electroautomatica.ru · FactoryLink 7.0 / Programmer’s Access Kit / 3 Table of Contents...

FactoryLink 7Version 7.0

Programmer’s Access Kit

FactoryLink 7.0

• • • • • • • • • • • • • • • • • • • • • • • • • • • •

© Copyright 2000 United States Data Corporation. All rights reserved.

NOTICE:

The information contained in this document (and other media provided herewith) constitutes confidential information of United States Data Corporation (“USDATA”) and is protected by copyright laws and international copyright treaties, as well as other intellectual property laws and treaties. Such information is not to be disclosed, used or copied by, or transferred to, any individual, corporation, company or other entity, in any form, by any means or for any purpose, without the express written permission of USDATA.

The information contained in this document and related media constitutes documentation relating to a software product and is being provided solely for use with such software product. The software product was provided pursuant to a separate license or other agreement and such information is subject to the restrictions and other terms and conditions of such license or other agreement.

The information contained in this document and related media is subject to change without notice and does not represent a commitment on the part of USDATA. Except for warranties, if any, set forth in the separate license or other agreement relating to the applicable software product, USDATA makes no warranty, express or implied, with respect to such information or such software product.

USDATA and FactoryLink are registered trademarks of United States Data Corporation in the United States and/or other countries. Open Software Bus is a registered trademark licensed to United States Data Corporation. All other brand or product names are trademarks or registered trademarks of their respective holders.

.

FactoryLink 7.0 / Programmer’s Access Kit / 3

Table of Contents

Programmer’s Access Kit

• • • •

Programmer’s Access Kit in this bookProgrammer’s Access Kit in the Programmer’sAccess Kit

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Structure of the Programmer’s Access Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11How to Use this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12List of Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Part I BASIC PAK

Programmer’s Access Kit at a Glance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Chapter 1 Programmer’s Access Kit Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

FactoryLink Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Required Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Required Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Installing the Programmer’s Access Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Compiling Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25For All Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Chapter 2 The Skeleton Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Integrating Skeleton into the FactoryLink System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Verify the FactoryLink Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Compiling and Executing the Skeleton Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Chapter 3 Run-Time Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Run-Time Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32FactoryLink Kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

4 / FactoryLink 7.0 / Programmer’s Access Kit

•

•

•

•

Programmer ’s Access Kit

Kernel Multi-User Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33USER and SHARED Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Application Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

FactoryLink Real-Time Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Structure of the Real-Time Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

FactoryLink Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41How FactoryLink Tasks Transfer Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41How FactoryLink Architecture Affects New Task Development . . . . . . . . . . . . . . . 43

Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Configuration Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46FactoryLink Directory Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Chapter 4 Configuration Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Configuring FactoryLink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Arrayed Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Element Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Element Name Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Predefined Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61OBJECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61XREF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Task-Specific . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

FactoryLink Application Directory ({FLAPP}) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Chapter 5 Constructing a FactoryLink Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Setting up the Configuration Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Convert Database Tables to CTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Writing the Run-Time Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Creating a Configuration Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Design the Database Table(s) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Create the Attribute Catalog(s) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73XLATES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75TASK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75CT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75EDIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76



VALIDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77PANEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78FIELD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79HEADING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81RELATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82DESC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83DOMAIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83SELECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84SEQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85END . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Naming Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Associating Help with the Task Attributes Catalog . . . . . . . . . . . . . . . . . . . . . . . . 97Executing an Editor Program from the Configuration Manager . . . . . . . . . . . . . 98Create the KEY Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Informing FactoryLink about the Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Testing the Configuration Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Viewing Contents of a Configuration Database without FLCM . . . . . . . . . . . . . 103

Creating a Single Point Configuration Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Extending the Single Point Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103AC file Language Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Using PAGEDIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Adding Help to Your Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Preparing Configuration for Run Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Create the CTG Conversion Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118TABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119HEADER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120DOMAIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121FIELD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121SKIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124SORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Creating FactoryLink Configuration Tables (CTs) . . . . . . . . . . . . . . . . . . . . . . . 125Debugging the Conversion Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Writing the Run-Time Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129


•

•

•

•


Kernel Check (Conditional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130New Configuration Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

The RTM File and Task Bumping Determination . . . . . . . . . . . . . . . . . . . . . . . . . 130Termination Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Orderly Shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Message Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Task Program Skeleton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Chapter 6 PAK Library Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Kernel Interface Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Task/Kernel Session Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Database Access Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Calling and Return Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

CT Access Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Object CT Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Overview of Object CT Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Overview of the Object CT API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Direct Tag Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Direct Tag Library Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156The FLDTP API Exit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Normalized Tag Reference Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Overview of FLNTAG Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Overview of the FLNTAG API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166FLNTAG Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168FLNTAG Function Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Path Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Path Name Building and Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Path Name Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Use of Environment Variables in Path Names . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Allocating/Destroying a Normalized Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Converting To/From a Normalized Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Modifying an Existing Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Creating/Deleting Directories and Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173Searching for Matching Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173Getting File Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Message Translation Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176



Overview of Message Translation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Loading Translation Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Translating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Managing Multiple Translation Trees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Extended Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Chapter 7 PAK API Reference Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Chapter 8 FactoryLink Menu Creation Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279Starting FactoryLink Menu Creation Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279User Interface Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280Quick Start Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281Adding Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Configuring Display Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285Configuring Action Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

Browsing Node Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Using Custom Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

Part II Configuration PAK

Configuration PAK at a Glance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

Chapter 9 Configuration PAK Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Required Hardware and Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

Chapter 10Configuration Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Configuration Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Configuration Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301Data Structure Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

Chapter 11Configuration PAK Library Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

Configuration Session API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306Attribute Catalog API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309


•

•

•

•


What is an Attributes Catalog (AC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309Accessing CDBs Defined Within an AC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Configuration Database API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313Interrogating a CDB Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313Reading Configuration from a CDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318Writing Configuration to a CDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321Multi-user Access to a CDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Object Database API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331Locating the Object CDB Handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331Reading Tag Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

Exception Handling API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340Return Codes and Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340Validation Error Reporting for Inserts and Updates . . . . . . . . . . . . . . . . . . . . . . 343

Chapter 12The Configuration Database Active-X Component . . . . . . . . . . . . . . . . . . . 345

Using the CFGPAK OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346The OBJPACK Sample Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

Chapter 13Configuration PAK API Reference Library . . . . . . . . . . . . . . . . . . . . . . . . . . 351

flCfgCDB_select_previous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

Part III RAPD PAK

RAPD PAK at a Glance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397

Chapter 14RAPD PAK Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399

Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400

Chapter 15RAPD Principle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

Compiling with the IMX library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

Chapter 16IMX Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403

Mailbox Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404mm_msg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405mm_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409



mm_user1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410mm_user2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410

Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411Dataset Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411Datasets Defined in an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411Passing and Processing a Dataset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413

I/O Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415The Block Read Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415Block Write Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418

Exception Write Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422Normal Exception Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422Unsolicited Receive Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424

Data Directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427Combinations of CDE Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428Converting IMX Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429

IMX and LANS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

Chapter 17Writing a RAPD Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

IOX - Driver Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437Error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438

Chapter 18IMX Reference Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443

General IMX Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443IMX Header Functions (IMXHDR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444IMX System Functions (IMXSYS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444IMX Message Functions (IMXMSG) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445IMX Dataset Functions (IMXDS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445IMX Data Manipulation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

IMX APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

PAK Conversion Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479

Converting Pre-FactoryLink 7.0 PAK Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479Adding Multilingual Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479Automated Conversion of Pre-6.0.4 Driver or PAK Task . . . . . . . . . . . . . . . . . . . . . . . 481

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483


•

•

•

•


• • • • • • • • • • • • • • • • • • • • • • • • • • • • • •

PrefacePURPOSE

The FactoryLink 7.0 Programmer’s Access Kit is a collection of software tools for use in the design and construction of FactoryLink-compatible tasks.

This guide is prepared to present the technical information programmers of these systems need to complete their applications.

The following guidelines help focus our purpose and goals to meet customer requirements:

• Accuracy is paramount—This FactoryLink documentation must provide accurate and reliable information and procedures.

• Time is valuable—This FactoryLink documentation must guide the programmer through what he/she needs to know quickly and efficiently.

AUDIENCE

The major audience of this guide is programmers who design and construct programs to

• Create new tasks that perform functions not performed by standard FactoryLink tasks.

• Develop communications interfaces to computers or devices for which standard interface tasks are not already developed.

In addition, FactoryLink Customer Support Services personnel use the procedures and examples included here to help you develop and troubleshoot your applications.

STRUCTURE OF THE PROGRAMMER’S ACCESS KIT

The FactoryLink ECS Programmer’s Access Kit is part of the Additional Manuals in the overall FactoryLink Documentation Set. For the structure of the entire Documentation Set, refer to the Preface in FactoryLink ECS Fundamentals.

This manual is divided into three major parts:

• Basic PAK (PAK)

• Configuration PAK (CFIGPAK)

• Rapid Application Protocol Driver PAK (RAPD PAK)

HOW TO USE THIS GUIDE

The material in this guide is presented in learning, then performance order. We recommend you become familiar with the complete procedure before you develop your application.

PREFACEConventions


•

•

•

•… at a Glance

Located within each part of this guide is a section named … at a Glance. This section provides a quick key to locations to find information to perform the procedures detailed in that part with hypertext links to those locations.

CONVENTIONS

The material in the Documentation Set adheres to the guidelines published in The Digital Technical Documentation Handbook by Schultz, Darrow, Kavanagh, and Morse; Developing International User Information by Jones, Kennelly, Mueller, Sweezy, Thomas, and Velez; and corporate style guidelines.

The FactoryLink ECS Programmer’s Access Kit is also referred to as the Programmer’s Access Kit. It uses the following conventions.

Convention Description

… Horizontal ellipsis points indicate the omission of material from an example. The information is omitted because it is not important to the topic being discussed.

.

.

.

Vertical ellipsis points indicate the omission of information from an example or command format. The information is omitted because it is not important to the topic being discussed.

italic type Italic type is used to denote user-supplied variables in command examples.Italic type also sets off references to specific documents.

monospace type Monospace type is used to denote command names and code examples or example output.

bold monospace type Bold monospace type is used in command examples to indicate words that must be typed literally.

sans serif type Sans Serif type is used to set off field names, button names, and keys on the keyboard.

press nnnnn Press is used to denote a key on the keyboard. The key name will appear in a sans serif type.

PREFACEConventions


Example Syntax

Example syntax using these conventions is provided below:

command input_file [input_file…] {a|b} output_file

click nnnnn Click is used to denote a button on the screen. The button name will appear in a sans serif type.

Shift+F1 The + indicates the keys must be pressed simultaneously.

Shift+F1 indicates you hold down the Shift key while you press another key or mouse button (indicated here by F1).

Other key combinations are presented in the same manner.

F1 F2 F3 The space between the key callouts indicates press and release.

The key sequence F1 F2 F3 indicates you press and release F1, then F2, and then F3.

Other key combinations are presented in the same manner.

File>Open The > indicates a progression through a menu sequence.

File>Open indicates you choose Open from the File menu to perform the required action.

Other menu sequences are presented in the same manner.

FLAPP\user\drw\mydrw.g The \ indicates the directory structure for the listed file.

FLAPP\user\drw\mydrw.g indicates the drawing file mydrw.g is located in the drw sub-directory of the user sub-directory to the FLAPP directory.

Other directory structures are presented in the same manner.


[ ] Brackets indicate an optional argument. You can choose none, one, or all of the options.

{ } and | Braces indicate a choice. You must choose one of the elements. The vertical bar separates choices within braces.


PREFACEList of Abbreviations


•

•

•

•where

command is typed as it is displayed in the syntax.

input_file indicates a variable the user supplies.

[input_file…] indicates the user can optionally supply multiple input file names, each name separated by a space.

{a|b} indicates either the a or b must be specified as an argument.

output_file indicates the user must specify an output file.

LIST OF ABBREVIATIONS

The following abbreviations are used in this guide.

Abbreviation Description

AC Attribute Catalog.

API Application Programmer’s Interface.

APPEDIT Application Editor.

ASC ASCII.

BIN Command files.

CDB Configuration database files.

CDE Code extension.

CFGPAK Configuration Programmer’s Access Kit.

CM Configuration Manager.

CML Compiled Math & Logic.

CPU Central Processing Unit.

CT Configuration tables.

CTG File extension for conversion scripts.

CTGEN Configuration tables script files utility.



DCT External Device Interface configuration table files.

DRW Graphics and PowerVB directory.

DE German.

DLL Dynamic Link Library files.

DTP Direct Tag Processing.

EDI External Device Interfaces.

EN English.

EXP File extension for output of configuration manager export.

FL FactoryLink.

FLAPP FactoryLink Application.

FLCM FactoryLink Configuration Manager.

FLIB FactoryLink library.

FR French.

FLINK FactoryLink System Files.

FMT File extension for report formats.

G*/GP*/PL* File extension for graphic and PowerVB files.

GUI Graphical User Interface.

H File extension for header files.

ID Identification.

IMX Intertask Mail Exchange.

INC Header files for C programs.

INSTALL Files used during installation.

IOX I/O translator.




•

•

•

•

IPC Inter-process communications.

KEY Text files.

LAN Local area network.

LIB Library files.

LOG Error log files.

MDX File extension for indices used by Configuration Manager.

MPS Multi-platform save.

MSG Message files.

NET Node.

PAK Programmer’s Access Kit.

PLC Programmable Logic Controller.

PDEF Program definition.

PRG File extension for Math & Logic procedures.

PROCS Math & Logic procedures.

RAPD Rapid Application Protocol Driver.

RCP Directory for files created by the Batch Recipe task.

RPT Directory for report formats and files.

RTDB Real-time Database.

RTU Remote Terminal Unit.

SEQ Sequence number.

SKEL Skeleton Task.

SPOOL Subdirectory used by Print Spooler task.

SQL Structured Query Language.


Getting Help


GETTING HELP

Contact your Sales or Customer Support Representative for help troubleshooting problems.

Also, help files are included for each configuration panel. Click Help on the panel menu bar to access these files.

SRC Programmer’s Access Kit files.

TXT Extension for message files.


Getting Help


•

•

•

•

• • • • • • • • • • • • • • • • • • • • • • • • • • • • • •

Part I

19

Part IBASIC PAK


• • • •

Programmer’s Access Kit at a Glance

Using Programmer’s Access Kit

For details on performing the following steps... Go to...

1. Read what the Programmer’s Access Kit does, about FactoryLink environment variables, required hardware and software and compiling programs.

Chapter 1, “Programmer’s Access Kit Overview“

2. Verify the Skeleton Task is both functional and integrated into your FactoryLink system.

Chapter 2, “The Skeleton Task”

3. Read about Run-Time Architecture, including the Run-Time Manager, Kernel, Real-Time Database, FactoryLink tasks, triggers, the Configuration Manager, and FactoryLink Directory Organization {FLINK}.

Chapter 3, “Run-Time Architecture”

4. Read about Configuration Architecture, including configuring FactoryLink and FactoryLink Application Directory.

Chapter 4, “Configuration Architecture”

5. Read about Constructing a FactoryLink task, including an overview, guidelines for task design, creating the configuration environment, the run-time requirements, and the task program Skeleton.

Chapter 5, “Constructing a FactoryLink Task”

6. Read about Library Services, including the Kernel interface, CT access, object CT access, direct tag processing, normalized tag reference, path manipulation, and message translation.

Chapter 6, “PAK Library Services”

7. Read about the API Reference Guide. Chapter 7, “PAK API Reference Library”


•

•

•

•

1

Pro

gram

mer’s A

ccess K

it Overview


• • • •Chapter 1

Programmer’s Access Kit Overview

The FactoryLink Programmer’s Access Kit (PAK) is a collection of optional FactoryLink software tools and related documentation for use in the design and construction of FactoryLink-compatible tasks.

PAK allows you to take full advantage of FactoryLink’s open architecture. This manual describes the C-language calling conventions; however, you can develop programs using any language that supports these calling conventions. Customer-written programs have full access to FactoryLink’s real-time database and operate in conjunction with other FactoryLink programs.

Caution: The structure of FactoryLink provides an architecture that supports an arbitrary number of languages, not just English, French, and German. Test for the availability of a particular language by checking the subdirectories under the %FLINK%\DLL directory. The FactoryLink utility, FLSETLNG, assumes any subdirectories added to the DLL directory are additional language implementations. If additional languages are not implemented correctly, FactoryLink produces unpredictable results.

Use the FactoryLink Programmer’s Access Kit to:

• Create new tasks that perform functions not performed by standard FactoryLink tasks

• Develop communications interfaces to computers or devices for which standard interface tasks are not already developed

Unlike any other open architecture system, FactoryLink fully integrates a customer-written task into the FactoryLink environment. FactoryLink’s Configuration Manager (FLCM) fully supports new tasks with full-screen editing, context-sensitive help, and documentation utilities.

PROGRAMMER’S ACCESS KIT OVERVIEWFactoryLink Environment Variables


•

•

•

•

FACTORYLINK ENVIRONMENT VARIABLES

FactoryLink tasks depend on the values of various environment variables to determine many aspects of their interactions with files and the Real-Time Database. FactoryLink must know where the FactoryLink application, FactoryLink system files, and FactoryLink software license information are located. Because multiple FactoryLink applications can run concurrently and because FactoryLink software is designed to run in both single-user and multi-user environments, the following environment variables must always be set to appropriate values:

{FLINK} Base directory of FactoryLink system installation

{FLAPP} Base directory of application files

{FLOPT} Directory where software licence files reside

{FLNAME} Name of application that is running

{FLDOMAIN} Domain name

{FLUSER} User instance name

These variables are set to default values during installation.

REQUIREMENTS

Required Hardware

PAK is an option used in conjunction with a FactoryLink Development System. The hardware requirements specified in the FactoryLink Product Matrix (included on the documentation CD) also apply to the Programmer’s Access Kit option. Refer to the FactoryLink Release Notes for information on which compiler to use.

Required Software

PAK requires specific versions of software tools not included with PAK. See the FactoryLink Product Matrix for a list of FactoryLink software requirements for Windows NT and Windows 95 users.

PROGRAMMER’S ACCESS KIT OVERVIEWInstalling the Programmer’s Access Kit


1

Pro

gram

mer’s A

ccess K

it Overview

INSTALLING THE PROGRAMMER’S ACCESS KIT

Install the Programmer’s Access Kit as an option during the installation procedure for FactoryLink following the procedure explained in FactoryLink Installation Guide.

COMPILING PROGRAMS

PAK provides a command script for all supported compilers named setup<platform>.bat that sets the environment variables required to successfully build the example programs. This command script must be executed prior to building any of the shipped examples. The set up script resides in directory {FLINK}/src/examples/skel.

Each example program is accompanied with a makefile. Execute the compiler make facility at the command prompt to build the example programs. While PAK does not provide any pre-built projects for use within the compiler integrated developer’s environment, you should be able to create one with limited effort.

FOR ALL USERS

Whenever you receive a new version of FactoryLink, you must relink all tasks to the new libraries. Also, you cannot run old FL tasks with the new ones. You must run all new FL tasks.

Caution: Failure to heed these concerns will almost certainly result in an immediate crash of your entire application.

PROGRAMMER’S ACCESS KIT OVERVIEWFor All Users


•

•

•

•

2

Skeleto

n Task



The Skeleton Task

The Skeleton Task serves as a framework to build a custom task designed to meet your unique needs. Ensure the Skeleton Task is both functional and integrated into your FactoryLink system before beginning the PAK task construction.

The source code and support files for the Skeleton Task reside in the directory {FLINK}\src\examples\skeleton and include the following files.

Skeleton Files Description

skel.ac Skeleton Task attribute catalog.

skel.ctg Skeleton Task configuration table conversion script.

skel.c Skeleton Task source code.

skel.txt Skeleton Task error message translation file.

makefile.<platform> Skeleton Task make file. Its extension varies by plaftorm.

setup<platform>.bat Environment setup script (invoked prior to compilation).

skel.rc, skel.ico

(Windows only)

Skeleton Task icon for when it is minimized.

THE SKELETON TASKIntegrating Skeleton into the FactoryLink System


•

•

•

•

INTEGRATING SKELETON INTO THE FACTORYLINK SYSTEM

Perform the following steps to integrate the skeleton development components:

1. Copy the Attribute Catalog skel.ac into the AC directory: {FLINK}\ac.

2. Make the Skeleton Task AC known to the FactoryLink system.a) With a text editor, append a new line skel.ac to {FLINK}\ac\titles.b) From the system prompt, execute {FLINK}\bin\acctmgr -c -d.

3. Copy the conversion script skel.ctg into the CT directory: {FLINK}\ctgen.

4. Copy the on-line configuration handling script skel.rtm to the CT directory: {FLINK}\ctgen.

5. Make the Skeleton Task conversion script known to the FactoryLink system.a) With a text editor, add the line skel: skeltrig skeltags to {FLINK}\ctgen\ctlist.

6. Copy the translation file skel.txt into the message directory: {FLINK}\msg\{FLLANG}.

To verify the Skeleton Task has been successfully integrated into the development environment:

• Create a new application (FLNEW)

• Set the FLAPP environment variable to this application

• Invoke the Configuration Manager (FLCM)

Verify the FactoryLink Integration

Perform the following steps to verify the integration:



2

Skeleto

n Task

1 Double click on the Skeleton Task entry to display the Trigger Tags panel.

2 Create a row in the Triggers Tag panel in the SHARED domain with the Table Name as A and the Trigger Tag as skeltrig_a. Accept the defaults when creating the trigger tag.

3 Close the skeleton panel and double click on the System Configuration choice in the FLCM Main Menu. Again, configure a row for the Skeleton Task in the SHARED domain. The row should be the same as the one pre-configured for the RTMON task, except the tag dimension indices should be set to the next available slot. A common technique is to copy and paste the RTMON line and then change the array indices and task specific fields to reflect the new skel task. Also, the following fields need to be set to the values shown.

4 Exit FLCM, run FLRUN, and then shutdown the application. Verify this sequence generates the file {FLAPP}\shared\ct\skel.ct.

You have now confirmed the successful integration of the Skeleton Task into the FactoryLink system.

Compiling and Executing the Skeleton Task

Next, confirm the run-time environment is functional and verified. Perform the following steps to do so:

1. Prepare the compilation environment.a) Execute the environment setup script appropriate for the platform.

Flags Task Name Description Executable File

FR SKEL Skeleton PAK Task bin/skel



•

•

•

•2. Build the executable.

b) Invoke the compiler’s MAKE utility on the skeleton makefile.

For example, in Windows NT, the following commands are issued at the operating system prompt in order to build the Skeleton Task.

>cd %FLINK%\src\examples\skeleton

>setupnt

>nmake -f makefile.nt

The makefile places the built executable into the correct location within the FactoryLink system ({FLINK}\bin). Run the application created earlier a second time to verify the task is functional. When the graphics for the application are displayed, switch to the SHARED Run-time Manager screen (either 1 or 2) that has the SKEL task listed. The screen indicates the task is running.

To verify the SKEL task is working as expected, use RTMON to write a 1 to the skeltrig_a tag. A message displays in the Skeleton Task Message field that effectively verifies the Skeleton Task has read its configuration and is correctly processing it.

3

Ru

n-T

ime A

rchitectu

re



Run-Time Architecture

FactoryLink is a modular system of individual tasks that perform separate functions. These tasks communicate and share data with one another through the Real-Time Database managed by the FactoryLink Run-Time Manager and Kernel. This system provides the following advantages over systems relying on real-time inter-process communications (IPC) through passing buffers or sharing files:

• Tasks maintain their independence and inherent compatibility with one another.

• Data formats for interfaces will not change unpredictably as the maintenance programmer changes.

• Tasks can hand off the inter-process communication to the database function, which acts as an intermediary, meaning less time is spent waiting for another task to acknowledge error-free receipt of data.

• Functions, conditions, or events can be related through the use of a common element since each task has access to the same global elements.

FactoryLink allows you to create custom applications by selecting, configuring, and linking different programs to exchange information freely in real time.

FactoryLink operation involves the following:

• Run-Time Manager

• Kernel

• Real-Time Database

• FactoryLink Tasks

• Triggers

• Configuration Manager

• FactoryLink Directory Organization ({FLINK})

RUN-TIME ARCHITECTURERun-Time Manager


•

•

•

•

RUN-TIME MANAGER

The Run-Time Manager supplied with FactoryLink orchestrates the run-time environment. It is a FactoryLink task that runs concurrently with other tasks to start, monitor, control, and shut down the concurrent execution of all FactoryLink tasks.

The Run-Time Manager reads the System Configuration table [sys.ct]to determine the startup criteria for each task. The Run-Time Manager communicates with each task by sending commands to and reading status information from the Real-Time Database. Each task must monitor the command objects so the task shuts down when instructed to by the Run-Time Manager.

The Run-Time Manager interacts with the other tasks within a specific domain through the FactoryLink API and the Real-Time Database as shown in the following figure.

Figure 3-1 Run-Time Manager Data Flow Diagram

FactoryLinkApplication

Tasks

Run-TimeManager

FactoryLinkReal-timeDatabase

WriteRead

WriteRead

SYS.CT

*.CT

Run-Time Manager Data Flow Diagram

RUN-TIME ARCHITECTUREFactoryLink Kernel


3

Ru

n-T

ime A

rchitectu

re

FACTORYLINK KERNEL

The FactoryLink Kernel is a software module that creates the Real-Time Database in memory and serializes access to the memory so tasks can communicate with each other. When you start the FactoryLink Run-Time system, the Run-Time Manager creates the shared memory using the Kernel Services. Other tasks also use the Kernel Services to access the shared memory as they start.

Kernel Multi-User Capabilities

The following aspects of the FactoryLink Kernel allow multiple independent users of a FactoryLink application:

• Provide global memory areas for real-time data

• Provide private, per-user memory areas for real-time data (an instance of the USER domain)

• Allow up to 31 tasks for each user’s instances’ collection of tasks

• Allow multiple applications to run simultaneously

USER and SHARED Domains

Domain

FactoryLink supports the concept of shared and private data areas by the separation of data access into domains. The SHARED domain is the shared portion of the Real-Time Database and the collection of shared processes that have access to that data. The USER domain is an instance of the user Real-Time Database and the set of all the user processes having access to that Real-Time Database. Multiple USER domains each have their own set of user processes. Each can access both the SHARED Real-Time Database and the USER instance of the Real-Time Database.

When FactoryLink runs, the entire Real-Time Database is created, including the SHARED portion and all Real-Time Database USER instances. Next, the SHARED Run-Time Manager initializes the SHARED Run-Time Database and starts the SHARED processes. As USER instances start, each USER Run-Time Manager initializes its instance of the USER Real-Time Database and starts an instance of all USER processes.

Within the starter application (FLNEW), default domain associations are made in the System Configuration Table. These defaults determine which domain a task is associated with at run time. Some tasks are associated with both SHARED and USER domains. Review the default domain associations during application planning to verify they are compatible with current needs. These default associations may be changed if an application has special requirements.



•

•

•

•FactoryLink tasks use Real-Time Database elements (tags) to control tasks. User database elements are duplicated for each FactoryLink user. The subset of the Real-Time Database duplicated on a per-user basis is known as the USER domain.

The multi-user architecture allows duplicate USER domains by allocating an array of pointers to database segments for each user. This allows the element numbers (indices into the pointer array) themselves to remain the same for each user while referencing a private data area for each user.

Some FactoryLink tasks monitor and control processes, such as a PLC driver task, that require the process data values be the same for all users. The subset of the Real-Time Database shared by all users is known as the SHARED domain.

Application Instances/ Identification

Since multiple copies of a FactoryLink task may be running concurrently, a task must identify itself to the Kernel. The task must specify the application, domain, and user instance as well as the task name.

Each application instance is specified by its invocation name. The invocation name is a character string of up to 16 characters. The invocation identifies an instance of the Real-Time Database and is used to locate the memory segment the kernel is stored in. The Run-Time Manager refers to the invocation name stored in the environment variable {FLNAME} and stores it in the tags FLNAME_U or FLNAME_S, depending upon the domain.

The domain within an application is specified by the domain name. The domain name is a character string of up to 16 characters and is used to determine which portion of the Real-Time Database the task has access to: either the elements in the SHARED domain or elements in one of the duplicate USER domains. In addition, the task uses the domain name to determine which CT files should be processed. The Run-Time Manager refers to the domain in the environment variable {FLDOMAIN} and stores it in the tag FLDOMAIN_U or FLDOMAIN_S, depending upon the domain.

The user instance is specified by the user name. The user name is a character string of up to 16 characters and is used to determine which instance of the duplicate USER portions of the Real-Time Database the task has access to. The Run-Time Manager refers to the environment variable FLUSER and stores it in the tag FLUSER_U or FLUSER_S, depending upon the domain. The FLUSER environment variable must be unique for each user of the application.

When a FactoryLink application is started, the Run-Time Manager must be supplied with the invocation name, domain name, and user name on the command line or through environment variables. All sub-processes the Run-Time Manager creates inherit these environment variables.



3

Ru

n-T

ime A

rchitectu

re

Domain Tables

The domain table in the Configuration Manager contains the definition of domains in the application. Currently, two domains are supported: SHARED and USER. The definition of these domains includes the number of allowed instances as well as domain-wide persistence attributes.

The Configuration Manager has a domain selection feature that must be set before tasks are configured. The default is SHARED. If the run-time domain associations do not match the configuration domain associations, the application will not run as intended.

Domain Associations

Domain designations are critically important. Before each task begins to run, the associated domain is defined as an environment variable. Typically, the task inherits the environment from the Run-Time Manager when the Run-Time Manager starts the task. This variable must match one of the previously defined domain values. Two types of domain relationships are possible:

• A task may be designed to run as SHARED. All tables and database elements are associated with the SHARED domain. At run time the task runs as a shared entity with one set of elements for all users.

• A task may be designed to run as USER. You have a private copy (domain instance) of the task for every user. The tasks may use both the SHARED and USER Run-Time Database elements. At run time all user domain instances are identical when generated; however, individual user actions are independent, and the resulting data is stored in a Real-Time Database unique to each operator.



•

•

•

•Application Example

The following example of one of numerous application configurations possible illustrates one way a FactoryLink application may be configured.

Single Application/Multiple Users

In the following example, you have created an application that allows multiple operators to run separate user instances of the same application in which each operator has his own USER domain tasks and Real-Time Database.

Figure 3-2 Domains: Single Application/Multiple Users

USER

USER

SHARED

RUN-TIME ARCHITECTUREFactoryLink Real-Time Database


3

Ru

n-T

ime A

rchitectu

re

FACTORYLINK REAL-TIME DATABASE

The Real-Time Database is the area of the Kernel’s shared memory used to store the current value of the application elements. It exists only in memory and does not persist between subsequent invocations of the FactoryLink system.

Structure of the Real-Time Database

The Real-Time Database is made up of arrays and pointers. Each array consists of up to 65535 elements of a single data type. Whenever you define an element, the system prompts you to identify the data type of the element by choosing one of FactoryLink predefined data types. The following table shows the storage capacities, ranges, and accuracies of each data type.

Use the following formulas to determine memory requirements:

Formula = storage requirement for an element defined for the SHARED domain:

(N - 4) + (4 x I)

where

Data Type Value Storage in User Area

Storage in Kernel Area

Value Range and Accuracy

Digital (Boolean) 1 bit * 2 bytes 12 bytes 1 (ON) or 0 (OFF)

Analog (Short integer) 2 bytes * 2 bytes 14 bytes -32,768 to 32,767 (signed)

Long Analog (Long integer) 4 bytes 4 bytes 16 bytes -231 to 231 -1

Floating point (IEEE standard/double precision)

8 bytes 8 bytes 20 bytes +/-10-308 to +/-10308

Message (String) 0 to 65535 bytes

0 to 65535 bytes

20 bytes per message + storage of data

ASCII or arbitrary binary data

Mailbox (Variable- length data, organized as a queue)

0 to 65535 bytes

0 to 65535 bytes

20 bytes per message + storage of data

Arbitrary binary data



•

•

•

•N Is the storage in Kernel area from the table above.

I Is the number of instances (shared + user).

Example:

A SHARED domain long analog element in a system with a maximum of two USER instances:

[20 bytes (from table) - 8] + {8 x [1(shared) + 2 (user)]} = 40 bytes

Formula = storage requirement for an element in the USER domain:

(N x I)

where

N Is the storage in kernel area from the table above.

I Is the number of instances (shared + user).

Example:

A USER domain floating-point element in a system with a maximum of two USER instances:

24 bytes (from table) x [1 (shared) + 2(user)] = 72 bytes

The FactoryLink Kernel uses data types and element numbers to read from or write to elements in the Real-Time Database.

Structure of an Element

An element consists of the following items:

• One or more bits containing the element value

• Set of change-status bits (change-status word)

• Set of wait bits (wait-status word)

• Set of reserved bits

FactoryLink pre-allocates a single bit to each potential client task in each of these status words. Each domain instance has potentially 31 possible processes. The 32nd bit is a digital tag value or unused.

Change-Status Bits

For each element, one change-status bit exists for each potential client process. The read-call and write-call functions use the change-status bits within the FactoryLink Kernel to indicate



3

Ru

n-T

ime A

rchitectu

re

changes in an element value. The value of the change-status bit can be either ON (equal to 1) or OFF (equal to 0).

FactoryLink tasks write information to elements through either

• Write call

• Forced-write calls

Tasks use the Kernel Service’s write-call function to update a value of an element. This function first determines whether the element value changed. If the new value differs from the old, the write-call function sets each of the element change-status bits to 1 (ON) and stores the new value in the element; however, if the comparison determines the new value for the element is identical to the old, nothing changes. This method saves processing time because tasks watching the element will not waken to process unchanged values.

Alternatively, the writing task can also use the Kernel Service’s forced-write function. This function does not compare old and new values. Instead, the forced-write call function assumes the element has changed and sets all of the element change-status bits to ON as it stores the new value, even if the updated value being assigned to the element is the same as the old. Forced writes are useful when you need to trigger processes setting the element change bit but do not wish to change the actual contents of the element or when an element needs to be processed a second time, even if its value has not changed.

Use write calls except when the forced-write is specifically needed.

FactoryLink tasks read information from elements through

• Read calls

• Change-read calls

• Change-wait calls

The read-call function always returns the current value of the element to the calling process regardless of the value of the element change-status bit assigned to that process.

When a task makes a change-read-call, the reading task requests change-status information about specific elements. If the function finds that the change-status bit of an element has been



•

•

•

•set since it was last read, the function informs the calling task it has found a changed element and returns the value of the first changed element found. If the change-status bits have not been set since the last read for any of the specified elements, the change-read-call function returns a code indicating this to the calling task. This method blocks the calling routine’s processing for less time than reading and comparing the values of all the elements.

When a task makes a change-wait call, the reading task uses the change-wait-call function within the Kernel to request change-status information about specific elements. Once a task makes its call, the task then hibernates while waiting for an element to change. When a task is asleep, it uses no CPU cycles. The task wakes when any one of the specified elements have changed and/or have had their change-status bits set to 1 (ON) by another task since the last reading. In other words, this call blocks the calling process until at least one of the specified elements change-status bits are toggled.

Regardless the method of reading an element, the act of reading an element resets the element change-status bit associated with the reading task to OFF by writing a 0 to the task change-status bit in the element. As successive tasks read an element, they toggle the change-status bits in the element, one by one, to OFF.

The Kernel maintains the change-status bits in a manner transparent to the tasks; however, you can use these bits in the Math & Logic task.

For example, you can write a Math & Logic procedure that uses the ? operator to determine whether the value of an element has changed and then take an action.

Change-status bits optimize system performance in the multi-tasking environment. FactoryLink tasks use change-status bits as exception flags and the Kernel acts as an exception processor.

Caution: Exception processor terminology is uniform across all FactoryLink documentation and should not be confused with the traditional use within the industry of the term exception processing to mean error handling or CPU exception recovery.

This allows FactoryLink tasks to perform functions on an exception-only basis or only on those elements whose values have changed rather than continuously reprocessing unchanged information. This method results in increased software performance.

Wait bits: For each element, one wait bit exists for each possible client process. When the client is currently waiting to read the specified element, the value of the bit is 1 (ON); otherwise, the value is 0 (OFF).

RUN-TIME ARCHITECTUREFactoryLink Tasks


3

Ru

n-T

ime A

rchitectu

re

FACTORYLINK TASKS

FactoryLink tasks are programs that read from and write to the Real-Time Database allowing for an exchange of information among the tasks. You use the configuration tables to specify the elements each task reads or writes. A task is only aware of the elements it is reading and writing, not of other tasks; therefore, it does not know which task wrote the data it is reading from the database nor can it know which task is reading the data it is writing to the database.

An application task calls functions to perform the following FactoryLink operations involving the Real-Time Database:

• Lock the database

• Unlock the database

• Read one or more database elements

• Write one or more database elements

• Determine whether a database element has been modified by another task since it last read the element

• Sleep until any one member of a list of specific database elements is modified

• Access miscellaneous utilities

How FactoryLink Tasks Transfer Data

Data transfer is based on reads, writes, and change reads of information in the Real-Time Database. All information, either transmitted to or collected from outside sources, goes through the Real-Time Database on its way to its final destination.

Any task can use any element in the Real-Time Database as long as the data type and domain of that element matches the type required for the indicated operation. It is possible— even beneficial— for two tasks to use the same element. When this occurs, both tasks share the information stored in the element.

Although some tasks may only read or write to elements, most tasks have both read and write access to the elements. Remember all elements are global, so any task can use any element as long as that element data type matches the type required for the indicated operation. It is possible for two tasks to use the same element, sharing responsibility for updating the information stored in the element.

It is important to plan and configure the system so read and write operations to the Real-Time Database are predictable. For example, if two tasks are configured to write simultaneously to the same element, it is impossible to know which task is responsible for the data in the element. Even though it is sometimes desirable to have such a capability, most applications should be designed so only one writer task and one or more reader tasks function for any particular element.



•

•

•

•Transfer Methods

FactoryLink transfers data in three ways:

• Reading data from the Real-Time Database

A task reads the value of an element in the Real-Time Database to display it on a screen, transmit it to an external device, or send it along to another task.

• Writing data to the Real-Time Database

A task writes information to an element in the Real-Time Database as the result of an operator input, a read of an external device, or an input from another task.

• Change-read operations

A change-read operation is a block read of the Real-Time Database that returns only those elements whose values have changed since the last read operation. This is known as exception processing. The flags contained in the structure of FactoryLink elements make this possible. Change-reads optimize system performance because large blocks of data can be checked for change and because only the changed values are processed.

Data Transfer Examples

Reads, writes, and change-reads are generally performed in combinations.

Example 1. When you enter a new value from the keyboard, the Graphics Task gets the value and writes it to the element associated with the input object.

Example 2. The Graphics Task uses a change-read function that executes in a loop to determine whether element values linked to a screen display have changed. The function informs the task if no values have changed. The function returns the new value for the changed element from the Real-Time Database if a value has changed. At the completion of the execution of the loop, the task relinquishes the CPU to another process or task.

Example 3. The Batch Recipe task is configured to read values from a file and write them to associated elements in the Real-Time Database or read elements from the database and write their values to a file on the disk.

Example 4. A programmable controller task reads values from the programmable controller and writes them to the Real-Time Database. It can also read values from the Read-Time Database and write them to the programmable controller.



3

Ru

n-T

ime A

rchitectu

re

How FactoryLink Architecture Affects New Task Development

The following illustrates FactoryLink architecture.

ASCII Application/{FLAPP}/, MPS (ASCII)

ConfigurationDatabase Tables

/{FLAPP}/

Configuration Tables(Binary)

/{FLAPP}/{FLDOMAIN}/CT/*.CT

*Source

FLIB/{FLINK}/INC//{FLINK}/LIB/

FLSAVE/FLREST/{FLINK}/BIN/

FLRUN/{FLINK}/BIN/CTGEN.EXE

*Configuration TableGenerator Scripts

/{FLINK}/CTG/*.CTG

*Key Word Files

/{FLINK}/Key/{FLLANG}/*.KEY

*Attribute Catalogs/{FLINK}/AC/*.AC

Compile & Link/{FLINK}/BIN/TASK.EXE

Overview of FactoryLink Architecture

FactoryLinkConfiguration

Manager

* Denotes user-written with any text editor

Task

Run-TimeManager

FactoryLinkReal-TimeDatabase

Starts Run-Time Manager

SYS.CT

TASK.CT

Starts othertask



•

•

•

•The following table describes each part of the illustration, beginning with the upper left portion.

Item in Illustration Description

ASCII Application Any application can be saved to enable the importing/exporting of configuration data from one application directory to another (typically, from one platform to another).

FLSAVE/FLREST Utilities used to save/restore an application. Refer to “FactoryLink Utilities” in Fundamentals for additional information about these utilities.

Configuration Database (.CDB)

Tables that store information about the Real-Time Database elements. You must design these tables as part of task development. In this manual, configuration database tables are referred to as database tables.

FactoryLink Configuration Manager (FLCM)

Development system tool used to set up or configure an application.

Attribute Catalogs (.AC) Programmer-created ASCII text files that describe the database tables and the editing criteria for operator-entered data.

Key Word Files (.KEY) ASCII text files that 1) delimit valid entries for a database table field; and 2) provide binary value for conversion by CTGEN.

FLRUN Command that executes the FactoryLink Software System including the custom application. This command starts the Run-Time Manager task.

Configuration Table Generator Scripts

Programmer-created script files that tell the CTGEN utility (generate binary CT files) how to extract data from the database tables and combine it to produce a binary Configuration Table (CT) file at run time.

Configuration Tables (Binary) (.CT)

Binary files produced by the CTGEN utility at run time containing data extracted from the database tables.

Source Programmer-developed source code for a task.



3

Ru

n-T

ime A

rchitectu

re

Only portions of the FactoryLink architecture affect you directly. You must design the database tables for the task. These tables contain all information required to completely describe the application with the possible exception of operator-entered menu selections and/or commands.

Once the design is final, you must create an Attribute Catalog file for one or more database tables. The Attribute Catalog file represents one menu option on the Configuration Manager Main Menu. If the Attribute Catalog file references a KEY file, you must create a KEY file that provides the Configuration Manager with information on developer-entered key words placed in the database tables. Then, you must open the Configuration Manager and use it to test whether the Attribute Catalog file(s) and, if used, the KEY files, accurately reflect the desired database table design and editing requirements.

At run time the Run-Time Manager starts and the database tables are converted into one or more sorted binary files known as a CT file(s). When a task begins running, it reads its CT file to determine the elements to open and the actions to perform on those elements. You must write a configuration table generator script that describes how to extract data from the database tables and produce the CT file at run time.

The custom-developed program describes how the custom-developed task functions in relation to other tasks, including the Run-Time Manager.

Compile and Link Step to compile source code into object code and link object modules.

FLIB FactoryLink library. Collection of utility functions serving primarily to interface application and system programs to the FactoryLink Kernel.

Task Task that performs a required operation. Up to 31 tasks, including the Run-Time Manager, may be active concurrently per domain instance.

Run-Time Manager Task that monitors and controls other FactoryLink tasks using the services of the Real-Time Database.

FactoryLink Real-Time Database

Memory-resident array of information that exists only at run time.

Item in Illustration Description

RUN-TIME ARCHITECTURETriggers


•

•

•

•

TRIGGERS

Many FactoryLink tasks use digital elements to trigger certain actions. Events, such as read or write operations, can be configured to occur as the result of a combination of bit value and change-status flag value in a trigger element. A trigger element can be used as a trigger by more than one task.

Two conditions must exist for an element to trigger an event in existing FactoryLink tasks:

• Value of the element must be 1.

• Value of the change-status flag being read must be non-zero.

Note: Remember: trigger conditions are task dependent.

When a task reads a trigger element, the reading task sets its change-status flag to 0 and begins the operation designated by the trigger if the element value is 1 and has changed since the last time it was read.

Forced-writing a 1 to a digital element, even though it may not change the actual value of the element (if the element was already equal to 1), causes the events tied to that trigger to be triggered during the next read operation. If multiple tasks are to use the same element as a trigger, using the forced-write technique simplifies inter-task handshaking requirements.

You use trigger elements in many ways:

• Define Interval and Event Timer digital elements in the Real-Time Database for use as triggers

• Configure function keys as triggers

• Initiate a Math & Logic procedure by having Math & Logic create triggers of any data type

• Report or log data

• Read and write recipes

• Execute another program

• Cause a screen to be printed

• Initiate a network transfer

• Cause a new setpoint to be downloaded to a programmable controller

• Trigger separately each polled read function used by a programmable controller task

CONFIGURATION MANAGER

The Configuration Manager is a development system program used to set up or configure a FactoryLink application. It is used only for system configuration and application development.

RUN-TIME ARCHITECTUREConfiguration Manager


3

Ru

n-T

ime A

rchitectu

re

You create an application by specifying the elements created for each task and the actions each task performs on these elements. In the Configuration Manager, you enter data in one or more database tables for each task. The Configuration Manager normally invokes a default Panel Editor that provides a data entry panel for each of the database tables; however, the Configuration Manager may invoke specialized editors, such as the Application Editor, to handle non-textual configuration.

Advantages of using the Configuration Manager include reduction of development time for an application and having the same developmental look and feel as standard FactoryLink tasks.

RUN-TIME ARCHITECTUREFactoryLink Directory Organization


•

•

•

•

FACTORYLINK DIRECTORY ORGANIZATION

FactoryLink Program Directory ({FLINK})

The following files are located in the {FLINK} directory. The subdirectories containing program files are organized as follows.

Subdirectory File(s) Description of File(s)

\AC *.AC Text files that function as Attribute Catalogs to inform the Configuration Manager of the format of the database tables and to determine editing entry criteria.

\BIN Command files, executable program files, and related support files for each task.

\BLANK Blank {FLAPP} directory used by the FLBLANK utility to create a new application.

\CML * Compiled Math & Logic files.

\CTGEN *.CTG CT script files.

\DLL\en

\DLL\fr

\DLL\de

*.DLL Contains language specific DLL files.

\EDI … /* Subdirectory for External Device Interfaces (PLC drivers).

\INC *.H Header files for C programs.

\INSTALL Files used during installation.

\KEY\en

\KEY\fr

\KEY\de

*.KEY Text files that tell the Configuration Manager how to translate text table entries into binary values to be placed in a configuration table (CT) for the specified language.



3

Ru

n-T

ime A

rchitectu

re

\LIB *.LIB (WIN& )

*. a

Library files.

*.DLL WIN Dynamic link library files.

\MPS\en

\MPS\fr

\MPS\de

*.MPS Multiplatform save files for the specified language.

\MSG\en

\MSG\fr

\MSG\de

*.TXT Message files for tasks.

\RPT *.FMT Report formats.

\SRC … /* Programmer's Access Kit files.

Subdirectory File(s) Description of File(s)



•

•

•

•

4

Co

nfig

uratio

n

Arch

itecture



Configuration Architecture

This chapter highlights the following aspects of constructing tasks and integrating them with the rest of the FactoryLink system:

• Configuring FactoryLink

• FactoryLink Application Directory ({FLAPP})

CONFIGURATION ARCHITECTUREConfiguring FactoryLink


•

•

•

•

CONFIGURING FACTORYLINK

Configure FactoryLink by filling in configuration tables associated with different FactoryLink tasks. Define one or more elements, assigning each a symbolic element name and enter other static information required to define the function of the element(s). For instance, in the Interval Timer Information panel, you define an element with the symbolic element name (tag) sec1 and a value specifying the length of time between intervals. The element name serves to link the interval timer element to other FactoryLink tasks by making the state of the timer element accessible by other tasks.

This information allows tasks to read data from and write data to the Real-Time Database, providing developer-configurable communication links between FactoryLink tasks. Establishing these links is the essence of creating a FactoryLink application.

Enter information in a table by opening one or more screen displays or panels that provide predefined entry fields for information required for the task to function.

In general, two types of panels are used:

• Control panels

• Information panels



4

Co

nfig

uratio

n

Arch

itecture

• In a control panel, enter information that identifies and/or initiates an operation, such as a read or write.

• In an information panel, enter specific information about the values used in the operation defined in the control panel.

This is how the control and information panels for a particular task are related. For example, in the following sample Control panel, specify types and priorities of read and/or write operations performed.

Then, enter the DDE item names read or written and the names of RTDB elements to receive or supply information from/to the DDE source (MS Excel spreadsheet) in the following sample Information panel, which is associated with the previous Read/Write control panel.

A task may require both Control and Information panels or just an Information panel.



•

•

•

•Element Names

Each element has a unique, developer-defined, symbolic element name (tag). You assign these element names, one for each element used in the application during system configuration and the system stores them in a separate predefined data file. Element names are linked at run time with pointers to their associated elements, allowing their use by any task. Because the Real-Time Database is completely memory-resident and is organized as arrays and pointers when loaded at run time, FactoryLink does not have to keep track of element names stored as text strings. This, in part, accounts for FactoryLink’s high processing speed.

Element name assignment: During configuration you create and assign an element name to an element by defining at a minimum its name, data type, and possibly its domain dimension. If the element you referenced does not exist, the system automatically creates it. Once an element has been defined in this way, other tasks refer to this element using its element name, reading or writing data to or from the element at run time.

Valid tag names conform to the following grammar:

[<node>:]<name>[<dims>][.<ext>]

where

<node> Is limited to 8 characters.

<name> Is limited to 32 characters.

<dims> Is limited to 16 characters.

<ext> Is limited to 16 characters.

The maximum tag name length, including <node>, <name>, <ext>, and the separators : and . is 32. Legal characters for the <node>, <name>, and <ext> strings are

• {A-Z}

• {a-z}

• {0-9}

• {@$_}

These strings cannot begin with a number or contain spaces.

Users cannot directly create a tag name with extensions, such as abc.mymember. These are considered member tags. The Application Editor creates these automatically through the tag definition notebook. Currently, only member tags related to scaling and deadbanding are supported.



4

Co

nfig

uratio

n

Arch

itecture

Syntax Samples

• Sample element name: plc_readval

• Sample remote element name: serverl:plc_readval

• Sample arrayed element name: plc_readval[5][6]

• Sample member element name: plc_readval.raw

• Sample remote, arrayed, member element name: node name plc_readval [5][6].raw

Arrayed Elements

An element array is a block of elements of the same type. As such, it frees the developer from having to define large numbers of scalar elements separately. Certain FactoryLink tasks, such as Math & Logic and Database Browser, can detect the arrayed property of an element and can access the entire element array when given a reference to just one of its elements.

Defining Element Arrays

Define element arrays in a configuration table by using at least a two-part element name. A two-part element name consists of an alphanumeric string (the arrayed element name) followed by one set of square brackets containing an integer (array index) for each dimension of the array. Dimension refers to the capacity or size of the array. If an array has more than one dimension, it is called multi-dimensional, and each element will have as many array indices as the array has dimensions. Think of the Cartesian coordinate system in which both vertical and horizontal indices are specified to pinpoint a position on the spatial grid. A two-dimensional array is an array in which each of the elements is also an array and its elements are referenced by [row,column] pairs.

The array dimensions defined within the square brackets are the sizing factors that determine the number of elements in an array. For example, if you specify the size of a one-dimensional element array is 5, the Real-Time Database creates five separate elements referenced individually or as a group. Their array element names are the same, but they have different array indices.

The following is a sample arrayed element name:

set_temp[2][1]

Each set of square brackets represents a dimension or spatial characteristic of the element array, such as length, width, or height. When you define an element array in a configuration panel, a dialog displays showing default sizes for each dimension you can modify before pressing Enter.

The size of a default dimension is always one larger than the integer specified in the element name brackets because C arrays are indexed from zero to the specified dimension. For



•

•

•

•example, if the element name is tagname[0][0], the default dimension sizes displayed in the dialog are 1,1. If the element name is tagname[4][6][3], the default dimension sizes are 5,7,4.

This also means that arrays are indexed beginning at zero. For example, tagname[0] is the first element of the element array tagname.

The number of array dimensions and the number of elements allowed in an array are constrained in two ways:

• The element name field limits the size of the array dimensions. Sixteen characters are allowed in the dimension portion of an element name. For example, the array element name tempset[3][1][10][1][1] contains 7 characters in the element name portion (first field) and 16 characters (the maximum) in the dimension portion. The 16-character limit in the dimension field allows you to specify up to five dimensions, assuming most of the dimensions are single-digit.

• You can create element arrays containing up to 64K (65535) numbers of elements.

Use the following formula to determine the number of elements created in an array with a given set of dimensions:

a x b x c

where

a Is the size of the first dimension.

b Is the size of the second dimension.

c Is the size of the third dimension.

If an array contains more than three dimensions, use the same method to multiply by the sizes of the additional dimensions.

Example 1: Defining a One-dimensional Element Name

If you define a one-dimensional element name

tagarray[0]

the default size of the dimension displayed in the dialog is

1

If you modify the size of the dimension to

5



4

Co

nfig

uratio

n

Arch

itecture

five elements are created with the following element names:

tagarray[0]tagarray[1]tagarray[2]tagarray[3]tagarray[4]

Enter tagarray[index number] in the panel for each element referenced to reference individual elements in the array.

Example 2: Defining a Two-dimensional Element Name

If you define a two-dimensional element name as

msg_tag[1][1]

the default sizes of the two dimensions displayed in the dialog are

2,2

If you modify the sizes of the dimensions to

3,2

six elements are created with the following element names:

msg_tag[0][0]

msg_tag[0][1]

msg_tag[1][0]

msg_tag[1][1]

msg_tag[2][0]

msg_tag[2][1]

Enter msg_tag[index1][index2] in the panel for each element referenced to reference individual elements in this array.

Example 3: Using a One-dimensional Array

Suppose you need to define message elements whose values indicate the colors the cars on one conveyor belt are painted. If 300 cars are painted on the conveyor belt and element arrays are not used, you must define 300 elements individually. With element arrays, however, you define only one two-part element name and specify that the name contains 300 elements by entering 299 (creating elements 0 to 299) inside the brackets, as in

color[299]



•

•

•

•Set the integer ([299]) sizing the single dimension of the element to one less than the desired number since elements are numbered beginning at index zero (0). Here, the desired number of elements (299 + 1 or 300) are created under one element name, as in

color[0]color[1]color[2]

.

.color[299]

Example 4: Using a Two-dimensional Array

Suppose you want to define elements to indicate the colors cars on three conveyor belts are painted. You can define a two-dimensional element array by entering one element name, such as

paint[299][2]

The integer ([299]) for the first dimension indicates one fewer than the number of cars on each conveyor. The integer ([2]) for the second dimension indicates one fewer than the number of conveyors. As a result, the correct number of elements [(299 + 1) X (2 + 1) or 900] are created under one element name, as in

paint[0][0] paint[0][1] paint[0][2]




. . .

. . .

. . .


Example 5: Using a Three-dimensional Array

Suppose you must define elements whose values indicate the colors that cars on three conveyor belts and trucks on three conveyor belts are painted. You can define a three-dimensional element array using one element name as in

car_truck[299][2][1]

The third dimension ([1]) indicates the type of automobile. In this example, 1,800 elements are created under one element name as in



4

Co

nfig

uratio

n

Arch

itecture

(299 + 1) X (2 + 1) X (1 + 1) = 1800

The three-dimensional array may be thought of as a cube of indexed elements with each element having an (x,y,z) coordinate reference, such as depth, vertical position, and horizontal position.

Element Descriptions

A description includes optional information about the element defined or referenced with an element name in a data entry panel. When you enter a reference to a new element and click Enter, the system prompts you to define the element. Tag definitions can include a description of up to 80 characters. Two methods for changing descriptions are available:

• Open the Element Tag List in the Configuration Manager and modify the description field.

• Place the cursor in the element name field on the panel where the field has been defined and press Ctrl-T. The Element Tag Definition dialog displays, allowing you to change information about this element including its description.

Element Name Storage

Element names are stored in the {FLAPP} directory in the OBJECT database table.

Each task can have tables with elements referenced by name. These tables are converted to binary configuration table files (CT files) and, at run time, the typical FactoryLink application program reads its configuration table files and makes calls to read and/or write elements identified by the element numbers and data types listed in the CT files.

Predefined Elements

The FactoryLink starter application FLNEW comes with a set of predefined elements for internal use. These also serve as a convenience so you can use these when configuring tasks. Predefined elements in the USER domain contain a unique extension to the identifier of _U.

Configuration Database Tables

The model for data entered and managed by the Configuration Manager is a set of relational database tables including:

• DOMAIN

• TYPE

• OBJECT

• XREF

• Task-Specific



•

•

•

•The DOMAIN, TYPE, OBJECT, and XREF database tables are reserved system tables and are not developer-definable. The task-specific database tables, however, are developer-defined and are only present when that task is used in the application.

The database tables form a set of relational databases as follows.

XREF

OBJECT

DOMAIN

TYPE

Task 1Table 1

Task 1Table 2

Task 2Table 2

DATABASE TABLES



4

Co

nfig

uratio

n

Arch

itecture

TYPE

The TYPE database table defines the segments that consist of one of the six data types and one of the domains used in FactoryLink. Each of these types corresponds to a record in the TYPE table.

OBJECT

The Configuration Manager maintains the Real-Time Database tag definitions for each application in the OBJECT database table. Knowledge of the format is generally not required to add a new task. The OBJECT table contains a list of real-time elements defined by the developer, but it does not contain task-specific information. Task-specific information is kept in other tables related solely to that task.

XREF

The Configuration Manager maintains a cross-reference table. The XREF database table contains a record for each occurrence of an element in any task-specific table. This information allows the Configuration Manager to locate all occurrences of a particular element in the task-specific tables quickly.

Type Description

DIGITAL Boolean value (on or off).

ANALOG 16-bit signed integer.

LONGANA 32-bit signed integer.

FLOAT double precision floating point.

MESSAGE Variable length binary or ASCII data.

MAILBOX Variable length data, organized as a queue.

CONFIGURATION ARCHITECTUREFactoryLink Application Directory ({FLAPP})


•

•

•

•Task-Specific

A task consists of one or more developer-definable task-specific database tables. There is no limit on the number of tables per task. If a task has more than two tables, the tables may be related either serially or in a one-to-many fashion.

Task-Specific Example

Suppose a PLC task consists of a Write table and a Read table. The Write and Read tables each consist of a Control panel and an Information panel. The Control panel contains header records specifying the trigger information for a group of data records. The control and information records are stored in different tables because they have different structures.

FACTORYLINK APPLICATION DIRECTORY ({FLAPP})

The following files are located in the {FLAPP} directory. The subdirectories containing program files are organized as follows.

Subdirectory File(s) Description

*.CDB Database tables that store information about the elements such as name, type, number of definitions (number of writes specified by the defining task), number of references, and task specific information.

*.MDX Indexes used by the Configuration Manager in conjunction with the CDBs to order the CDB information.

\ASC *.ASC ASCII database tables that store information about the Real-Time Database elements and task specific information. They are used to import/export configuration data from one application directory to another (typically, from one platform to another platform).

*.EXP Output of CM export.

\CT *.CT Binary configuration tables. Each FactoryLink program employs one or more configuration tables.



4

Co

nfig

uratio

n

Arch

itecture

\LOG Error log files produced by FactoryLink processes at run time containing debug information.

\NET GROUPS Groups on this node.

LOCAL FLLAN information.

\PROCS *.PRG Math & Logic procedures.

\RCP Files created by the Batch Recipe task.

\RPT *.RPT Report files generated by the Report Generator task.

\SPOOL Subdirectory used by the FactoryLink Print Spooler task.

Subdirectory File(s) Description



•

•

•

•The following files are located in the {FLAPP} directory and/or the {FLAPP}\{FLDOMAIN} directory where the {FLDOMAIN} is either SHARED or USER. The subdirectories containing program files are organized as follows.

Subdirectory: File(s): Description of File(s):

\ASC *.ASC ASCII database tables that store information about the elements. Used to import/export configuration data from one application directory to another (typically, from one platform to another).

*.EXP Output of CM export.

\CML Compiled Math & Logic files.

\CT *.CT Binary configuration tables. Each FactoryLink program employs one or more configuration tables.

\DCT External Device Interface CT files.

\DRW *.G*

*.PL*

Graphics and PowerVB files created with the Application Editor and used by Run-time graphics files.

\LOG Error log files produced by FactoryLink processes at run time containing debug information.

\NET GROUPS Groups on this node.

LOCAL FLLAN information.

\PROCS *.PRG Math & Logic procedures.

\RCP Files created by the Batch Recipe task.

\RPT *.RPT Report files generated by the Report Generator task.

\SPOOL Subdirectory used by the FactoryLink Print Spooler task.

5

Co

nstru

cting

a F

actoryL

ink Task



Constructing a FactoryLink Task

This chapter details the procedure for constructing tasks and integrating them with the rest of the system. Topics include:

• Overview

• Guidelines for Task Design

• Creating the Configuration Environment

• Run-Time Requirements

• Task Program Skeleton

CONSTRUCTING A FACTORYLINK TASKOverview


•

•

•

•

OVERVIEW

We recommend you follow the top-down software design model illustrated in the following flow chart even though you are not required to follow any particular process when constructing tasks.



5

Co

nstru

cting

a F

actoryL

ink Task

The top-down software design model consists of three major tasks:

• Setting up the Configuration Environment

• Converting Database Tables to CTs

• Writing the Run-Time Task

Setting up the Configuration Environment

Setting up the Configuration Environment includes four steps:

1 Design the Database Tables(s).

2 Create the Attribute Catalog(s).

3 Create the KEY Files.

4 Test the Configuration Environment.

Design the Database Table(s)

Designing the database table(s) for the task involves laying out the panel(s) opened from the Configuration Manager Main Menu where you enter configuration information for the task. Designing these tables involves mapping the work performed into a set of relational databases.

With the possible exception of operator selections and/or commands entered at run time, the database table contains the information the task program needs to do its job. For example, it serves as the storage area for the user-entered inputs when you select this task from the Main Menu.

A table consists of one or more fixed-length database records. Each table is associated with an index to control the logical order of the records. The task may require more than one table to describe the work to be performed. These database tables can be related or unrelated to each other.

Create the Attribute Catalog(s).

Create at least one Attribute Catalog (with extension .AC) for each set of database table(s) to describe the structure of this table. In addition, it lists the panel(s) displayed when the user chooses this task from the Main Menu.

An AC file is an ASCII text file that may be created and edited with an ordinary text editor, such as Notepad. It tells the Configuration Manager the format or structures of the records, how to interpret operator input, and how to fill in the fields of the records.



•

•

•

•Place the AC file(s) in the {FLINK}/AC directory that contains AC files for all FactoryLink tasks. Create the translation file for the AC headings.

Create the KEY Files

If necessary, create any KEY files referenced by the Attribute Catalog(s) or the Panel file(s). Create the KEY file(s) with a text editor, such as Notepad. Limit the alpha-numeric strings to 32 characters. This file tells the Configuration Manager how to validate operator-entered key words to be placed in the database table. After the KEY file(s) have been created, place them in the /{FLINK}/KEY\EN, /{FLINK}/KEY\FR, or /{FLINK}/KEY\DE directory. Example KEY files are shown below.

flink\key\en\example.key

flink\key\fr\example.key

NULL -1 NULL

NO 0 NO

YES 1 YES

N 0 N

Y 1 Y

SLW 1 SLW

FST 2 FST

NULL -1 NULL

NON 0 NO

OUI 1 YES

N 0 N

O 1 Y

LENT 1 SLW

RAPIDE 2 FST



5

Co

nstru

cting

a F

actoryL

ink Task

flink\key\de\example.key

Test the Configuration Environment

Inform FactoryLink about the new task by adding the name of the AC file to the TITLES file.

Using the Configuration Manager, test the configuration environment, including the Attribute Catalog.

Once errors or problems are analyzed and corrected, choose the task from the Main Menu, entering a variety of simulated data in the panel(s) to be stored in the newly-created database table(s).

Convert Database Tables to CTs

When converting database tables to CTs, you must write a configuration table generator (CTG) script that tells the CTGEN utility (generate binary CT files) how to extract data from the database tables and combine it to produce a binary Configuration Table (CT) file. You must also verify the script performs the desired conversion.

Writing the Run-Time Task

Ultimately, an executable must be created that reads the configuration information entered into the task configuration databases (CDBs) and later converted into binary configuration tables (CT). This involves writing a C program that invokes the methods provided by the FactoryLink library.

You must remember certain high-level concepts during the design of a custom task. Proper design enables the task to coexist efficiently with other FactoryLink programs. In addition, designing to the PAK guidelines provides an upgrade path to other operating systems.

NULL -1 NULL

NEIN 0 NO

JA 1 YES

N 0 N

J 1 Y

LANGSAM 1 SLW

SCHNELL 2 FST



•

•

•

•The following guidelines enhance your design process:

• Tasks should be designed to run concurrently with system configuration.

A custom program should not adversely affect or otherwise interfere with concurrently running tasks, directly access system resources, such as I/O devices under the control of the operating system, or severely degrade the performance of FactoryLink.

• Tasks should be designed to cooperate with the Run-Time Manager.

The program must conform to certain requirements imposed by the Run-Time Manager in order for the latter to carry out its supervisory duties effectively.

CONSTRUCTING A FACTORYLINK TASKCreating a Configuration Environment


5

Co

nstru

cting

a F

actoryL

ink Task

CREATING A CONFIGURATION ENVIRONMENT

This section provides details for setting up the configuration environment that includes the following tasks:

• Design the Database Table(s)

• Create the Attribute Catalog(s)

• Create the KEY Files

• Add AC File Names to TITLES file

• Test the Configuration Environment

The following figure illustrates the portion of the Task Construction Flowchart involved in setting up the configuration environment.



•

•

•

•Design the Database Table(s)

When you construct a task for a custom application, you must design one or more database tables.

Designing the Task-Specific Database Table(s)

Designing the task-specific database table(s) is the first step in task construction. The design process should include the following considerations:

• What type of data is required for this task?

• What data must be stored in this task-specific database table.

• What other tasks require information supplied by this task?

• Are both Control and Information panels required or just an Information panel?

• What is the panel design, including the following items:

• Name of the panel

• Panel layout, such as column headings and order of information

• Data type of any element to be entered on the panel

• Editing validation required for a field, such as data type limitation or value- range check

Relationship Between OBJECT and Task-Specific Tables

Task-specific tables contain information for the Configuration Manager to add to the other run-time tables on behalf of the task. For example, the Alarm Supervisor configuration allows the specification of an element to be monitored for an alarm condition. In addition to the element, you can also specify alarm messages and limits. The Configuration Manager adds the element to the OBJECT table if it has not already been created. In addition, the Configuration Manager adds the element name and task-specific information to the Alarm Supervisor table.

Relationship between DOMAIN and Task-Specific Tables

Tasks run in one or more domains. The configuration for these tasks are normally unique per domain; therefore, a domain is associated with each record entered into the configuration database. Configuration in one domain is not accessible to the task executing in another domain.

Caution: On the rare occasion a task configuration applies to all domains, it is legal to omit specifying a domain with each record. Be aware, however, that configuration without a domain cannot reference any FactoryLink tags.



5

Co

nstru

cting

a F

actoryL

ink Task

Create the Attribute Catalog(s)

An Attribute Catalog (AC) file represents one menu option on the Main Menu and may or may not represent an entire task. For example, to configure the Batch Recipe task, you choose only one option, Recipe, and fill in the associated panels. This option corresponds to the RECIPE.AC file.

When you select an option from the Main Menu, one or more panels display. Each panel corresponds to a database table whose characteristics are specified in the AC file that corresponds to the option chosen.

An AC file indicates

• Name of the menu option

• Order database tables are to be edited in

• Relationships between the database tables

• Validation information

Each field you can edit in a database table record must be specified in the AC file. AC files are found in {FLINK}\ac\<filename>.ac.

Because they are ASCII text files, the AC files for standard tasks are easily copied and altered to create an AC for a new task.

The best way to create an AC file is

• Copy an existing AC file from the {FLINK}/ac directory

• Make necessary changes to this file

• Save it with a new name

Configuration Manager Main Menu Option AC File Name

Recipe RECIPE.AC

System Configuration SYS.AC



•

•

•

•Note: Text files (*.txt) are now stored in one of the following directory paths:

\flink\msg\en\flink\msg\de\flink\msg\fr

The text files were previously found in the \flink\msg or \flink\msg\english directory paths.

Fl_xlate automatically loads from the correct subdirectory based on the language you select.

AC File Format

In an AC file, each statement begins with a keyword followed by one or more parameters separated by commas. Comments may be included in the AC file by beginning the line with an asterisk. The comment continues to the end of the line. Blank lines and leading spaces are ignored. A statement may be split over multiple lines. The keyword DELETE may not be used in an AC file. It is reserved for an internal function and is not available to the programmer.

Note: The first non-comment line of the AC file should contain an XLATES directive that tells where the token translations are located. For example, in the Report Generator AC file (rpt.ac), the XLATES directive is XLATES rpt_ac.txt, which tells the system to look in file rpt_ac.txt for translation for this file.

The general format of an AC file follows. Brackets ([ ]) indicate optional entries.

XLATES “xlatefilename”

TASK name, {title}

CT table_name, file_name, “{titletokenstring}”

[EDIT type [, editor]]

[VALIDATE type]

PANEL panel_file, x, y, width, height

FIELD name, type, width, field_prec, key_file, default, low, high, flags

[HEADING “{tokenstring}”, width ]

[RELATE CDB_name, field_name, index_file ]

DOMAIN “DOMAIN”, 8

SELECT field_name , width [<HEADING {heading_string}> , width]

SEQ field_name , width



5

Co

nstru

cting

a F

actoryL

ink Task

INDEX index_file, key_expression, key_length

END

The following sections describe each statement in the AC file.

XLATES

XLATES “filename”

Filename is the name of the file in \flink\msg\en, \flink\msg\fr, or \flink\msg\de that contains the tranlsations of the tokens used in the AC.

TASK

TASK name, {title}

The TASK statement defines the task name and title for the task list. Only one TASK statement is included in an AC file.

CT

CT table_name, file_name, “{titletokenstring}”

The CT statement defines a database table. A task may have as many CT statements as needed, one per panel. If more than one panel is displayed when this task is chosen from the Main Menu, place the CT statements in reverse order from the order the panels are displayed in; that

Parameter Description Valid Entries

name Name of task as displayed in the Task Name field on the System Configuration Information panel.

Alphanumeric string of up to 8 characters.

{title} Name of the task as displayed on the Configuration Manager Main Menu from translation of the tokens used in the AC.

Note: Tokens in AC files must be enclosed in braces { }.

Alphanumeric string.



•

•

•

•is, the first CT statement corresponds to the back panel, the last CT statement corresponds to the front panel.

EDIT

[EDIT type [, editor]]


table_name Name of the database table.

Valid table name.

file_name Name of the database table or file specification.

If name refers to: Then enter:

Database table Same name asspecified above intable_name.

File spec. TEXT or EXECUTEtype in EDIT statement:File name(s) to edit.

{titletokenstring} Title of the panel from translation of the tokens used in the AC.

Alphanumeric string.



5

Co

nstru

cting

a F

actoryL

ink Task

The EDIT statement defines a module or program used to edit this database table. If the EDIT statement is not included, the Configuration Manager uses the default edit procedure.

VALIDATE

[VALIDATE type]


type Determiner of the module or program used for editing.

DEFAULT (Standard panel edit procedure, which means you complete the columns and rows of the panel using the Tab key or arrow keys to move from field to field or row to row.)

TEXT (Text panels where you press the Enter key to move to the next line of text.)

EXECUTE (Any executable program loaded as an editor.)

EXTERNAL (The EXTERNAL entry for the type parameter of the EDIT.)

editor Editor to be used on this database table; depends on the type parameter.

If the type is:

DEFAULT: no entry

TEXT: no entry

EXECUTE: name of executable to launch

EXTERNAL: Internal use only



•

•

•

•The VALIDATE statement defines the level of editing you are allowed when completing a configuration table and the program or module that performs the editing.

PANEL

PANEL panel_file, x, y, width, height

The PANEL statement defines the display/edit window(s) for the database table. If the PANEL statement is not included, you cannot edit records in the table with the Configuration Manager default edit functions.


type Type and level of editing performed on a configuration table.

DEFAULT

EXTERNAL

READONLY

NOEDIT

Validation done internally by the Configuration Manager.

Validation performed by an external function.

You can only view table; editingnot allowed.

Do not use this entry: it is reserved. NOEDIT means you cannot edit or view the table.


panel_file Name of a file containing the panel definition.

Valid file name.

x Initial horizontal position of the lower left corner of the panel or of the default panel if the panel_file is not used.

0-1000 where the position:0,0 is lower left corner of screen1000,1000 is upper right corner of screen.

y Initial vertical position of the lower left corner of the panel or of the default panel if the panel_file is not used.

0-1000 where the position:0,0 is lower left corner of screen1000,1000 is upper right corner of screen.

width Width of the panel. 0-1000.



5

Co

nstru

cting

a F

actoryL

ink Task

FIELD

FIELD name, type, width, field_prec, key_file, default, low, high, flags

The FIELD statement defines one editable field in the database.

height Height of the panel. 0-1000.


name Field name as stored in the database table definition.

Valid field name with 10 characters maximum.

type Type of field. The Configuration Manager performs validation on the field based on the type.

CHARCTERNUMBERKEYTAGTAGCHARTAGNUMTAGKEY

width Maximum field length. 255 characters maximum.

field_prec Numeric precision of field. 0 (floating points only).

key_file KEY or TAG types only:Name of a keyword file used to validate the value in the field.

Name of the key file; do not use the extension; no entry.

default Default value for the field. String. If the type is KEY, then the entry must be included in the key_file. If the type is TAG, then the entry must be a valid tag type.

low NUMBER or TAGNUM type only:Lowest value allowed in this field.

Number; must match radix indicated in flags parameter.




•

•

•

•

Tag-Constant Extensions to the Field Definition

Tag constants provide a means wherein a user can enter a tag name or a constant value within a single field. This increased flexibility in field types often simplifies the configuration of a task by reducing the number of fields to be configured.

FLCM has three distinct types of tag constant fields:

• TAGNUM. Fields that accept numeric constants or tag names

• TAGCHAR. Fields that accept character constants or tag names

• TAGKEY. Fields that accept key file verification or tag names

Visual Indication to the USER

FLCM automatically precedes all field descriptions in the displayed panel with an asterisk to eliminate confusion as to whether a tag name, value, or both may be entered into a field.

Determining the Tag-Constant Field’s Data Type

Inputs into TAGCHAR and TAGKEY type fields, which allow tag names or character constants as input, need a way for FLCM to distinguish a tag name from a character constant. To do this, FLCM requires any constant value entered into a TAGCHAR and TAGKEY type field to be preceded by a single quotation mark (’).

high NUMBER or TAGNUM type only:Highest value allowed in this field.

Number; must match radix indicated in flags parameter.

flags Edit options. b allow blank field.v validate using min/max.r read-only field.o octal field.x hexadecimal field.u force field to upper case.




5

Co

nstru

cting

a F

actoryL

ink Task

Specifying Validation Criteria for a Tag-Constant Field

The affect of tag constant type on valid entries for the following field parameters follow.

Examples

FIELD "YEAR", "TAGNUM", 48, 0, "TYPEAL", "ANALOG|1992", 1980, 2200, "bv"

HEADING "{Yearhd}", 44

FIELD "MONTH", "TAGKEY", 48, 0, "TYPEAFML|MONTH", "MESSAGE|JAN", 0, 0, "bu"

HEADING "{Monthhd}", 44

FIELD "DOW", "TAGCHAR", 48, 0, "TYPEM", "MESSAGE|MON", 0, 3, bu"

HEADING "{DOWhd}", 44

HEADING

[HEADING “{tokenstring}”, width]

The HEADING option defines the text used as a field heading and the character width for the column. If you do not specify a heading, the field name is used as the field heading and the width is calculated based on the number of characters in the field. The Configuration Manager

Parameter Valid Entries

key_file Since a tag constant field allows entry of tag names or constant values, there may be more than one validation file for TAGKEY type fields. One key file specifies the allowable tag types. The other key file specifies the valid key constant entries. As such, concatenate both key file names into this parameter with a | dividing the names.

Example: “<tag_types_key>|<constants_key>”

default The default parameter has a | dividing the default tag type from the default value for a constant. The default tag type precedes the default constant value.

Example: “<tag_type_default>|<constant_default>”

low/high These parameters are still applied to constant value validation. The only tag constant twist applies to the TAGCHAR type fields where the low and high parameters specify the minimum and maximum number of characters allowed in the character string.



•

•

•

•allows an unlimited number of lines of text for the HEADING parameter. Delimit lines with the vertical bar on the first line and Heading on the second line.

RELATE

[RELATE CDB_name, field_name, index_file]

A RELATE entry indicates this field is used as a relational field. The current value of the field is used to select records in another database table. The index file is currently unused.

Note: In .AC files, do not use RELATE statements with a field of type TAG.

TYPE

[Type “field_name”]


{tokenstring} Field heading as displayed on the panel from translation of the tokens used in the AC.

Text string.

width Width of the heading in pixels. Number of pixels.


CDB_name Name of the database table related records are to be selected from (for example, associated data in another table about a specified table).

Table_name parameter entry of another CT statement in this AC file.

field_name Name of field to set using data from this field.

Name parameter entry of a FIELD statement in related CT in this AC file.

index_file Name of index to use for ordering; not currently implemented.

Index_file parameter entry of an INDEX statement in related CT in this AC file.



5

Co

nstru

cting

a F

actoryL

ink Task

The TYPE statement causes the TAG type of a TAG field to be displayed.

DESC

[DESC “fieldname”]

The DESC statement indicates the description of an OBJECT field should be displayed.

DOMAIN


Enter the DOMAIN statement exactly as shown above for each configuration panel in each AC file. Do not change this statement.

After you configure a panel, the task-specific CDB file DOMAIN statement contains SHARED or USER, depending on the domain selected in the Domain Selection box. The OBJECT.CDB associates each element with the domain defined in the Tag Definition pop-up panel.

This statement must be included for each configuration table defined in an AC file for FactoryLink to operate correctly.


field_name TAG field associated with the type.

String containing the name of a field of type TAG in this CT.


field_name TAG field associated with this description.

String containing the name of a field of type TAG in this CT.



•

•

•

•SELECT

SELECT field_name , width [<HEADING {tokenstring}> , width]

The SELECT statement defines a selection field. Each CT may have one or more select fields that determine whether or not a record in the CT is displayed and edited by matching the current value of the selection with the value contained in the database. Normally, select fields are not listed in the FIELD statements and you cannot change them. The first select field, however, is displayed at the bottom of the table and you may change it. The HEADING option allows a string to be defined to label the select input box. Any other select fields should be set by a RELATE statement in another CT.


field_name Name of the field. String; valid database field name.

width Field length. Maximum database field width.

HEADING {tokenstring} Heading; displayed as prompt for select input field from translation of the tokens used in the AC.

Text string.

HEADING width Width of the heading in pixels.

Number of pixels.



5

Co

nstru

cting

a F

actoryL

ink Task

SEQ

SEQ field_name , width

The SEQ statement defines a field that contains a sequence number for the records. Sequence numbers can be included in the primary key for the database so that records are sorted in the same order they were entered. The Configuration Manager automatically generates the sequence number.

INDEX

INDEX index_file, key_expression, key_length

The INDEX statement defines an index for the database. The first INDEX statement defines the primary index and controls the order of records on the screen. If needed, define additional indices for use by external programs, such as CTGEN. The Configuration Manager updates all indices whenever a database record is updated.


field_name Name of the field containing a sequence number for the records.

Valid database field name.

width Field length. 0 - maximum field width.


index_file Name of the index. Valid index name.

key_expression List of fields used to form the key for the database. A field contained in the key should not be listed in the FIELD statements.

Entry format is:“FIELD+FIELD2+...FIELDN”

key_length Length of the key. Integer equal to the sum of the lengths of the fields contained in the key.



•

•

•

•END

END

The END statement terminates a CT definition; therefore, one END statement corresponds to each CT statement in the AC file.

Naming Considerations

PAK currently uses a dBASE-compatible database library that dictates the following parameters.

Sample AC File

The following code sample shows the Attribute Catalog for the FactoryLink Logger task:

* Attribute Catalog for Logger Taskxlates “loggerac.txt”TASK "LOGGER", "{Logger_Task}" * Task name and Title

* CT"logtags", "logtags", "{Logger_Info}"EDIT DEFAULT * Default EditingVALIDATE DEFAULT * Default ValidationPANEL "", 100, 100, 700, 700 * Initial PositionFIELD "TAG", "TAG", 48, 0, "", "", 0, 256, "v"

HEADING "{Value_Tag}", 96FIELD "WIDTH", "NUMBER", 3, 0, "", "", 0, 256, "v"

HEADING "{Field_Width}", 96DOMAIN "DOMAIN", 8SELECT "TABLE_NAME", 16 * Primary KeySEQ "TABLE_NBR", 10 * Sequence NumberINDEX "logtags", "DOMAIN+TABLE_NAME+TABLE_NBR", 34 * Index file, key

END

* CT Name Database Title

CT "logtrig", "logtrig", "{Logger_Cntl}"EDIT DEFAULT * Default EditingVALIDATE DEFAULT * Default ValidationPANEL "", 200, 0, 700, 700 * Initial PositionFIELD "TABLE_NAME", "CHARACTER", 16, 0, "", "", 0, 0, ""

Entries Maximum Length/Width

All table and index names. 8 characters.

Field names. 10 characters.

Field width. 255 characters.



5

Co

nstru

cting

a F

actoryL

ink Task

HEADING "{Table_Name}", 96RELATE "logtags", "TABLE_NAME", "logtags"FIELD "TRIGGER", "TAG", 48, 0, "", "", 0, 0, ""

HEADING "{Trigger Tag}", 96FIELD "PATH", "CHARACTER", 64, 0, "", "", 0, 0, ""

HEADING "{PATH}", 96DOMAIN "DOMAIN", 8SEQ "TABLE_NBR", 10 * Sequence NumberINDEX "logtrig", "DOMAIN+TABLE_NBR", 18 * Index file, key

END



•

•

•

•The following table shows the tokens for an internationalized LOGGER.AC file.

Language Name Description

EN Logger_Task Logger Task.

FR Logger_Task Tache du consignateur.

DE Logger_Task Logger Task.

EN Logger_Info Logger Information.

FR Logger_Info Informations du consignateur.

DE Logger_Info Logger-Information.

EN Value_Tag Value Tag.

FR Value_Tag Tag de valeur.

DE Value_Tag Wert-Tag.

EN Field_Width Field_Width.

FR Field_Width Largeur du champ.

DE Field_Width Feldbreite.

EN Logger_Cntl Logger Control.

FR Logger_Cntl Controle du consignateur.

DE Logger_Cntl Logger-Kontrolle.

EN Table_Name Table Name.

FR Table_Name Nom table.

DE Table_Name Tabellenname.

EN Trigger_Tag Trigger Tag.

FR Trigger_Tag Tag declencheur.

DE Trigger_Tag Trigger-TAG.

EN Path Path.



5

Co

nstru

cting

a F

actoryL

ink Task

The next three tables show the tokens for internationalized English, French, and German LOGGER.AC files generated from the previous code.

FR Path Chemin.

DE Path Pfad.

Name Description

Logger_Task Logger Task.

Logger_Info Logger Information.

Value_Tag Value Tag.

Field_Width Field Width.

Logger_Cntl Logger Control.

Table_Name Table Name.

Trigger_Tag Trigger Tag.

Path Path.




•

•

•

•

The next table contains the tokens for internationalized English, French, and German LOGGER messages. These tokens are not related to the AC file, but they are part of the Logger Task.

Name Description

Logger_Task Tache du consignateur.

Logger_Info Informations du consignateur.

Value_Tag Tag de valeur.

Field_Width Largeur du champ.

Logger_Cntl Controle du consignateur.

Table_Name Nom table.

Trigger_Tag Tag declencheur.

Path Chemin.

Name Description

Logger_Task Logger-Task.

Logger_Info Logger-Information.

Value_Tag Wert- Tag.

Field_Width Feldbreite.

Logger_Cntl Logger-Kontrolle.

Table_Name Tabellenname.

Trigger_Tag Trigger-Tag.

Path Pfad.


EN START Starting.



5

Co

nstru

cting

a F

actoryL

ink Task

FR START Demarrage.

DE START Startet.

EN RUN Running.

FR RUN Execution.

DE RUN Lauft.

EN STOP Normal shutdown.

FR STOP Arret normal.

DE STOP Normaler Shutdown.

EN NOMEMORY Out of RAM.

FR NOMEMORY Memoire RAM saturee.

DE NOMEMORY Kein Arbeitsspeicher mehr.

EN NOCT Can’t open CT.

FR NOCT Impossible d’ouvrir la TC.

DE NOCT CT Kann nicht geoffnet werden.

EN NOTRIGGERS No triggers defined.

FR NOTRIGGERS Aucun declencheur defini.

DE NOTRIGGERS Keine Trigger definiert.

EN CTINDEX Error reading CT index.

FR CTINDEX Erreur lors de la lecture de l’index de la TC.

DE CTINDEX Fehler beim Lesen von CT-Index.

EN CTHEADER Error reading CT header.

FR CTHEADER Erreur lors de la lecture de l’en-tete de la TC.

DE CTHEADER Fehler beim Lesen von CT-Kopf.




•

•

•

•

The next three tables show the internationalized English, French, and German token files generated from this message .AC file.

EN BADTAG Invalid trigger tag.

FR BADTAG Tag declencheur incorrect.

DE BADTAG Ungultiges Trigger-TAG.

EN CTRECORD Error reading CT record.

FR CTRECORD Erreur lors de la lecture de l’enregistrement de la TC.

DE CTRECORD Fehler beim Lesen von CT-Datensatz.

EN CANTOPEN Can’t open: %s.

FR CANTOPEN Impossible d’ouvrir : %s.

DE CANTOPEN Kann nicht geoffnet werden : %s.

EN TRIGCRE Error creating trigger manager.

FR TRIGCRE Erreur lors de la creation du gestionnaire de declencheurs.

DE TRIGCRE Fehler beim Erstellen des Trigger-Managers.

EN TRIGINS Error inserting trigger into manager.

FR TRIGINS Erreur lors de l’insertion du declencheur dans le gestionnaire.

DE TRIGINS Fehler beim Einfugen des Triggers in den Manager.

Name Description

START Starting.

RUN Running.

STOP Normal shutdown.




5

Co

nstru

cting

a F

actoryL

ink Task

NOMEMORY Out of RAM.

NOCT Can’t open CT.

NOTRIGGERS No triggers defined.

CTINDEX Error reading CT index.

CTHEADER Error reading CT header.

BADTAG Invalid trigger tag.

CTRECORD Error reading CT record.

CANTOPEN Can’t open: %s.

TRIGCRE Error creating trigger manager.

TRIGINS Error instering trigger into manager.

Name Description



•

•

•

•

Name Description

START Demarrage.

RUN Execution.

STOP Arret normal.

NOMEMORY Memoire RAM saturee.

NOCT Impossible d’ouvrir la TC.

NOTRIGGERS Aucun declencheur defini.

CTINDEX Erreur lors de la lecture de l’index de la TC.

CTHEADER Erreur lors de la lecture de l’en-tete de la TC.

BADTAG Tag declencheur incorrect.

CTRECORD Erreur lors de la lecture de l’enregistrement de la TC.

CANTOPEN Impossible d’ouvrir : %s.

TRIGCRE Erreur lors de la creation du gestionnaire de declencheurs.

TRIGINS Erreur lors de l’insertion du declencheur dans le gestionnaire.



5

Co

nstru

cting

a F

actoryL

ink Task

Skeleton Task Sample

A complete AC file for the Skeleton Task is in the PAK software at file, SKEL.AC.

If you have not yet integrated the skeleton task into your FLINK system, please execute the steps from Chapter 2, “The Skeleton Task” prior to proceeding with the following procedure.

Name Description

START Startet.

RUN Lauft.

STOP Normaler shutdown.

NOMEMORY Kein Arbeitsspeicher mehr.

NOCT CT kann nicht geoffnet werden.

NOTRIGGERS Keine Trigger definiert.

CTINDEX Fehler beim Lesen von CT-Index.

CTHEADER Fehler beim Lesen von CT-Kopf.

BADTAG Ungultiges Trigger-TAG.

CTRECORD Fehler beim Lesen von CT-Datensatz.

CANTOPEN Kann nicht geoffnet werden : %s.

TRIGCRE Fehler beim Erstellen des Trigger-Managers.

TRIGINS Fehler beim Einfugen des Triggers in den Manager.



•

•

•

•Choose the Skeleton FactoryLink Task from the Main Menu to configure the task. As described in the CT statements in the SKEL.AC file, the panels, Tag List and Trigger Tags, are displayed on the Main Menu along with the Domain Selection box.

The second CT definition describes the Trigger Tags panel; therefore, it is the front panel in the display. Compare the PANEL statements for both panels: the lower left corner of the Tag List panel (position 100) appears further left than the lower left corner of the Trigger Tags panel (position 200). Also, the lower left corner of the Tag List is vertically higher (position 100) than the lower left corner of the Trigger Tags panel (position 0). The example runs in the USER domain.

As described in the FIELD statements for the Trigger Tags panel, the panel contains two fields, Trigger Tag and Table Name. Since the type parameter in the FIELD statement is TAG and the key_file parameter is TYPED (digital) in the Trigger Tag field, you enter the name of a digital Real-Time Database element when configuring the task. Since the type parameter in the FIELD statement is CHARACTER and the width parameter is 16 in the Table Name field, enter a string of 1-16 characters when configuring the task.



5

Co

nstru

cting

a F

actoryL

ink Task

As described in the RELATE statement for the Trigger Tags panel, the two panels are related to each other by the TABLE_NAME field. Once the Trigger Tags panel is complete, select the Table Name you want to complete a tag list for and then complete the Tag List panel for that table name.

After you complete the Trigger Tags panel, choose the desired Table Name, and open the Tag List panel, the chosen Table Name displays in the field above Cancel on the Tag List panel.

As described in the FIELD statement for this panel, you complete only one field, Tag Name, by entering the name of an element (TAG type in FIELD statement) of any data type.

Associating Help with the Task Attributes Catalog

Both table and field help should be created for all ACs. This equates to creating a formatted text file and placing the results in directory {FLINK}\msg\en, {FLINK}\msg\fr, or {FLINK}\msg\de for each supported language. AC help files have a .hlp extension.

The help format is very simple. It contains several repeating blocks of the following:

$

<CT name>, <Field name>, <Help title>

<Description text>

Whenever field help is requested, FLCM locates the entry associated with the selected field and displays the description text in a message box. The title of the message box is <Help title>. To locate the help text, the values for <CT name> and <Field name> must match the names entered in the corresponding AC exactly.

Use the string TABLE_HELP for <Field name> to create panel help for a CT.



•

•

•

•Execute command “mkhelp -v” from the system prompt to integrate the help file into the FactoryLink system. This rebuilds the index of help entries that FLCM references later.

Note: The HLP and VHS files have been moved to a new directory structure, \flink\help\{EN, FR, DE}\ *.{hlp, vhs}, where the EN, FR and DE subdirectories contain the English, French, and German translations, respectively. There are no other changes to the HLP or VHS files.

Executing an Editor Program from the Configuration Manager

The Configuration Manager can load any executable program as an editor; therefore, to run an editor from the Configuration Manager, create an AC file for the external editor program. Remember to add the name of the AC file to the TITLES file. Refer to “Testing the Configuration Environment” on page 102 for more information.

An AC file for an external program has the following format:

Task name, {task_title}

CT ct name, file spec, “”

EDIT EXECUTE executable, cmd arguments, format string

VALIDATE DEFAULT

END

The following table describes each statement of this format.

Parameter Description

task Name of the FactoryLink run-time task.

task_title Text displayed in the Configuration Manager Main Menu window.

ct_name Name of the configuration table.

file_spec Specifics for the file to edit.

executable Editor executable.

cmd_arguments Argument strings to be passed to the editor.

format_string Format string for command arguments. If %s is displayed in the format string, it is replaced with the file spec option and passed to the editor as a command line argument.



5

Co

nstru

cting

a F

actoryL

ink Task

The following sample AC file loads the system E.EXE to edit FactoryLink Math & Logic files.

TASK “IML”, “Edit Math Procedures with System Editor”

CT “iml”, “%s/procs/*.prg”, “”

EDIT EXECUTE “e.exe”, “”, “%s”

VALIDATE DEFAULT

END

Since the file specification contains a wildcard character, the screen displays a list box of all PRG files in the {FLAPP}/procs directory. You select a file name from this list to be passed to the editor. If the file spec contains wildcard characters and is not a full path name, the current application directory is added to the front of the file name to make a full path name.

The string specified as the format string is passed to the C-language function SPRINTF. Only one % can be specified. Also, if a percent sign must be passed as an argument, denote this by using two percent signs.

If the file spec option does not contain any wildcard characters, then the display does not contain the file list box and the file spec option is used exactly as it is displayed in the AC file.

Note: This is slightly inconsistent. The format string should be used in either case, but it is used only if the file spec contains wildcard characters. Currently no easy way exists to pass wildcard characters on to the external editor.

If you select MYPROC.PRG from the file list box, the following command is executed:

e.exe {FLAPP}/SHARED/PROCS/MYPROC.PRG

Create the KEY Files

KEY files are used to validate table entries. The CTGEN utility that generates the binary CT files also uses key files to translate ASCII values into binary values. If a KEY file does not exist that contains the desired values, create a new KEY file with an ordinary text editor, such as Notepad on Windows.

Construction of a Key File

Each active line of a KEY file specifies a text-to-binary value conversion. Comment lines, which are not used by the system and are for information and documentation purposes only, begin with an asterisk.

By convention, the text and its associated value are displayed on the same line separated from each other by a vertical bar. The Configuration Manager ignores any leading and trailing



•

•

•

•blanks surrounding the text or the value. The binary values in the KEY file must be entered in decimal notation.

The Key files are found in {FLINK}\key\en, {FLINK}\key\fr, or {FLINK}\key\de.

The third column of the *.KEY files contains English versions of the string. This English string is what is stored in the MPS files. In FactoryLink the English string is mapped for display to the proper language, based on the current language setting in flink\install\fllang.lst. This allows applications to be saved on a system using one language and restored on a system using another language.



5

Co

nstru

cting

a F

actoryL

ink Task

The best way to create a KEY file is

• Copy an existing key file

• Make the necessary changes to it

• Save it with a new name

Sample KEY File

A sample KEY file is MONTH.KEY, used for translating abbreviations of the names of the months to numeric values:

* MONTH, KEY

*NAME | NUMBER

NULL | -1 | NULL

JAN | 1 | JAN

FEB | 2 | FEB

MAR | 3 | MAR

APR | 4 | APR

MAY | 5 | MAY

JUN | 6 | JUN

JUL | 7 | JUL

AUG | 8 | AUG

SEP | 9 | SEP

OCT | 10 | OCT

NOV | 11 | NOV

DEC | 12 | DEC

Informing FactoryLink about the Task

You must configure FactoryLink to load and start up the task to fully integrate the new task with FactoryLink. Complete the following to inform FactoryLink about the task:

• Add the name of the AC file to the TITLES file to make the task accessible from the Main Menu.

• Execute acctmgr -c -d at the system prompt to update the AC map with the latest edition of the TITLES file.



•

•

•

•Adding the Name of the AC File to the TITLES File

When the Configuration Manager starts, it reads the file {FLINK}/ac/titles that contains a list of all AC files for the Configuration Manager to load, so the name of the AC file must be added to the TITLES file. Perform the following steps to open the task configuration table(s) from the Main Menu:

1 Open {FLINK}\ac\titles with a text editor.

2 Add filename.AC to the TITLES file. The entry location of the new AC file in the TITLES file reflects the location of that task selection on the Main Menu.

3 Save the tables file and close the editor.

4 Execute acctmgr -c -d to update the map with the latest TITLES file.

5 Open the Main Menu. If FLCM is already open, close and reopen it.

Testing the Configuration Environment

Test the Attribute Catalog using the Configuration Manager and a dBASE-compatible database manager.

Choose the new task from the Main Menu. If an error exists in the AC file or if it cannot locate a KEY file referenced by the AC file, it displays an error panel stating the nature of the problem.

Once any errors are analyzed and corrected, invoke the Configuration Manager repeatedly, each time entering a variety of simulated data in the panels, and, therefore, in the developer-created database tables. Using a compatible database manager or the CDBLIST utility included with the PAK, examine the resulting database table(s) to ensure the Configuration Manager is generating the correct and expected data and placing it in the proper location within the table.

If the Configuration Manager finds a syntax error in the AC file or if it cannot locate a KEY file referenced by the AC file, it displays an error message stating the nature of the problem. Return to the AC file and correct this error. Reopen the Configuration Manager.

If no problems exist or once any problems have been resolved, the name specified in the title parameter of the TASK statement in the AC file is displayed as a selection on the Main Menu.

CONSTRUCTING A FACTORYLINK TASKCreating a Single Point Configuration Environment


5

Co

nstru

cting

a F

actoryL

ink Task

Verify the following items are correct:

• Item name in the Main Menu

• Name in panel header

• Names of fields

Viewing Contents of a Configuration Database without FLCM

• CDBLIST dumps the contents of configuration database. The command line is:

cdblist [-d] <file.cdb> [<file.mdx]

where

-d Shows the database schema (field names, and optionally, the index expressions).

<file.cdb> Is the database file to show contents.

<file.mdx> Is the index for the given database.

CREATING A SINGLE POINT CONFIGURATION ENVIRONMENT

Extending the Single Point Dialog

The Single Point Tag Definition dialog within the Application Editor program can be extended through a combination of AC file modifications and the use of the Single Point Page Editor (PAGEDIT). The AC files must follow some basic design constraints and must be modified to make use of new extensions to the AC definition required by the Graph task.

PAGEDIT is a standalone utility that allows for the creation of additional pages for the Single Point Dialog. As the new notebook page is created, the fields on the notebook page are connected to fields in the AC file.

Adding a page to the Single Point Tag Definition dialog allows for tags to be configured within APPEDIT and creates entries in FLCM panels/databases for each configured tab page. These entries are fully compatible with those in FLCM.



•

•

•

•AC file Language Extensions

The following AC file statements have been newly created or modified from their original definition. The changes apply only to AC files used to define information for pages that will be added to the Single Point Dialog. The statements must be used in those AC files.

TASK “GTITLE” substatement

Format GTITLE "R/W Information CT name", "Tab Title String"

"R/W InformationCT name"

Defines the CT used to fill in the page.

"Tab Title String" Defines the title to display on the notebook page tab.

DEFINES statement

Format DEFINES "ACname.h"

"ACname.h" Include file that defines necessary ID numbers.

Note: ACname represents the base name of the AC file.

ID statement

Format ID CTID, Flags

CTID Unique ID number for this CT. It should be unique at least within the CT. User configured IDs start above 7000. Current FactoryLink supported ACs use the 6000 range.

Note: If you might use this extension with other third party extensions, a range of unique ID numbers should be obtained from USDATA.

Flags 0x10 = Multiple records can be entered for this page (Alarm Information only)

0x20 = Read/Write Control Table

0x80 = FIELD/SELECT format (statements contain IDs and graphics type)

Note: All Single Point Extension ACs must set this bit.

DIALOG statement

Format: DIALOG CTID, "ac/ACname.acr"

CTID Use the same unique ID number as in the ID statement for this CT. It should be unique at least within the CT. User configured IDs start above 7000. Current FactoryLink supported ACs use the 6000 range.



5

Co

nstru

cting

a F

actoryL

ink Task

"ac/ACname.acr" Name of the file in %FLINK%/ac that contains the custom notebook page information. The ac/ prefix must be included in the filename.

FIELD statement

Format FIELD Field_ID, GraphType, "Field Name", FieldType, ...

Example:

FIELD XXXXTAG, TEDIT, "TAG", CT_PTAG, ...

Field_ID Unique number for each field within the AC file that links the Single Point Dialog to column data. This value also serves as the unique object name in the translate file for title substitution on the panel.

GraphType TEDIT, LISTBOX, TOGGLE. This is used to define the field graphical representation.

FieldType CT_PTAG, CT_TAG, CT_NUMB, CT_KEY, CT_CHAR, CT_TAGNUM,CT_TAGCHAR, CT_TAGKEY

CTRLFLD statement

Format CTRLFLD Field_ID, "SELECT Name", “Field Name", FieldSize

Example:

CTRLFLD XXXX__WRITETRIG, "TABLE_NAME", "WRITETRIG", 48

Field_ID Unique number within the AC file that refers to a field within the control table displayed on the page in a read-only field.

"SELECT Name" Control table entry Field_ID is obtained from.

"Field Name" Field name as it is in the database.

Field Size Field size as it is in the database.

A simple example follows that defines a tag-based table with four fields of information and also defines a control table with five fields. All five fields from the control table are displayed read-only on the new notebook page. Information from the control panel need not be displayed on the notebook page. This example is designed as a template to allow you to change the XXXX to any string of your choice and also to change the words Template and temp to something more meaningful.

To use the template, read the next section and make the necessary changes to template.acr. Then,

• Add template.ac to the TITLES file

• Use FLCM to define a control table

• Start APPEDIT and add tags using the Single Point Dialog



•

•

•

•template.H

#define ID_RWC_XXXX 6013#define ID_RWI_XXXX 6014#define ID_STC_XXXX 6015

#define XXXXTAG 6500#define XXXXSTATION 6501#define XXXXADDRESS 6502#define XXXXDATATYPE 6503#define XXXXTABLE_NAME 6504#define XXXXUNSOLRD 6505#define XXXXEXCEPWR 6506#define XXXXREADTRIG 6507#define XXXXWRITETRIG 6508#define XXXXCOMMENT 6509

## template.AC#

XLATES “templ_ac.txt”

TASK “EDI”, “{TEMPLATE_TASK}”GTITLE “temp_1”, “{TEMPLATE_GTITLE}”

DEFINES “ac/template.h”

CT “temp_sta”, “temp_sta”, “{TEMP_STA_TITLE}”ID ID_STC_XXXX, 0xA0EDIT DEFAULTVALIDATE DEFAULTPANEL “temp_hdr”, 50, 225, 850, 599FIELD XXXXSTATION, TEDIT, “STATION, CT_NUMB, 3, 0, ““, “0, 0, 999, “v”

HEADING “{STATION1}”, 54FIELD XXXXCOMMENT, TEDIT, “COMMENT”, CT_CHAR, 40, 0, ““, ““, 0, 0, “b”

HEADING “{COMMENT2}”, 128SEQ “TABLE_NBR”, 10

DOMAIN “DOMAIN, 8

INDEX “temp_sta”, “DOMAIN+TABLE_NBR, 18

END

CT “temp_1”, “temp_1”, “{TEMP_1_TITLE}”ID ID_RWI_XXXX, 0x80EDIT DEFAULTVALIDATE DEFAULTPANEL “temp_1”, 100, 150, 850, 599DIALOG ID_RWI_XXXX, “ac/template.acr”



5

Co

nstru

cting

a F

actoryL

ink Task

FIELD XXXXTAG, TEDIT, “TAG”, CT_PTAG, 48, 0, “type”, “DIGITAL”, 0, 0, ““HEADING “{TAG3}”, 96

FIELD XXXXSTATION, TEDIT, “STATION”, CT_NUMB, 3, 0, ““, “0”, 0, 999, “V”

HEADING “{STATION4}”, 54VALIDLIST “temp_sta”, “STATION, “COMMENT”

FIELD XXXXADDRESS, TEDIT, “ADDRESS”, CT_CHAR, 22, 0, ““, ““, 0, 0, “u”HEADING “{ADDRESS5}”, 160

FIELD XXXXDATATYPE, LISTBOX, “DATATYPE”, CT_KEY, 7, 0, “type”, “ANALOG”, 0, 0, “u”HEADING “{DATATYPE6}”, 60

CTRLFLD XXXXWRITETRIG, “TABLE_NAME, “WRITETRIG”, 48CTRLFLD XXXXREADTRIG, “TABLE_NAME, “READTRIG”, 48CTRLFLD XXXXEXCEPWR, “TABLE_NAME, “EXCEPWR”, 3CTRLFLD XXXXUNSOLRD, “TABLE_NAME, “UNSOLRD”, 5

SELECT XXXXTABLE_NAME, “TABLE_NAME”, 16HEADING “{TABLE_NAME7}”, 96

SEQ “TABLE_NBR”, 10DOMAIN “DOMAIN”, 8

INDEX “temp_1”, “DOMAI+TABLE_NAME+TABLE_NBR”, 34INDEX “temp_idx”, “TABLE_NAME+TABLE_NBR”, 26

END

CT “temp_hdr”, “temp_hdr”, “{TEMP_HDR_TITLE}”ID ID_RWC_XXXX, 0xA0EDIT DEFAULTVALIDATE DEFAULTPANEL “temp_hdr”, 150, 75, 850, 599FIELD XXXXTABLE_NAME, TEDIT, “TABLE_NAME”, CT_CHAR, 16, 0, ““, ““, 0, 0, “u”

HEADING “{TABLE_NAME8}”, 96RELATE “temp_1”, “TABLE_NAME”, “temp_idx”

FIELD XXXXUNSOLRD, TEDIT, “UNSOLRD”, CT_KEY, 5,0, “ediunsol”, “NO”, 0, 0, “bu”HEADING “{UNSOLRD9}”, 88

FIELD XXXXEXCEPWR, TOGGLE, “EXCEPWR”, CT_KEY, 3,0, “yesno”, “NO”, 0, 0, “bu”HEADING “{EXCEPWR10}”, 72

FIELD XXXXWRITETRIG, TEDIT, “WRITETRIG”, CT_TAG, 48, 0, “typed”, “DIGITAL”, 0, 0, “b”HEADING “{WRITETRIG11}”, 88

FIELD XXXXREADTRIG, TEDIT, “READTRIG”, CT_TAG, 48, 0, “typed”, “DIGITAL”, 0, 0, “b”HEADING “{READTRIG12}”, 80

SEQ “TABLE_NBR”, 10


INDEX “temp_hdr”, “DOMAIN+TABLE_NBR”, 18END



•

•

•

•Using PAGEDIT

Configuration tables consisting primarily of tag based information are information tables and can be added to the Single Point Dialog provided they have a defined parent configuration table, also called control table. When this is the case, you can use the PAGEDIT utility to define new custom notebook pages that represent the information tables and display as tabs on the Single Point Dialog.

The PAGEDIT utility is a graphical interface builder that specializes in building pages for the Single Point Dialog. The basic page is constructed using drag and drop operations placing fields and labels where appropriate. Once an item has been placed, double-clicking it displays a Property Window dialog that allows you to edit the various attributes of the variable. This is where the object is linked to the appropriate field within the AC file.

PAGEDIT is started by entering pagedit at the command prompt. Once PAGEDIT is started, you can click the folder icon to bring up a file chooser to locate and open an ACR file. A template ACR file, named template.acr is included to work with the template.ac file. Figure 2-1 shows PAGEDIT’s main window that lists any opened pages in the ACR file, in this case template.acr.

The Type and Tag are displayed together on a line. The Tag is also displayed in an editable field across the bottom. Select the page line, and in the edit field, change the Tag value to match the CTID specified in the ID statement in the AC file. To test the template, replace the XXXX with the same string used in the AC file. This links the page to the information table. To continue, double-clicking the page entry will allow you to edit the page.



5

Co

nstru

cting

a F

actoryL

ink Task

The Field_ID and GraphType entries added to the FIELD statement in the AC file serve as each field connection to the notebook page. An object created in PAGEDIT is given Field_ID as its tagname and GraphType is set in the AC file based on the type of graphical object used to display the field.



•

•

•

•The following screen shows the PAGEDIT utility as it displays the page from template.acr that corresponds to the template AC file.

The Item Palette shown depicts the various objects you can place in any arrangement on the page. You add objects by pressing the left mouse button on an object in the palette and dragging it onto the page. The object can then be moved around on the page as needed.



5

Co

nstru

cting

a F

actoryL

ink Task

Notice the tag-based information is arranged at the top, and several fields from the control table are displayed in a read-only section at the bottom of the page. Since Table Name is the key field for the control table, it is represented as a pulldown listbox that allows the user to select the table the tag being input is placed into. No information from the control table need be displayed, nor is it required that all fields from the information table be displayed.

This palette button is used to place label items on the page. Label items are static and do not relate to a field in the AC file. The value of the label is set by editing the Title field in the object Property Window.

This palette button is used to place editable text fields on the page. This field type can be used for any type of alpha-numeric input. Validation of the field will be performed by a call to the CM validation. When using this object, set GraphType to TEDIT.

This palette button is used to place checkbox items on the page. The checkbox’s label works like a label item. When using this object, set GraphType to TOGGLE.

This palette button is used to place drop-down listboxes on the page. Drop-down lists are good for providing lists of key values. When using this object, set GraphType to LISTBOX.

This palette button is used to place boxes on the page. Boxes are used to group related fields together.

This palette button is used to place buttons on the page.

This palette button is used to place listbox items on the page. Use this object when you want the list to remain visible. When using this object, set GraphType to LISTBOX. (This is not implemented yet.)

This palette button is used to place combo-boxes on the page. The combo-box allows for text entry in the field, or selection from a drop-down list. When using this object, set GraphType to LISTBOX. (This is not implemented yet.)



•

•

•

•Double-clicking an object on the page displays the Property Window dialog. Figure 2-3 shows the Property Window dialog for the text field that displays the value of the Address field. The text field is linked to the AC field by setting the object Tag to the Field_ID used for this item in the AC file. The GraphType is set in the AC file based on the type of object used to represent the field. In this case, because an editable text field is used, GraphType is set to TEDIT.

Each field on the page should have a tag value that references an item in a configuration table. The Enabled checkbox determines whether or not you can the field. For read-only fields from the control table, the checkbox should be unselected. The Click Focusable checkbox controls whether the field can gain focus by clicking with the mouse or by pressing the Tab key to move to the field. The buttons display choosers to set the Foreground or Background colors and change the font used in the field.

Once all fields have been added and their tags have been set, save the ACR file and quit PAGEDIT.

Note: You can reorder the items in your list, by selecting an entry to be moved with the mouse, then holding down both the left and right mouse buttons and dragging the item to the desired location in the list.

Adding Help to Your Page

Context-sensitive help can be added to your new notebook pages. Your help will appear exactly as the standard FactoryLink notebook pages help does, providing seamless integration.



5

Co

nstru

cting

a F

actoryL

ink Task

The help can be associated with the entire page or with specific dialog items on the page. To accomplish this you need to create an ASCII file containing the information required by APPEDIT to implement the help. After the file is created you must run the mkhelp utility to build the new help source into the APPEDIT help system and move the new files into the appropriate directory. The help system supports English, French and German language versions of the help.

The ASCII text file you create to define your help must conform to the syntax described in “Source Syntax for Tag Dictionary Notebook Page Help” on page 114. The file must have the extension .ahs and the English language version must be placed in the {FLINK}\help\en\ directory. The French and German language versions must be placed in the {FLINK}\help\fr\ and {FLINK}\help\de\ directories, respectively.

It is recommended that you create your .ahs file by copying the template file provided and modifying it to describe your page. For example, to copy the three template files to mypage.ahs you would enter the following commands at the command prompt:

copy {FLINK}\help\en\template.ahs {FLINK}\help\en\mypage.ahs

copy {FLINK}\help\fr\template.ahs {FLINK}\help\fr\mypage.ahs

copy {FLINK}\help\de\template.ahs {FLINK}\help\de\mypage.ahs

The Template Source File

The contents of the template help source file provided with FactoryLink are shown below. Keywords are those that begin with the @ symbol. Definition constants are those words that are fully capitalized. Many of these definitions are derived from entries from within the related AC file.

For example, the identifier for the template dialog is specified in the template AC file as ID_RWI_XXXX. This identifier is referenced many places within the page help source file to associate the help with the appropriate page. This applies to the definition constants (i.e. XXXXDATATYPE) associated with field definitions.

@comment(****** start of section for CT 'ID_RWI_XXXX' ******)@section(ID_SPTDLG_ID_RWI_XXXX_GFI_HELP Help on Template Definitions)@parent(ID_SPTDLG_GFI_HELP)@context(Context_XXXXPAGEOVERVIEW)@italic(Template Page Overview)

Description of the Template page goes here...

@begin(literal)@relmargin(36 8)@popup(STATION Logical Station)



•

•

•

•@popup(TABLE_NAME Table Name)@link(Context_XXXXADDRESS Address)@link(Context_XXXXDATATYPE Data Type)@popup(CANCEL_BUTTON Cancel)@popup(CLEAR_BUTTON Clear)@popup(WRITETRIG Write Trigger)@popup(READTRIG Read Trigger)@popup(EXCEPT_WRITE Exception Write)@popup(UNSOL_READ Unsolicited Read)@end(relmargin)@end(literal)

@comment(** section for field ’XXXXADDRESS’ in CT ’ID_RWI_XXXX’ **)@section(ID_SPTDLGFI_TAGNOTEBKID_RWI_XXXXXXXXADDRESS Address)@parent(ID_SPTDLG_ID_RWI_XXXX_GFI_HELP)@context(Context_XXXXADDRESS)@italic(Address)

@begin(literal)

Address description goes here.

@end(literal)

@comment(** section for field ’XXXXDATATYPE’ in CT ’ID_RWI_XXXX’ **)@section(ID_SPTDLGFI_TAGNOTEBKID_RWI_XXXXXXXXDATATYPE Data Type)@parent(ID_SPTDLG_ID_RWI_XXXX_GFI_HELP)@context(Context_XXXXDATATYPE)@italic(Data Type)

@begin(literal)

Data Type description goes here.

@end(literal

Source Syntax for Tag Dictionary Notebook Page Help

@comment(<comment string>)

These entries add comments to the help source, allowing for easier maintenance of the source. These do not affect the contents or presentation of the page help.

@section(ID_SPTDLGFI_<AC DIALOG define>_GFI_HELP <description>)



5

Co

nstru

cting

a F

actoryL

ink Task

@section(ID_SPTDLGFI_<AC DIALOG define><AC FIELD define> <descr.>)

Every help topic is called a section, and the section keyword associates a name and a description string to each topic.

For APPEDIT’s help to associate a topic with a notebook page, the help section's name is built from the AC's dialog identifier. For example, the section describing the template's page has the name ID_SPTDLG_ID_RWI_XXXX_GFI_HELP, where ID_RWI_XXXX is the identifier of the template AC's dialog.

For Appedit's help to associate a topic with an item on a notebook page, the help section's name is built from a combination the AC's dialog identifier and the AC's field identifier for the related item. For example, the section describing the template's page ADDRESS text input field has the name ID_SPTDLG_ID_RWI_XXXXXXXXADDRESS where ID_RWI_XXXX is the identifier of the template AC's dialog and XXXXADDRESS is the identifier of the template AC's ADDRESS field.

@parent(ID_SPTDLG_GFI_HELP)@parent(ID_SPTDLG_[<AC DIALOG define>]_GFI_HELP)

The parent keyword establishes the help section hierarchy. All page overview help sections have the same help section parent, denoted by the section name ID_SPTDLG_GFI_HELP.

The parent of a field help section is the help overview section for the page, and the name of the page's overview help section name should be used.

@context(Context_<AC FIELD define>)

The context keyword creates subtopic within the current section for the given name.

For the help section describing an item on a page, the context name must have the name of "Context_" concatenated with the AC identifier for the field item.

@link(Context_<AC FIELD define> <link title>)

The link keyword establishes a jump from the current context to the given context.

@popup(<internal define> <link title>)

The popup keyword establishes a jump from the current context to the given context, but creates a popup window to show the linked information. The APPEDIT convention for popup help is to display help that is common to several pages. The template example shows the help definition names useful for displaying common descriptions, such as for the CANCEL button.

@italic(<description string>)



•

•

•

•@begin(literal) @end(literal)@relmargin(<left_margin> <right_margin>)@end(relmargin)

These keywords affect the presentation of the help text in the manner that the keyword suggests.

Building Your Notebook Page Help into APPEDIT

Once your .ahs file has been created you must build it into the APPEDIT help system. When you distribute your application to users, this process occurs automatically during the installation procedure. During development you need to use the mkhelp utility to build your help into the APPEDIT help system. Enter the following at the command prompt to run mkhelp:

mkhelp -c

If an error associated with your help file occurs during the build process the error messages are written to the file vdebug.log and the appropriate {FLINK}\help\<en\fr\de> directory.

Running the mkhelp program builds the appedit.vhs file for each language and places it in the appropriate {FLINK}/dll/<en\fr\de> directory. A copy of the file corresponding to the current language is placed in the {FLINK}\bin directory.

CONSTRUCTING A FACTORYLINK TASKPreparing Configuration for Run Time


5

Co

nstru

cting

a F

actoryL

ink Task

PREPARING CONFIGURATION FOR RUN TIME

This section provides details for setting up the configuration environment that includes the following tasks:

• Convert Database Tables to CTs

• Create the CTG Conversion Scripts

• Test the Conversion Process

The figure below illustrates the portion of the Task Construction Flowchart involved in converting database tables to CTs.

Run CTGEN

Examine BinaryCT File

Edit ScriptProblems

with CT Files?Yes

No

Create CTGConversion Script



•

•

•

•Create the CTG Conversion Scripts

Conversion Overview

The conversion process translates database tables into run-time, binary configuration tables. The binary tables are arrays of records with a format that matches the internal C-structure within the target task. This enables FactoryLink run-time tasks to load the tables with little or no additional processing. The task simply copies the data into its internal structure.

All run-time CTs use a common archive format. The term archive refers to the binary CT file containing data for more than one database table. For example, the TIMER.CT file contains information for the event timer and interval timer database tables.

The following information is created in a CT file:

1. Each CT file begins with an archive header indicating the number of CTs in the archive.

2. The header is followed by an index entry for each CT. Each CT consists of an optional header section followed by zero or more records. Each record within a CT has the same format:

[CT archive header]

[CT index 0]

[CT index 1]

[CT index n]

[CT 0 header]

[CT 0 records]

[CT 1 header]

[CT 1 records]

[CT n header]

[CT n records]

Library services are provided that enable a task to read the CT files. The developer determines the contents of the CT header and CT records that vary according to the database table.

Conversion Script Format

A conversion script, which is processed by the CTGEN utility, controls conversion of database table information into CT files. Generally, design the conversion script so the output from CTGEN matches the run-time task data structures. This allows the run-time task to read the



5

Co

nstru

cting

a F

actoryL

ink Task

binary data from the CT archive directly into memory. The /{FLINK}/CTGEN directory contains sample CT conversion scripts.

The format of a conversion script is

TABLE type, name, hdrlen, reclenHEADER database, namefield

SORT “FIELD1”,”FIELD2”DOMAIN “DOMAIN”, S, 8FIELD name, format, storage, [options]RECORD database, namefield, indexfile

SORT “FIELD1”,”FIELD2”,”FIELD3”DOMAIN “DOMAIN”, S, 8FIELD name, format, storage [option] [DEFAULT dfltval]SKIP count, value

The following paragraphs describe this format.

TABLE

TABLE type, name, hdrlen, reclen

The TABLE statement defines one CT type in the archive. The values of the parameters are placed in the appropriate fields in the CT index record. A single TABLE definition may result in multiple CT index entries. The HEADER database determines the number of times the table is repeated.

Multiple TABLE definitions may exist in the script. Each one is processed in order.

HEADER

HEADER database, namefield


type Table type ID. Integer ordinal (0-65536).

name Table name String of up to 10 characters.

hdrlen Number of bytes of a header record.

0 (CTGEN automatically calculates this value.

reclen Number of bytes of a data record. 0 (CTGEN automatically calculates this value.



•

•

•

•The HEADER statement defines the format of the header section of the CT. No more than one header record is written for a CT; however, the header record may be non-existent.

RECORD

RECORD database, namefield, indexfile

The RECORD statement defines the format of the repeated record entries in a CT. Multiple RECORD statements are allowed. Each is processed in order.


database Name of the database table to be used.

Valid database table name (string of characters enclosed in quotes).

namefield Controller of the repeated record section.

Null or non-null string

If the value is: Then:

null string: all records in the repeated section are written.

non-null string: the value of the indicated field is used to fill in the name member of the CT index record and to select repeated records.


database Name of the database table to be used.

Valid database table name.

namefield Field in the RECORD database that must match the Namefield field in the current record of the HEADER. If this parameter is not specified, the HEADER namefield is not specified, or the HEADER is non-existent, then all records in the RECORD database are written to the CT. This field should be the primary key.

Valid field name.



5

Co

nstru

cting

a F

actoryL

ink Task

DOMAIN

DOMAIN “DOMAIN”, S, 8

Enter the DOMAIN statement exactly as shown above for each configuration panel in each CTG file if the source database table has a DOMAIN field. Do not change the statement.

where

DOMAIN References the domain field in the database in the CDB file, which is created by the DOMAIN statement of the corresponding AC file. For additional information about AC files, refer to “Create the Attribute Catalog(s)” on page 73.

S Indicates the domain directory name consists of a character string.

8 Is the number of characters in the domain directory name. This number must be the same as the number in the DOMAIN statement of the corresponding AC file.

The DOMAIN statement in the CTG file places the CT file in the domain-specific path specified in this parameter, which is {FLAPP}/{FLDOMAIN}/*.CT.

Failing to put this statement in means the configuration is domain independent resulting in the CT being placed at {FLAPP}/ct. This usage is the exception rather than the rule.

FIELD

FIELD name, format, storage [option] [DEFAULT dftval]

The FIELD statement defines the translation of one field in the database table to bytes in the CT entry. Include as many FIELD statements as necessary.

indexfile Name of the index file used to read the records.

Index containing namefield as the primary key.



name Field name of the database field to be used.

Valid field name.



•

•

•

•

format Output format for the database field. The format is specified by a single character.

T Data is a two-word TAG C-structure containing segment and offset. Use only for Tag Fields.

S ASCII string.

D Binary output. The database field is considered to be a string of numerical

digits representing a decimal value.

X Binary output. Field assumed to contain hexadecimal number string.

O Binary output. Field assumed to contain octal number string.

F Double output. Field assumed to contain a precision float number string.

storage Number of bytes in the output record the value occupies. The database value is truncated or null-padded to fit the output field width.

Number of bytes.

For format: Then:

T TAG structure byte size is 4.

S String length (add 1 to guarantee termination)

D Integer length: 2 for i16; 4 for i32

X Integer length: 2 for i16; 4 for i32

O Integer length: 2 for i16; 4 for i32

F Double byte size is 8.




5

Co

nstru

cting

a F

actoryL

ink Task

Handling Tag Constant Fields

Generally, each tag constant field in the AC file results in two references to that field within the CTG script. One field reference outputs the field as a tag and the other reference outputs the field as a constant value. When outputting the constant value, append to the CONST or KEYCONST keyword so the field value returns as 0 or a NULL string if a tag name has been entered in the field. The CONST option applies to character or numeric constants and the KEYCONST option applies to key constants. When outputting a constant value as a TAG, the returned tag equals the invalid tag identifier {-1, -1}.

CTG File Example

FIELD “YEAR”, T, 4, TAG

FIELD “YEAR”, D, 2, CONST DEFAULT -1

FIELD “MONTH”, T, 4, TAG

FIELD “MONTH”, D, 2, KEYCONST “month” DEFAULT NUL

FIELD “DOW”, T, 4, TAG

FIELD “DOW”, S, 4, CONST

option Specifier of additional information about how the data in the input field is converted.

Option keywords:

TAG Output as a name, segment and offset as binary as numerical values.

DIM The dimensions of the TAG contained in the database field is used as the output data.

TYPE The type of the TAG contained in the database field is used as the output data.

KEY <keyfile> Specifies the keyfile to use to translate the field string value into a numeric value.

dftval Default value. Specifies the default value to be used if the database field contains a NULL string.




•

•

•

•SKIP

SKIP count, value

A SKIP statement causes one or more bytes to be written to the output. The SKIP statement allows padding of fields to match the task data structures as well as insertion of specific binary data into the CT file. Include as many SKIP statements as needed. FIELD and SKIP statements may be mixed in any order.

SORT

The SORT statement defines the order records are read in from the configuration databases and written to the binary CTs or the repeated header or record entries in a CT. The SORT immediately follows the HEADER or RECORD it applies to and may contain one or more field names to be used to sort the entries. Only one SORT statement is allowed per HEADER or RECORD entry.

By default, the order of CT information conform to ordering viewed from the configuration database.

Sample Conversion Script

The following file is a sample conversion script included in the PAK software as SKEL.CTG. It is found in the {FLINK}\src\examples\skeleton directory.

TABLE 0, “”, 4, 4HEADER “SKELTRIG.CDB”, “TABLE_NAME”

FIELD “TRIGGER”, T, 4, TAG DOMAIN “DOMAIN”, S, 8


count Number of bytes to output. Integer value greater than 0.

value (Optional) Byte value used to fill the output record.

Value of the byte (default = null).


sort field Field names. TABLE_NBR, DOMAIN, or any field name in the header or record being sorted.



5

Co

nstru

cting

a F

actoryL

ink Task

RECORD “SKELTAGS.CDB”, “TABLE_NAME”, “SKELTAGS,CDX” FIELD “TAG”, T, 4, TAG DOMAIN “DOMAIN”, S, 8

Creating FactoryLink Configuration Tables (CTs)

The binary CT file contains the information specified in the task database table(s). The CTGEN utility binds (converts) the tag names specified in the database tables to tag numbers maintained by the Real-Time Database. At run time the task loads the CT file and builds any internal structures required to perform the job. To improve performance, tasks use the tag number from the CT instead of the tag names in the database table(s) to access the Real-Time Database.

Integrating a Conversion Script into FactoryLink

Conversion scripts must reside in directory {FLINK}\ctgen. For the system to be aware of and process a conversion script, an entry for it must be appended to the CTLIST file that resides in {FLINK}/ctgen. With a text editor, append a line in the following format:

<task>: <cdb> <cdb> …

The <task> entry is the name of the conversion script without the .ctg extension. The names that follow are the configuration database file names without the .cdb extension referenced within the conversion script. This equates to a dependency list where, if the binary CT for the task is older than any of the listed CDBs, regenerate the binary CT.

For example, the entry for the skeleton task is:

skel: skeltrig skeltags

The Binary CT Generation Utility - CTGEN

CTGEN uses the CTLIST file to build CTs and rebuild all CTs whose database tables have changed. CTGEN can be run stand-alone or with a combination of parameters.

To run CTGEN, enter the following command at the DOS prompt:

ctgen <Enter>

To run CTGEN with parameters, enter the following command at the DOS prompt:

ctgen [-i<name.ctg>][-a <flapp>] [-o<ouput path>] -c -r -v(#) <Enter>



•

•

•

•where

-i Indicates only those CTs referenced within the specified CTG file are to be rebuilt. Next to -i, enter the file name of the CTG file to be used. ({FLINK}/CTGEN is the default directory.)

-a CTs in alternate FLAPP directories.

-o Indicates the output is to be redirected to the specified file. (The default is {FLAPP}/CT/NAME.CT.)

-c Indicates all element numbers (segments and locations) are to be cleared before the CT is generated. (Must be followed by -r).

-r Indicates all files are to be rebuilt. (Usually preceded by -c).

-v (#) Indicates verbose mode and level. Each verbose level displays cumulative messages. For example, v2 displays general activity messages and historian and client task messages. Choose v1 for general viewing. Use v2-v4 for debugging..

Debugging the Conversion Process

CTLIST, a command line utility that dumps the contents of a binary CT into a readable format, is useful for debugging purposes. Developers use this tool to view how CTGEN translated the CDBs into a collection of headers and records according to their CTG scripts and then to adjust these scripts accordingly. The actual binary data within the records are presented as hexadecimal with paired bytes in reverse order.

Usage: ctlist <file.ct>

where

<file.ct> CT file to dump.

Valid Entries Descriptions

v1 Displays general activity messages.

v2 Displays historian and client task messages.

v3 Displays the parsing of .CTG file tokens.

v4 Displays tag names as they are written to the database.

CONSTRUCTING A FACTORYLINK TASKWriting the Run-Time Task


5

Co

nstru

cting

a F

actoryL

ink Task

WRITING THE RUN-TIME TASK

For the Run-Time Manager to effectively perform FactoryLink task management duties, each FactoryLink task must adhere to certain run-time requirements so the Run-Time Manager monitors specific database elements in the Real-Time Database on a per-task basis.

The requirements include:

• Initialization

• Kernel Check

• Error Handling

• New Configuration Notification

• Termination Notification

• Orderly Shutdown

In addition, for proper operation in a foreign language environment, the task should use fl_xlate to translate any output messages into the language being used and fl_xlate_init to load the translations when the task is started.

CONSTRUCTING A FACTORYLINK TASKWriting the Run-Time Task


•

•

•

•The following figure illustrates the portion of the Task Construction Flowchart involved in completing run-time requirements.

Create SourceModules

ProblemsCompiling?

Link ObjectModules

Execute Program

ProblemsFound?

Edit Source andLink Files

ProblemsLinking?

Debug Program

Create InstallationMedium

Yes

Yes

Yes

Compile SourceModules

No

No

No

Edit SourceModules

CONSTRUCTING A FACTORYLINK TASKInitialization


5

Co

nstru

cting

a F

actoryL

ink Task

INITIALIZATION

First, the task attaches with the Real-Time Database (or Kernel) by calling FLIB function fl_proc_init( ) to obtain a task id (taskid). Function fl_proc_init( ) uses environment variables {FLNAME}, {FLDOMAIN}, and {FLUSER} to determine which Real-Time Database to attach. If the task needs to attach elsewhere, FLIB function fl_proc_init_app( ) can be called.

If the call fails (taskid = ERROR), the task writes an appropriate error message to STDOUT and calls EXIT.

If the call succeeds (taskid! = ERROR), the task obtains the task environment elements by calling to fl_get_env( ). The environment elements, which are used to communicate with the Run-Time Manager, include the following information:

• Status element for reporting task status as an ANALOG value

• Message element for reporting task status as a MESSAGE

• Application path specification

• Program path specification

• Command line arguments

Then, the task writes FLS_ACTIVE to its status element and Running to its message element. This causes the Active symbol to be displayed in the STATUS column and Running to be displayed in the MESSAGE column of the Run-Time Manager display.

KERNEL CHECK (CONDITIONAL)

If proper execution of the task depends on the version of the Kernel installed on the system, obtain the Kernel’s version and release number by calling fl_get_version( ). Check the values obtained against your own list of compatible values. As a rule, an unacceptable version or release number should be considered a fatal error. If this occurs, write an appropriate error message to STDOUT and call EXIT.

CONSTRUCTING A FACTORYLINK TASKError Handling


•

•

•

•

ERROR HANDLING

If the task encounters any errors, failures, or other problems during execution, it reports appropriate error messages to its environment STATUS and MESSAGE elements.

• In case of a fatal error, the task exits following the shutdown procedure described in the Orderly Shutdown requirement.

• In case of a non-fatal error, the task sets its environment STATUS element to FLS_ERROR. This indicates to the Run-Time Manager the task encountered problems but is continuing execution, and the Run-Time Manager displays ERROR in the STATUS column of its display. The task writes a description of the problem to its environment MESSAGE element

NEW CONFIGURATION NOTIFICATION

Custom tasks developed by users and 3rd party vendors can be enabled for online configuration simply by creating an RTM file for each task that gets installed into the {FLINK}\CTGEN directory. The format for the RTM files is described below and in the PAK Manual.

The RTM File and Task Bumping Determination

A new file type, the RTM file, lists the bump dependencies for individual tasks. If any file in the list is newer than when the task last started, RUNMGR needs to bump the associated task.

RTM file format:

The syntax is as follows:

BUMP <bumpname>METHOD <CYCLE | SIGNAL>[FILE_DEPENDENCY <filespec> [, <filespec>]][BUMP_DEPENDENCY <bumpname> [, <bumpname>]]

ENDBUMP

GROUP <bumpname>BUMP_DEPENDENCY <bumpname> [, <bumpname>]]

ENDGROUP* <comment>

The BUMP keyword establishes a record that holds the criteria for when a task should be bumped. Token <bumpname> should match the task name used to obtain a task ID from the kernel (fl_proc_init()). The ENDBUMP keyword closes the record definition.

CONSTRUCTING A FACTORYLINK TASKNew Configuration Notification


5

Co

nstru

cting

a F

actoryL

ink Task

The METHOD keyword indicates what method is used to update the given task with online configuration. If the following keyword is CYCLE, the task will be stopped and restarted. If the following keyword is SIGNAL, the task will be sent the kernel signal FLC_SIG_NEWCONFIG. If a task is to be signaled instead of cycled, then the developer must modify the task code to recognize the signal and dynamically reload its configuration information. Only one method definition is allowed and required per bump record definition.

The FILE_DEPENDENCY keyword precedes the comma-delineated list of files on which the task is dependent. The <filespec> entry is a file specification relative to the current FLAPP, although full paths can be specified. Wildcards are allowed, as are environment variables denoted by braces. One or more file dependency lists can be included within a single bump record definition.

The BUMP_DEPENDENCY keyword precedes the comma-delineated list of additional bump record names on which the task is dependent. The <bumpname> entry should match the <bumpname> used to define a separate BUMP record or group. One or more bump dependency lists can be included within a single bump record definition.

The GROUP keyword establishes a collection of dependencies that are not tied to any particular task. Hence, token <bumpname> should not match any task name. However, these groups can be referenced in other record or group bump dependency lists, thereby reducing the amount of information duplicated across the individual task bump record definitions. An example of where this is useful is the historian and client tasks. All the client tasks are dependent on the historians and must be bumped if an historian is bumped. Using the GROUP method the individual historian task names do not need to be referenced in the RTM file for each client. In addition, if a new historian is defined, only one file needs to be updated instead of several. The ENDGROUP keyword closes the group definition.

Finally, more than one bump records can exist in an RTM file. Also, comment lines are denoted an asterisk (*) at the beginning of the line.

Examples:

SKEL.RTM:* RTM file for the Skeleton task

BUMP skelMETHOD CYCLEFILE_DEPENDENCY ct\skel.ct*

ENDBUMP

PERSIST.RTM:BUMP persist

METHOD SIGNALFILE_DEPENDENCY ct\persist*, ct\object.ct*

ENDBUMP

CONSTRUCTING A FACTORYLINK TASKTermination Notification


•

•

•

•HISTRIAN.RTM:

GROUP historiansBUMP_DEPENDENCY or7_hist, db4_hist, syb_hist, odbchists

ENDGROUP

DPLOGGER.RTM:BUMP dplogger

METHOD CYCLEFILE_DEPENDENCY ct\dplogger.ct*BUMP_DEPENDENCY historians

ENDBUMP

Signaled Task Requirements

If a custom task is to be signaled instead of stopped and restarted, the developer must modify the task code to be able to receive signals and recognize the newly added online configuration signal. Refer to the PAK manual for documentation on how to implement signal handling using the fl_hold_sig() and fl_recv_sig() API functions. The FLC_SIG_NEWCONFIG has been added to support signaling tasks during an on-line update. Upon receiving the FLC_SIG_NEWCONFIG signal, a task can adjust its configuration in accordance to the latest CT files. Exactly what this entails and how it is actually done is totally up to the developer and specific to each task design and requirements.

TERMINATION NOTIFICATION

A task must shut down when the Run-Time Manager notifies it to do so. Tasks must check the current status of the task termination flag often. They do this by calling fl_test_term_flag ( ).

• If the value of the flag is 1 (ON), the task goes through the shutdown procedure in and writes normal shutdown to its environment MESSAGE element.

• If the value of the flag is 0 (OFF), the task continues execution.

You are able to terminate the task from the Run-Time Manager, and the task must terminate along with its associated FactoryLink session.

CONSTRUCTING A FACTORYLINK TASKOrderly Shutdown


5

Co

nstru

cting

a F

actoryL

ink Task

ORDERLY SHUTDOWN

The task performs the following actions before calling EXIT:

• Writes a message explaining the reason for termination to its environment MESSAGE element, which is then displayed in the MESSAGE column of the Run-Time Manager display.

• Sets its environment STATUS element to FLS_INACTIVE, which causes the Inactive symbol to display in the STATUS column of the Run-Time Manager display.

The task then terminates execution via fl_proc_exit( ).

Message Translation

Rather than using hard-coded messages, tasks should translate error and informational messages so multiple languages can be supported. Instead of saying “showerr (“error:out of memory”), the task should say “showerr (fl_xlate (“NORAM”)). Then, the following records should correspond to the following files:

{FLINK}/MSG/EN/taskname.txt: record NORAM out of memory

{FLINK}/MSG/FR/taskname.txt: record NORAM Memoire insuffisante

{FLINK}/MSG/DE/taskname.txt: record NORAM Nicht genug Speicher

TASK PROGRAM SKELETON

A sample FactoryLink program written in the C language resides in {FLINK}/Src/examples/skeleton. This program demonstrates proper programming practices, standards, and conventions. It illustrates the interaction of the program with the Run-Time Manager. Use it as a base to build your custom tasks from.

CONSTRUCTING A FACTORYLINK TASKTask Program Skeleton


•

•

•

•

6

PA

K L

ibrary S

ervices



PAK Library Services

The FactoryLink Library (FLIB) contains a set of callable software services that FactoryLink builds tasks with. The library services are divided into the following categories:

• Kernel Interface

• Task/Session Management

• Real-Time Database Access

• Calling and Return Conventions

• CT Access

• Object CT Access

• Direct Tag Processing

• Normalized Tag Reference

• Path Manipulation

• Message Translation

This manual assumes you develop client processes in the C Programming Language or in a language that provides a calling sequence compatible with the C language. This chapter includes information about the service functions and how to use them.

Function names are case-sensitive. All API function names are entirely lower-case. For example, a client process calls fl_proc_init( ) with the following command:

taskid = fl_proc_init(“RUNMGR”, “Run-Time Manager”) ;

Note: In general, always include FactoryLink headers after system headers to avoid any definition conflicts.

PAK LIBRARY SERVICESKernel Interface Services


•

•

•

•

KERNEL INTERFACE SERVICES

The Kernel interface services enable tasks to attach to the Kernel and to transact data transfers with the Real-Time Database. In other words, these are the hooks that allow your program to ride FactoryLink’s software bus. The discussion on the Kernel interface services is divided into three areas:

• Kernel/Task Session Management

• Real-Time Database Access

• Calling Conventions and Exception Reporting

Task/Kernel Session Management

The Kernel/Task Session Management discusses task interaction with the Kernel. Topics covered are

• Attaching to and Detaching from the Kernel

• Obtaining Task Environment Information

• Locking and Unlocking the Kernel

• Signals

• Miscellaneous Kernel Services

Attaching/Detaching from the Kernel

These functions help the Kernel and the Run-Time Manager control client processes. Since a prospective client must make itself known to the Kernel before doing anything, it must successfully call fl_proc_init( ) that assigns a FactoryLink ID before calling any other Kernel service. An exception to this rule is any functions that do not have the FactoryLink ID as one of the arguments. A client process may not call any other Kernel service after calling fl_proc_exit ( ), which releases to the system or renounces the caller’s FactoryLink ID.

Function Description

fl_proc_init Attach to the Kernel.

fl_proc_exit Detach from the Kernel.

fl_set_term_flag Sets the termination flag of a client process.

fl_test_term_flag Asks the Kernel the status of current task termination flag.



6

PA

K L

ibrary S

ervices

Using the Task/Kernel Management Functions

The process management functions are C functions callable by C-language application and system programs. The library functions make calls to the FactoryLink Kernel. It is the duty of the Kernel to maintain a task table. The task table holds all information relevant to running tasks and furnishes services allowing access to and limited manipulation of the data stored in this table.

FactoryLink tasks process real-time data until it detects its termination flag has been set. This is accomplished by frequently calling function fl_test_term_flag( ).

Sample Task Attachment/Detachment

The following example illustrates the use of the process-management functions. It does not illustrate the interaction of a task with the Run-Time Manager.

#include “FLIB.H”

char name[] = “MYNAME”; /*my name(name of this task)*/

int taskid; task number to be assigned*/

main() /*PROGRAM ENTRY POINT */{

/*————————-WITHIN START-UP CODE—————————*/if ((taskid = fl_proc_init(name,desc)) == ERROR)

/* first library call: */{ /* tell the Kernel who I am */printf(“Cannot get task number\n”);exit(1); /*abort for stated reason */}while (fl_test_term_flag(taskid) == OFF)

/* continue execution until */{ /* flag is turned ON *//*——————-MAIN LOOP OF TASK-DEPENDENT CODE—————*//*————————————-GOES HERE——————————-*/}

/*—————————-WITHIN CLEAN-UP CODE————————*/fl_proc_exit(taskid); /* tell Kernel I'm exiting */

/

exit(0)/* exit to OS */

}



•

•

•

•Obtaining Task Environment Information

The Kernel provides read-only access to the FactoryLink environment attributes. The environment access services consist of the following functions.

Locking and Unlocking the Kernel

Often times, a task needs to transact several operations with the Kernel without being interrupted by another task.

For example, a task may want to both write a value to a tag and clear its change bit for that tag without the possibility of another task writing a value to that tag between the two operations, which would result in the task missing the change since it subsequently clears the change flag.


fl_get_env Returns KENV structure of the client process.

fl_get_ctrl_tag Returns control tag for the specified process.

fl_get_stat_tag Returns value of the Real-Time Database analog status element for the specified process.

fl_get_msg_tag Returns value of the Real-Time Database message element for the specified process.

fl_get_pgm_dir Returns program directory for the specified process.

fl_get_app_dir Returns application directory for the specified process.

fl_get_cmd_line Returns command line for the specified process.

fl_get_title Returns pointer to the name of the product (FactoryLink).

fl_get_copyrt Returns a pointer to a copyright message.

fl_get_version Gets the Kernel version number.


fl_lock Locks the Real-Time Database on behalf of the calling process.

fl_unlock Unlocks the Real-Time Database for the calling process.



6

PA

K L

ibrary S

ervices

By placing an fl_lock( ) and fl_unlock( ) combination around small portions of the code, the task assures that intermediate values will be unavailable until the transaction is over. However, care must be taken with these functions for no other tasks can access the Kernel while a lock is held. Lengthy locks seriously degrade performance and an unreleased lock prevents the entire application from performing any work.

Signals

Signals are notifications of events, particularly change of status, sent by one process to another, referred to as the target process. Signals are a form of inter-process communication (IPC). In some cases, the Kernel itself may send a signal to a target process, but this is still a form of IPC since the Kernel always executes in the context of the calling process and acts on its behalf. The target process, rather than the caller, is notified of the event or what status has changed.

Mailbox services also provide an IPC mechanism to FactoryLink processes. Compared with signals, mailboxes allow data passing and are more flexible; however, they are slower. Also, messages sent to a given mailbox are placed in a queue, so they are read in the same order as they are sent. Signals are prioritized but not queued.

Signals provide a primitive, but very fast, form of IPC; therefore, they are ideally suited for process synchronization. Each signal is assigned a numerical value in the range 0-31 so only 32 different events can be described by signals. The following events are predefined by the Kernel and have special meaning.

The signal services consist of the following functions.

Signal Symbolic Name Meaning

0 FLC_SIG_TERMINATED Process has been terminated.

1 FLC_SIG_TERM_FLAG_SET Termination flag is set.

2 FLC_SIG_TAG_LIST_CHANGED Tag list has been changed.

3 FLC_SIG_MESSAGE_RECEIVED Message has been received.


fl_send_sig Sends a signal to a target process.

fl_recv_sig Receives a signal for the calling process.



•

•

•

•

Miscellaneous Session Services

The Kernel provides service functions to do miscellaneous odd jobs that fall into none of the other categories. These include database lock/unlock functions (semaphores), sleep/wake functions, initialization functions, and system data item retrieval functions.

The miscellaneous services consist of the following functions.

Database Access Services

The Real-Time Database Access section discusses transferring data values to and from the Real-Time Database. Topics covered are

• Reading and Writing Elemental Database Values

• Change Bits

• Reading and Writing Mailbox Messages

fl_hold_sig Prevents or allows signal delivery for the calling process.


fl_wakeup Awakens a mask of client processes.

fl_wakeup_proc Awakens a specified process.

fl_get_tick Gets the current clock tick and/or current date and time maintained and reported by the operating system.

fl_global_tag Retrieves the tag number for one or more global elements.

fl_name_to_id Translates a process name to a FactoryLink ID.

fl_id_to_name Translates a FactoryLink ID to a process name.

fl_sleep Forces program to release the CPU for a given period of time.

spool Sends a file to the FactoryLink spool task.




6

PA

K L

ibrary S

ervices

Any task may read a given Real-Time Database element; however, only one task, the “defining task,” should write it. This restriction is not enforced, but it is a good design technique to use to avoid possible ambiguity in the Real-Time Database.

Using the Database Access Functions

The database access functions are functions callable by C-language application and system programs. The Library functions make calls to the Kernel. The Kernel maintains the Real-Time Database shared among all client processes and permits client processes to access it only through these functions.

The database access services consist of the following functions.


fl_read Reads specified elements from the Real-Time Database.

fl_write Writes specified elements to the Real-Time Database.

fl_forced_write Force-writes a specified element to the Real-Time Database.

fl_wait Waits to read, write, or access the Real-Time Database or certain elements in the database.

fl_change_wait Reads the first Real-Time Database element that has changed since it was last read; if no change, goes to sleep until a change occurs.

fl_change_read Reads the first Real-Time Database element that has changed since it was last read.

fl_set_chng Sets the calling task change-status flags for specified Real-Time Database elements.

fl_clear_chng Clears the calling task change-status flags for specified Real-Time Database elements.

fl_get_tag_info Gets the information associated with a specified list of Real-Time Database elements.

fl_set_wait Sets the calling task wait flags for specified Real-Time Database elements.

fl_clear_wait Clears the calling task wait flags for specified Real-Time Database elements.



•

•

•

•Real-Time Database

The corresponding typedefs for each data type are found in FLIB.H.

Database Elements

A Real-Time Database element consists of the following items:

• One or more bits containing the element value

• Set of change-status bits

• Set of wait bits

Each set of bits consists of a single bit for each client process or, more properly, for each potential client process. A process does not officially become a client process until it registers with the Kernel by initializing the calling process through a call to fl_proc_init( ), but the bits still exist.

Change-status bits. For each database element, each possible client process has one change-status bit. If the value of a bit is 0 (OFF), the value has not changed since client (or task) number N last read the element where N = 0 through 30. The value of the bit is set to 1 (ON) when a new value is written to the element.

Wait bits. Each possible client process has one wait bit. When the client is currently waiting to read or to write the specified element, the value of the bit is 1 (ON); otherwise, the value is 0 (OFF). A client can set the value of a wait bit to 1 (ON) by performing one of the following actions:

• Call fl_change_wait( ). This sets the value to 1 (ON) only if none of the specified elements has changed (it sleeps until someone writes a new value into one or more of the elements).

• Call fl_set_wait( ).

Tag Number. In the Kernel, a tag number completely specifies a database element because it includes the data type as well as the array index. All database access service operates on mixed types; that is, on elements of various data types defined and allocated at run time.

Locking/Unlocking the Database

The Kernel automatically locks the database during execution of any of these database access functions and unlocks it upon completion. This ensures service calls are atomic operations in the sense that, once begun, they cannot be interrupted by service calls from other clients. The only exception is when the calling process may block another process waiting to write synchronous elements.



6

PA

K L

ibrary S

ervices

VAL Union Structure

All database types besides message and mailbox are read and written the same way, accessing the correct member of the union.

Sample Database Access Functions

The following examples illustrate the use of the database access functions in the FactoryLink Library. These examples are not complete C programs. None of the examples illustrates the interaction of the task with the Run-Time Manager.

Example A

Example A demonstrates how to use fl_read( ) to read messages from the database.

.

.int task_idTAG t;VAL v;char buffer[100];

v.msg.m_ptr = buffer;v.msg.m_len = 0;v.msg.m_max = sizeof(buffer);fl_read(task_id, &t, 1, &v);

.

.

Example B

Example B demonstrates how to use fl_write( ) to write messages into the database.

Database Type Union

DIGITAL val.dig

ANALOG val.ana

LONGANA val.lana

FLOAT val.flp

MESSAGE val.msg

MAILBOX val.mbxmsg



•

•

•

•..int task_id;TAG t;VAL v;char buffer[100];

strcpy( buffer, “The temperature is”);v.msg.m_ptr = buffer;v.msg.m_len = strlen(buffer);v.msg.m_max = sizeof(buffer);fl_write(task_id, &t, 1, &v);

.

.

Example C

Example C demonstrates how to use fl_read( ) to read analog values from the database.

.

.int task_id;TAG t;VAL v;

fl_read(task_id, &t, 1, &v);printf( “The ANALOG value is %d\n”, v.ana);

.

.

Example D

Example D demonstrates how to use fl_write( ) to write analog values to the database.

.

.int task_id;TAG t;VAL v;

v.ana = 100;fl_write(task_id, &t, 1, &v);

.

.



6

PA

K L

ibrary S

ervices

Mailbox

A mailbox is a Real-Time Database element that holds a queue of mailbox messages consisting of structures (typedef MBXMSG) and some associated message data. Since mailboxes are Real-Time Database elements, a process can read and write values to them just as with other types of database elements; that is, the following functions work when passed to a mailbox element:

• fl_read( )

• fl_write( )

• fl_forced_write( )

• fl_change_read( )

• fl_change_wait( )

When messages are present in a mailbox, the change bit for the associated Real-Time Database element is set to 1. When the mailbox is empty, the change bit for the associated Real-Time Database element is clear (value of 0).

Mailbox services provide an inter-process communication (IPC) mechanism to FactoryLink processes. The services allow one process to send a mailbox message (typedef MBXMSG), a structure that can hold arbitrary data of variable length, to another process.

Signal services also provide an IPC mechanism to FactoryLink processes. Compared with signals, mailboxes allow data passing and are more flexible; however, they are slower. Also, messages sent to a given mailbox are placed in a queue so they are read in the same order as they are sent. Signals are prioritized but not queued.

fl_read_app_mbx( ) allows messages to be read in a different order than they were sent.

The message queue associated with a mailbox contains a head and a tail. The head of the queue is the oldest message in the mailbox; the tail is the newest. Mailbox message reads occur at the head or relative to the head of the queue; writes always occur at the tail.

The mailbox services consist of the following functions.


fl_count_mbx Determines the number of messages in a mailbox, validates a mailbox, or monitors a mailbox.

fl_query_mbx Queries a mailbox for a range of queued messages.

fl_read_app_mbx Reads and dequeues a message from a mailbox.



•

•

•

•

Some tasks communicate with each other via FactoryLink mailbox messages. It is possible to configure an application so that these tasks are on different nodes, and the mailbox messages and replies are sent across the network by FL/LAN. This is transparent to the tasks, but the following conventions must be observed; otherwise, FL/LAN will not handle replies correctly.

If the task sending the mailbox message is expecting a reply, it should put the mailbox tag of where it wants the reply sent into the mm_mbx field of the mailbox message. If it does not want a reply, it should set mm_mbx.t_type and mm_mbx.t_data to 1 (0xFFFF). Otherwise, FL/LAN thinks it wants a reply and since it will never get one, FL/LAN’s internal table where it stores pending replies will fill up.

Also, if a reply is expected, the mm_sendid of the mailbox message must contain the sending task’s FactoryLink task id; otherwise, FL/LAN will not be able to write the reply to the correct instance of a user domain mailbox tag (since FL/LAN runs in the shared domain).

Calling and Return Conventions

The Calling Conventions and Exception Reporting section discusses how the Kernel reports errors.

The following calling and return conventions apply to application programs that call any of the FactoryLink Library functions:

• Most functions in the library return an item of C data type int.

• A return value of -1 invariably indicates the function failed. The reason for such a failure depends on the function and the circumstances it is called under.

The calling task must call fl_errno( ) with its task id to access the specific failure code error.

In the source code, the error numbers may be referred to by the integer value or the symbolic representation of the number. We recommend using the symbolic representation. For example, the symbolic representation of 0 is GOOD. A line of code might read as follows:

fl_write_app_mbx Writes and queues a message into a mailbox.

fl_set_owner_mbx Sets the owner of a mailbox.


fl_errno Returns the last error number generated by the calling process.




6

PA

K L

ibrary S

ervices

if (fl_proc_init(“SKEL”,”Skeleton Task”) != GOOD)

This code checks whether the return value from a request to connect to the Kernel indicates an error occurred. When the symbolic representation of GOOD is used, this code does not require any changes if, for some reason, the integer value of GOOD is later changed to a value other than 0. If the integer value is used in the code and it changes, the code must be changed and recompiled.

The symbolic representations of these error numbers are found in the header file FLIB.H.

Return Reference List

Use the following lists (excerpts from FLDEFS.H) as references for error numbers.

FactoryLink Error Codes Error Number Description

FLE_INTERNAL 1 General error code.

FLE_OUT_OF_MEMORY 2 Memory allocation error because of system exhaustion or FactoryLink allocation.

FLE_OPERATING_SYSTEM 3 Unable to map Kernel semaphores.

FLE_NO_FLINK_INIT 4 Cannot locate Real-Time Database for given {FLNAME}.

FLE_NO_PROC_INIT 5 Cannot locate Real-Time Database area for {FLDOMAIN}+{FLUSER}.

FLE_BAD_FUNCTION 6 Reserved.

FLE_BAD_ARGUMENT 7 Bad input parameter passed into function.

FLE_BAD_DATA 8 TAG structure received with an invalid offset member.

FLE_BAD_TAG 9 TAG structure received with an invalid type or offset member.

FLE_NULL_POINTER 10 Reserved.



•

•

•

•

FLE_NO_CHANGE 11 Change read/wait function call failed because no changes for given tag array.

FLE_PROC_TABLE_FULL 12 Maximum number of tasks has registered for the given {FLNAME}/{FLDOMAIN}/{FLUSER}.

FLE_BAD_PROC_NAME 13 Invalid task name received.

FLE_BAD_USER_NAME 14 Invalid user name received.

FLE_BAD_OPTION 15 Reserved.

FLE_BAD_CHECKSUM 16 Reserved.

FLE_NO_OPTIONS 17 Reserved.

FLE_NO_KEY 18 Reserved.

FLE_BAD_KEY 19 Reserved.

FLE_NO_PORT 20 Reserved.

FLE_PORT_BUSY 21 Reserved.

FLE_ALREADY_ACTIVE 22 Initializing task with same name as one currently running.

FLE_NOT_LOCKED 23 Attempted to unlock Kernel without holding a lock.

FLE_LOCK_FAILED 24 Unable to attain lock to the Kernel.

FLE_LOCK_EXPIRED 25 Attempted to release a lock that has expired on the Kernel.

FLE_WAIT_FAILED 26 Invalid task ID passed into fl_wait( ).

FLE_TERM_FLAG_SET 27 Termination flag for given task ID set to ON.




6

PA

K L

ibrary S

ervices

FLE_QSIZE_TOOBIG 28 Internal error - failed to allocate mailbox queue.

FLE_QSIZE_CHANGED 29 Internal error - inconsistent queue size.

FLE_NO_TAG_LIST 30 Reserved.

FLE_TAG_LIST_CHANGED 31 Reserved.

FLE_WAKEUP_FAILED 32 Failure occurred awakening task sleeping on the Kernel.

FLE_NO_SIGNALS 33 No signals pending for caller.

FLE_SIGNALLED 34 Task awakened by signal from another task.

FLE_NOT_MAILBOX 35 Called mailbox function with a tag not of type MAILBOX.

FLE_NO_MESSAGES 36 No mailbox messages pending for mailbox tag.

FLE_ACCESS_DENIED 37 Cannot read a mailbox message targeted for another task.

FLE_ATTR_FULL 38 Attribute name table full.

FLE_INVALID_ATTR 39 Invalid attribute name.

FLE_ATTR_NOT_DEF 40 Cannot find requested attribute.

FLE_APP_EXISTS 41 Attempted to start application with same {FLNAME} as one running.

FLE_NO_FLINK_RTDB 42 Unable to map to kernel memory area for {FLNAME}.

FLE_NO_TASK_BIT 43 Task protection bit not set for initializing task.




•

•

•

•

FLE_NOT_LITE_TASK 44 Attempted to start restricted task from running in a Lite system.

FLE_SEM_OP 45 Unable to get or release semaphose.

FLE_MBXLIM_EXCEED 46 Mailbox message space exhausted.

FLE_FLOAT_NAN 50 Float (FLP) is not-a-number.

FLE_FLOAT_POS_INF 51 Float (FLP) is positive infinity.

FLE_FLOAT_NEG_INF 52 Float (FLP) is negative infinity.


PAK LIBRARY SERVICESCT Access Services


6

PA

K L

ibrary S

ervices

CT ACCESS SERVICES

CT access functions allow client processes to access the CT archives. The term archive refers to the binary CT file containing data for more than one database table. For example, the TIMER.CT file contains information for the event timer and interval timer database tables. A typical application has a function that opens the task CTs and reads them into memory. The write CT access functions are the complement of the CT read functions. Use them to create and/or modify the CT archives.

The CT access services consist of the following functions.


ct_open Opens a CT archive file.

ct_read_index Reads an index from a CT archive.

ct_read_hdr Reads the header for ctp into buffer.

ct_read_rec Reads a record from the current CT into memory.

ct_read_recs Reads records from the current CT into memory.

ct_close Closes a CT archive.

ct_create Creates/truncates/opens a CT for update.

ct_find_index Finds an index.

ct_get_hdrlen Gets the length of the current CT table header.

ct_get_name Gets the name of the current CT table.

ct_get_ncts Determines the number of CT tables in the archive.

ct_get_nrecs Determines the number of records in the last selected CT table.

ct_get_reclen Determines the record length of records in the current CT table.

ct_get_type Gets the type field from the current CT table.

Error Codes Number Description

CT_CANNOT_OPEN_FILE 1 File is missing.

PAK LIBRARY SERVICESCT Access Services


•

•

•

•

CT_CANNOT_CLOSE_FILE 2 Program bug.

CT_FILE_NOT_OPEN 3 Program bug.

CT_SEEK_ERROR 4 Wrong file size.

CT_READ_ERROR 5 Wrong file size.

CT_WRITE_ERROR 6 Drive not ready or disk full.

CT_BAD_MAGIC 7 File corrupted.

CT_BAD_DATA 8 File corrupted.

CT_NULL_POINTER 9 Program bug.

CT_BAD_INDEX 10 CT does not exist.

CT_BAD_RECORD 11 CT record does not exist.

Error Codes Number Description

PAK LIBRARY SERVICESObject CT Access


6

PA

K L

ibrary S

ervices

OBJECT CT ACCESS

The object CT is a binary representation of a configuration database file similar to any other task-specific CT. The main difference is the CT contains the contents of the application object database, which is not tied to any one particular task. Another difference is a large application with many objects requires special handling in order to fit within a standard CT.

The object CT API written using the PAK ct_...( ) primitives hides the details of how the object database contents are coerced into a CT.

Overview of Object CT Services

The Object CT API mirrors the existing ct_...( ) API and provides the following services:

• Opening and closing of the object CT

• Object definition retrieval based on an object name

• Random access, block retrieval for object definitions

Overview of the Object CT API

Ignoring some organizational overhead, FactoryLink CTs equate to on-disk arrays of C-structures. The object CT is no different, and consists of many arrays of the following structure:

typedef struct _flobjrec

{

char tagname[MAX_TAG_NAME+1];

char tagdomain[MAX_USR_NAME+1];

char tagtype[MAX_TYPE_NAME+1];

char tagdescr[MAX_PROC_DESC+1];

char tagdimen[MAX_DIM_LENGTH+1];

u16 tagperwhen;

u16 tagchgbits;

TAG tagno;

} FLOBJREC;



•

•

•

•This structure reflects the current attributes that define a FactoryLink object. Applications should treat this structure as opaque and not access its members directly. A function-based interface, included with the Object CT API, should be used to query FLOBJREC’s values. Using the API shields the PAK task from future changes that alter the object structure and its members yet ignores the interface.

The Object CT API is a data abstracted set of functions. Its usage generally follows some variant of the following sequence:

• Open the application object table

• Search for definitions for one or more objects

• Close the object table

Code Sample: Printing All Objects in a Particular Domain

#include <objct.h>

/*

* Function print_objs4dom writes to standard output all objects

* configured for a particular domain.

*/

int print_objs4dom(char *flapp, char *tgt_dom)

{

FLOBJREC rec;

u32 nrecs;

u32 k;

CT objct;

if (ct_open_obj(&objct, flapp) != GOOD)

return ERROR

nrecs = ct_nrecs_obj(objct);

for (k = 0; k < nrecs; k++)

{

ct_read_objs(objct, &rec, k, 1);

if (strcmp(tgt_dom, flobjrec_get_domain(rec)) == 0)



6

PA

K L

ibrary S

ervices

{

printf(“Object %s in domain %s\n”,

flobjrec_get_name(rec), tgt_dom);

}

}

ct_close_obj(&objct);

return nrecs;

}

An object is a user-defined name associated with a set of attributes, such as type, dimension, and domain. This set of attributes equates to the object definition.

An application consists of many objects. Open the Configuration Manager and choose View>Object List from the Main Menu to view the objects defined within an application. The resulting list shows all objects with their definitions.

Object CT API Reference Guide


ct_find_obj Finds object definition for given object name.

ct_nrecs_obj Returns the number of object definitions held in CT.

ct_open_obj Opens object CT.

ct_read_obj Reads object definition(s) from object CT.

flobjrec_get_chgbits Extracts change bits attribute from object definition.

flobjrec_get_descr Extracts description attribute from object definition.

flobjrec_get_dimen Extracts dimension attribute from object definition.

flobjrec_get_domain Extracts domain attribute from object definition.

flobjrec_get_name Extracts the name from object definition.

flobjrec_get_perwhen Extracts persistence attribute from object definition.

flobjrec_get_tag Extracts tag attribute from object definition.

flobjrec_get_type Extracts type attribute from object definition.

PAK LIBRARY SERVICESDirect Tag Processing


•

•

•

•

DIRECT TAG PROCESSING

FactoryLink tasks are exception driven. The value of a Real-Time Database element, or tag, changes, causing the task to perform an action in response. In fact, the main processing loop of these tasks usually resembles the following pseudo code:

while (no task termination flag)

{

Wait for tag value change;

Find what action(s) are associated with the change;

Invoke the actions(s) for the tag value change;

}

The FactoryLink Kernel library services provide the low-level functionality required to awaken upon Real-Time Database value changes as well as to identify which value changed. However, determining the actions the task is to take for that change is left to the developer.

This is where the Direct Tag Processing (DTP) API enters the picture. The FLDTP API wraps itself around the Kernel services and presents a higher level interface to the developer. With DTP, the developer associates an action directly with the tag. In other words, whenever the value of a tag changes, its associated action is invoked. Therefore, the value-add for DTP is the developer spends more time on writing the processing than on routing value changes to the processing.

The FLDTP API features are:

• Associating one or more actions directly with a tag change.

• Dynamic addition/removal of actions through the task run-time.

• Blocking/non-blocking processing of tag value changes.

• Priority-based processing of tag value changes.

Direct Tag Library Services

The DTP has a fairly standard life-cycle. It is created. It is loaded with tags and actions. These tags and actions are then processed. As the program continues, existing tags/actions are removed and/or new ones are added. Finally, the task terminates, destroying the DTP during its exit.

This section categorizes the interfaces exposed by the FLDTP API. It should also help you envision how to make it work for your task. All of the code samples have been taken from the PAK Skeleton task.



6

PA

K L

ibrary S

ervices

Instantiating the DTP

In general terms, the DTP is a container of actions bound to tags with the normal overhead of construction, attribution, and destruction functionality.

The DTP Data Structures

The main structure is fldtp. This structure is the tag manager and most work with the FLDTP API requires a handle to one of its instances.

The next most visible structure is the fldtp_action( ) or action record. The action record represents one process to invoke on behalf of a tag.

Finally, the fldtp_tag( ) structure represents a tag inserted into the DTP. Several actions can be chained off the same tag. Users normally do not directly operate upon this structure.

External C-Structures Description

fldtp Trigger manager.

fldtp_action Action/tag binding record.

fldtp_tag Tag inserted into DTP.



•

•

•

•The DPT Instance

To use DTP, an instance of it must be created. Depending on the complexity of the program, there may be several DTP instances.

An fldtp instance equates to a tag process manager. Through it, tag processing actions are added, invoked, and removed. It serves as a container for all the events that the task needs to respond to.


fldtp_create Creates a DTP instance.

fldtp_destroy Destroys a DTP instance.

fldtp_get_comparef Get DTP comparison function pointer.

fldtp_get_msglen Get DTP message tag read buffer size.

fldtp_get_tagcnt Get DTP tag count.

fldtp_set_comparef Set DTP ID comparison function pointer.

fldtp_set_msglen Set DTP message tag read buffer size.

fldtp_set_proc_by Set DTP message tag read buffer size.



6

PA

K L

ibrary S

ervices

Code Sample: Creating and Destroying a DTP Instance

#include <flib.h>

#include <fldtp.h>

id_t Task_id = -1;

FLDTP *TrigMgr = NULL;

int main(int argc, char *argv[])

{

....

. Attach to the Kernel

....

/* Create the trigger manager */

if (fldtp_create(&TrigMgr) != FLDTP_E_GOOD)shutdown(1);

....

. Continue task initialization…

....

}

void shutdown(int error)

{

fldtp_destroy(TrigMgr); /* release all trigger info */

fl_proc_exit(Task_id); /* terminate FL access */

exit(error); /* exit to OS */

}



•

•

•

•The DTP Action Record

An action record (the fldtp_action( ) structure) contains all the information required to process its associated tag. The user does not directly create these records. Instead, an action record is created on behalf of the user whenever a tag action is inserted into the DTP.

Many attributes can be attached to the action record once its handle has been returned to the user.

Loading Actions into the DTP

Once the DTP is created, tags, along with their actions, need to be loaded into it. In terms of code, this means calling the function dtp_insert( ) with the appropriate parameters: the handle to the DTP instance to insert the action into, the tag the action is to be bound to, and the action to be invoked. The term action means the pointer to the process function to invoke with the tag value.

A successful insert into the DTP returns the handle to the action record that embodies the inserted information. With this handle, additional attributes can be attached. Of these attributes, the user data arguments are the most important. User data arguments are an array of


fldtp_action_get_args Get associated user-defined arguments.

fldtp_action_get_destroyf Get associated destruction notification function pointer.

fldtp_action_get_id Get associated ID.

fldtp_action_get_priority Get associated priority.

fldtp_action_set_args Set associated user-defined arguments.

fldtp_action_set_destroyf Set associated destruction notification function pointer.

fldtp_action_set_id Set associated ID.

fldtp_action_set_priority Set associated priority.


fldtp_insert Insert tag/action into DTP.



6

PA

K L

ibrary S

ervices

pointers to information related to the tag action. When processing tag actions, these pointers are passed to the process function along with the tag value.

To illustrate, consider the following code sample. Here, a trigger is being inserted into the DTP. Once inserted, the related CT information is attached to the action record representing this trigger event. Later, when DTP invokes action, function proc_trig( ) is called and the CT information will be passed to it. Also, a destruction notification function free_triginfo( ) is being attached to the action record. This allows the task to release the memory held by CT information when the action record is later destroyed. This attachment would not be necessary if the memory allocated for the CT information was managed elsewhere.

Code Sample: Inserting into the DTP.

{

FLDTP_ACTION *ap;

TRIGINFO *tip;

....

. Read a CT header and all its records. Allocate and store at ‘tip’.

....

r1 = fldtp_insert(TrigMgr, &hdr_buf.trigger, proc_trig, &ap);

r2 = fldtp_action_set_args(ap, 1, (void**) &tip);

r3 = fldtp_action_set_destroyf(ap, free_triginfo);

if (r1 != FLDTP_E_GOOD || r2 != FLDTP_E_GOOD || r3 != FLDTP_E_GOOD)

{

status("TRIGMGR", FLS_INACTIVE);

shutdown(1);

}

....

. Read the next header from the CT…

....

}



•

•

•

•Processing Actions with the DTP

Once the DTP is loaded with the tags and their actions, the next step is to process them. Each of the process functions in the preceding table offer a unique scope of processing. The most commonly used is fldtp_proc_wait( ) where the task sleeps until one or tags within the DTP change. At that time, the actions tied to the changed tags are invoked and control is returned to the caller. The other process functions either restrict processing to a particular subset of DTP entries or tune its blocking/non-blocking behavior. The following scrap depicts the normal process of a FactoryLink task using DTP:

Code Sample: Processing with the DTP.

while ( fl_test_term_flag(Task_id) == OFF )

fldtp_proc_wait(TrigMgr, Task_id);

Since the DTP invokes the action functions directly, the only work to perform outside of the process function is to check the task termination flag.

As for the work to perform from within the process function, note the following code sample that depicts a simple process function. Whenever a tag associated with process function proc_trig( ) changes, function fldtp_proc_wait( ) invokes that function with the following arguments: the tag, its value, and the associated user-defined arguments.

Code Sample: A DTP Process Function.

void proc_trig(TAG *tag, VAL *val, short f_argc, void *f_argv[])

{


fldtp_proc Process all actions loaded into DTP.

fldtp_proc_action Process an individual action immediately.

fldtp_proc_change Process all actions tied to changed tags.

fldtp_proc_tag Process all actions tied to an individual tag.

fldtp_proc_wait Process all actions tied to changed tags. If none, wait.

fldtp_wait Wait for any tag in DTP to change.



6

PA

K L

ibrary S

ervices

TRIGINFO *tip;

char msgbuf[80];

if (val->dig == 0) /* Ignore ’zero’ triggers */return;

tip = (TRIGINFO*) f_argv[0];

....

. Process the trigger...

....

}

The above code sample takes the tag value from the digital member of the VAL union. This is because the Skeleton task restricts its triggers to type DIGITAL. For more information on VAL union, see “fl_read” in Chapter 7 in the API Library.

Removing Actions From the DTP

Most tasks initialize the DTP with a set of tags and their actions and never adjust them again for the life of the task. These tasks do not need to use DTP’s removal function. More sophisticated tasks, however, may very well need to dynamically alter their processing lists over the task lifetime.

When a particular action is no longer required, it should be removed from the DTP so the task need not wake-up unnecessarily. There are two ways to accomplish this. First, function fldtp_remove( ) accepts the handle the particular action record to remove. While very surgical and quick, the downside to this is the developer must keep track of all action records held within the DTP.

The second way is to use function fldtp_remove_group( ). Here, the caller specifies a criteria used to remove records from the DTP. This criteria is any combination of action function pointer, user-defined ID, or tag binding. This allows the caller to remove particular records without necessarily recording the individual handles to each and every DTP insertion the task has ever made.


fldtp_remove Remove tag/action into DTP.

fldtp_remove_group Remove actions from DTP based on a criteria.



•

•

•

•The FLDTP API Exit Codes

Functions of the FLDTP API always return one of the following exit codes.

Error Code Value Description

FLDTP_E_ GOOD 0 No error occurred.

FLDTP_E_INTERNAL -1 General failure indicator.

FLDTP_E_ INVARG -2 Invalid argument passed to function.

FLDTP_E_INVTAG -3 Invalid tag passed into function.

FLDTP_E_NOMEM -4 Memory allocation failure.

FLDTP_E_NOTFND -5 Cannot find requested object.

FLDTP_E_ILLPROC -6 Illegal call to procedure at given time. Some DTP functions are not re-entrant.

FLDTP_E_ KERFAIL -7 Kernel function call failed. Call fl_errno( ) for details.

FLDTP_E_INKTYPE -8 Tag of unknown type passed into function.

FLDTP_E_NOCHANGE -9 No tag changes are pending.

PAK LIBRARY SERVICESNormalized Tag Reference Services


6

PA

K L

ibrary S

ervices

NORMALIZED TAG REFERENCE SERVICES

A FactoryLink object is a named instantiation of a data type of digital, analog, float, long analog, message, or mailbox. The object may be a single instance of its data type or it may be an array containing multiple instances of the same data type. The name of a FactoryLink object is referred to as the object name.

A FactoryLink object may be a member of another object to connote a structured view. A member FactoryLink object has equal standing with its parent object, save that it cannot have members of its own. A member tag can be arrayed, but these usually parallel the dimensions of its parent object.

Finally, FactoryLink object may have a local or remote value source. This source is known as its node. This node is sometimes referred to as an external domain.

A tag refers to a single location within the FactoryLink Real-Time Database. A FactoryLink object equates to one or more tags, depending on whether it is an arrayed object and/or whether it has member objects associated with it.

Given these parameters, a reference to a FactoryLink object conforms to the following syntax:

[{node}:]{name}[[dimensions]][.member]

where:

node (optional) The source node for the given tag

name The base name for the tag

dimension (optional) The particular tag element for an arrayed tag

member (optional) The sub-component identifier for the base tag

For example, the object reference plc1:tagx[4][5].raw has a node of plc1, a name of tagx, the dimensions of [4][5], and a member of raw.

This syntax provides the precision required to resolve an object reference to a single, Real-Time Database location (or tag).

Also given this syntax, the combination of a reference node, name, and member equates to the name of the object, as seen through FLCM object list panel. Please keep in mind the object name component may not be sufficient to uniquely identify a tag. It must be accompanied by its associated source, dimension, or member attributes.



•

•

•

•Overview of FLNTAG Services

The syntax for a tag reference becomes complex when associated attributes are prefixed and/or appended onto it. Even a simple reference, such as x[5], requires a significant amount of parsing and interpretation.

The FLNTAG API consolidates this processing into a single interface. References can be decomposed into their base components, have these components modified individually, and ultimately recombined into a reference string. The API also provides hooks for obtaining object definitions and RTDB locations.

The services provided by the FLNTAG API are

• Creation and destruction of an FLNTAG instance

• Decomposition of a tag reference string into a FLNTAG

• Object definition and RTDB location retrieval based on the FLNTAG

• Component level manipulation of a FLNTAG

• Generation of a string (reference, object name, …) from a FLNTAG

Overview of the FLNTAG API

The FLNTAG API is a data-abstracted set of functions. Its operation generally follows some variant of the following sequence:

1. Open the application object table (table containing all known objects)

2. Create an FLNTAG instance

3. Load a tag reference string into the FLNTAG

4. Obtain the RTDB location for the reference, using the FLNTAG API

5. Destroy the FLNTAG instance

6. Close the object table

Therefore, the reference location within the RTDB can be determined in a hands-off manner. Additionally, should the syntax for a reference change, code based on the API need not change to support it.



6

PA

K L

ibrary S

ervices

Code Sample: Converting a Tag Reference to a TAG

#include <flntag.h>

/*

* Function convert_ref2tag() returns the RTDB location for the

* given reference.

*/

int convert_ref2tag(char *flapp, char *tagref, TAG *tag)

{

FLNTAG *ntag;

CT objct;

int rv;

if (ct_open_obj(&objct, flapp) != GOOD)

return ERROR

if ((ntag = flntag_create()) != NULL)

{

if ((rv = flntag_parse_ref(ntag, tagref)) == FLNTAG_E_GOOD)

rv = flntag_find_tag(ntag, &objct, tag);

rv = (rv == FLNTAG_E_GOOD) ? GOOD : ERROR;

flntag_destroy(ntag);

}

else

{

rv = ERROR;

}

ct_close_obj(&objct);

return rv;

}



•

•

•

•FLNTAG Return Codes

The following table lists the return codes defined in FLNTAG.H with their meanings.

Return Code Number Description

FLNTAG_E_GOOD 0 Function successful.

FLNTAG_E_GENERAL -1 Internal error.

FLNTAG_E_HANDLE -2 Invalid FLNTAG structure handle.

FLNTAG_E_INVARG -3 Invalid argument passed to function.

FLNTAG_E_NOMEM -4 Memory allocation failure.

FLNTAG_E_REFSYN -5 Illegal syntax for tag reference.

FLNTAG_E_INVCHR -6 Invalid character found in given tag reference.

FLNTAG_E_LENGTH -7 Invalid string length.

FLNTAG_E_DIMSYN -8 Invalid dimension syntax.

FLNTAG_E_DIMLEN -9 Invalid dimension string length.

FLNTAG_E_DIMNUM -10 Invalid number of dimensions.

FLNTAG_E_DIMRNG -11 Number of elements for single dimension too large.

FLNTAG_E_MBRREF -12 Member tag reference passed when expecting only a structured tag reference.

PAK LIBRARY SERVICESPath Manipulation


6

PA

K L

ibrary S

ervices

FLNTAG Function Listing

PATH MANIPULATION


flntag_calc_base Calculates base tag address from arrayed tag.

flntag_calc_tag Calculates arrayed tag address from base tag.

flntag_create Creates FLNTAG instance.

flntag_destroy Destroys FLNTAG instance.

flntag_find_def Returns tag definition for given FLNTAG structure.

flntag_find_tag Returns tag definition for given TAG structure.

flntag_gen_objname Generates object name string.

flntag_gen_ref Generates tag reference string.

flntag_gen_str Generates string from selected portions of given FLNTAG.

flntag_get_dimen Returns dimension component of given FLNTAG.

flntag_get_member Returns member component of given FLNTAG.

flntag_get_name Returns name component of given FLNTAG.

flntag_get_node Returns node component of given FLNTAG.

flntag_parse_brkt4dims Parses dimensions from bracketed string representation.

flntag_parse_comma4dims Parses dimensions from comma string representations.

flntag_parse_ref Loads a given tag reference string into an FLNTAG.

flntag_set_dimen Sets dimension component of given FLNTAG.

flntag_set_member Sets member component of given FLNTAG.

flntag_set_name Sets name component of given FLNTAG.

flntag_set_node Sets node component of given FLNTAG.



•

•

•

•The functions beginning with the name fl_path( ) are all concerned with allowing developers to write portable code with generic path name structures that can be automatically converted to be system-specific.

The normalized path functions eliminate system-specific path name dependencies and allow porting of code to different platforms without changes. FactoryLink multi-platform code should use only these functions to generate path names, open file information, and search directories.

It is essential you call the fl_path( ) functions instead of attempting to hard-code or build path names using string functions into the programs if you plan on porting the applications to other systems and on retaining compatibility with future releases of FactoryLink.

Path Name Building and Representation

Paths are represented as either a system-dependent character string or as a data structure containing the parts of the path as individual strings. The data structure form is called a normalized path name.

A normalized path contains the following components:

• Node name

• Device

• Directory

• File name

• Wild card pattern

• File date and time

• File size

• File type

• System-dependent information

This information is stored in the NPATH C-structure. The NPATH structure should be considered opaque and its members should not be accessed directly. The fl_path( ) API provides functions to extract member values.

Path Name Format

The complete path name for a file follows the format:

DISK:/DIRECTORY/SUBDIRECTORY/FILENAME

Partial path name for a file follows the format:



6

PA

K L

ibrary S

ervices

/DIRECTORY/SUBDIRECTORY/FILENAME

Path Name Format for Windows NT and Windows 95

The platform-independent path name format of

DISK:/DIRECTORY/SUBDIRECTORY/FILENAME

translates to

DRIVE:\DIRECTORY\SUBDIRECTORY\FILENAME

If a file named TIMER.CT is located in a subdirectory named CT in the {FLAPP} directory, the file name in this manual is specified as {FLAPP}/CT/TIMER.CT. The file name has the format {FLAPP}\CT\TIMER.CT. The boldfaced type on {FLAPP} indicates this refers to the default or operator-specified name of the application-related directory specified during installation.

fl_path( ) functions under Microsoft Windows NT, Windows 95 normalize paths as follows:

• If a DOS-style path string is supplied to fl_path_norm( ), FactoryLink assumes any name following the last slash character is a file name.

• If a path refers to a directory, add a trailing slash to the path name in order for fl_path_norm( ) to normalize the path as a directory.

• If the path refers to a directory and adding a trailing slash is a problem, use the fl_path_set_dir( ) function to normalize the path.

Use of Environment Variables in Path Names

The fl_path( ) API functions allow specification of environment variables in a multi-platform path. An environment variable is indicated by placing the environment variable name inside braces {}. For example, assuming that {FLAPP} is set to /users/myflapp and {FLDOMAIN} is set to SHARED, the multi-platform path myflapp/ct is expanded to /users/{FLINK}/{FLAPP}/shared/ct. This macro expansion takes place automatically whenever braces are used around the name of a valid environment variable within a path name. The following API functions recognize and expand environment variables:

• fl_path_norm

• fl_path_add_dir

• fl_path_set_dir

• fl_path_set_file

• fl_path_set_pattern

• fl_path_set_node



•

•

•

•• fl_path_set_device

Allocating/Destroying a Normalized Path

NPATH *fl_path_alloc(void)

void fl_path_free(NPATH *p)

The function fl_path_alloc( ) allocates and returns a pointer to a normalized path buffer. This function should be called rather than allocating the NPATH structure directly so you can add a buffer for system-dependent information to the path buffer.

The function fl_path_free( ) releases the space allocated by a call to fl_path_alloc( ). The NPATH structure should not be accessed after fl_path_free( ) is called. This leads to unpredictable behavior of the system.

Converting To/From a Normalized Path

char *fl_path_sys(NPATH *p, char *path, size_t length)

NPATH *fl_path_norm(NPATH *p, char *path)

NPATH *fl_path_set_dir(NPATH *p, char *dir)

NPATH *fl_path_cwd(NPATH *p)

The function fl_path_sys( ) converts a normalized path into a system specific path string. If the path argument is null, fl_path_sys( ) calls malloc( ) to allocate memory for the resulting path. Release the memory when it is no longer in use.

fl_path_norm( ) converts a system-specific path string into a normalized path. Alternatively, the fl_path_set_dir( ) function is used if the path refers to a directory.

fl_path_set_dir( ) replaces the directory portion of the path and the directory argument is converted to normalized form. If the NPATH argument is NULL, fl_path_set_dir( ) first calls fl_path_alloc( ) to allocate a NPATH buffer. The file name, extension and version are not modified by the fl_path_ser_dir( ) function.

fl_path_cwd( ) builds a normalized path for the current working directory. If the NPATH argument is NULL, fl_path_cwd( ) first calls fl_path_alloc( ) to allocate a NPATH buffer.

Modifying an Existing Path

void fl_path_add(NPATH *p1, NPATH *p2)void fl_path_add_dir(NPATH *p, char *dir)void fl_path_set_file(NPATH *p, char *file)



6

PA

K L

ibrary S

ervices

void fl_path_set_pattern(NPATH *p, char *pattern)void fl_path_set_node(NPATH *p, char *node)void fl_path_set_device(NPATH *p, char *drive)void fl_path_set_extension(NPATH *p, char *extension)void fl_path_set_version(NPATH *p, char *version)

fl_path_add( ) catenates two paths. Any missing component of the second path, p2, is taken from the first path, p1, or from the current directory if the first path is null.

fl_path_add_dir( ) adds a subdirectory specification to the end of the directory portion of a path. Only one subdirectory can be added to a path during each call to fl_path_add_dir( ). The subdirectory name should not contain any path-separator characters.

fl_path_set_file( ) replaces the file name portion of the path.

fl_path_set_pattern( ) sets the wild card pattern for subsequent directory search.

fl_path_set_node( ) replaces the node name portion of the path.

fl_path_set_device( ) replaces the drive portion of the path.

fl_path_set_extension( ) replaces the extension of the current file name portion of the path.

Creating/Deleting Directories and Files

int fl_path_mkdir(NPATH *p)int fl_path_rmdir(NPATH *p)int fl_path_create(NPATH *p)int fl_path_remove(NPATH *p)

fl_path_mkdir( ) creates the directory given by the directory portion of the path.

fl_path_rmdir( ) deletes the directory given by the directory portion of the path.

fl_path_create( ) creates an empty file using the complete path.

fl_path_remove( ) removes the file specified by the complete path.

Searching for Matching Files

int fl_path_opendir(NPATH *p)int fl_path_readdir(NPATH *p)void fl_path_closedir(NPATH *p)



•

•

•

•fl_path_opendir( ) begins a directory search operation. The current directory information in NPATH is used as the directory to search and the current wildcard pattern is used to choose files. fl_path_opendir( ) returns GOOD if the directory opens for search or ERROR if it does not. fl_path_opendir( ) reads the first entry in the directory.

fl_path_readdir( ) reads the next matching file in the directory and places the name of the file into the file name component of the path. The file type, date, time, and size are also stored in the NPATH structure. fl_path_readdir( ) returns GOOD if a matching file is found or ERROR if not.

fl_path_closedir( ) ends a directory search. The following code fragment in C demonstrates how to use directory search functions to print a directory listing.

NPATH *p;char date[80];char time[80];

char fullpath[MAX_PATH_NAME];

p = fl_path_norm(NULL, “*.*”);if (fl_path_opendir(p) == ERROR){printf(“Directory Not found\n”);return;

}

do{

fl_path_date(p, date,80);fl_path_time(p, time,80);fl_path_sys(p, fullpath,MAX_PATH_NAME);

printf(“%s %s %s\n”, date, time, fullpath);} while ( fl_path_readdir(p) != ERROR );fl_path_closedir(p);fl_path_free(p);

Getting File Information

int fl_path_info(NPATH *p)long fl_path_date(NPATH *p, char *buf,size_t length)long fl_path_time(NPATH *p, char *buf,size_t length)int fl_path_access(NPATH *p)char *fl_path_get_device(NPATH *p)char *fl_path_get_node(NPATH *p)char *fl_path_get_dir(NPATH *p)char *fl_path_get_file(NPATH *p)long fl_path_get_dt(NPATH *p)



6

PA

K L

ibrary S

ervices

long fl_path_get_size(NPATH *p)int fl_path_get_type(NPATH *p)

fl_path_info( ) initializes the date, time, size, and type for the path. If the file does not exist, fl_path_date( ) formats the date of a file into the caller’s buffer and returns the date and time (concatenated) as a long integer.

fl_path_time( ) formats the time of the file into the caller’s buffer. This function is operating system-dependent.

Under Windows NT and Windows 95, the format is controlled by the country code returned by the MS-DOS function 38h.

PAK LIBRARY SERVICESMessage Translation Services


•

•

•

•

MESSAGE TRANSLATION SERVICES

The message translation functions provide services so run-time tasks can translate keywords into localized messages stored in external disk files (message files).

The message translation services consist of the following functions.

Overview of Message Translation Functions

Keyword/translation pairs are kept in a tree data structure. The translation for a keyword is retrieved using the fl_xlate( ) function. This tree is automatically loaded with a set of default translations for tasks. The translations may be overridden or supplemented by loading another translation file into the current tree. Each task may maintain several translation trees.

Use the fl_xlate( ) functions for output from all messages to create a language-independent task.

If file names or other data need to be imbedded in a message, use fl_xlate( ) to retrieve the format string and then sprintf ( ) using that format, as in the following example:

Example 1

The file test.txt contains:

BADFILE“Could not open the file: %s”

Functions Descriptions

fl_xlate Translates keyword to its associated message.

fl_xlate_init Loads the first message file. The message translation data structure is a tree.

fl_xlate_load Loads the specified file into the current translation tree, replacing any duplicate keywords. The function returns the number of entries loaded from this file or returns ERROR.

fl_xlate_get_tree Returns the address of the current translation tree or NULL if no translation files have been loaded.

fl_xlate_set_tree Sets the current translation tree to the tree at the specified address.



6

PA

K L

ibrary S

ervices

The file test.c contains:

char buff[MAX_MSG_SIZE] ;sprintf(buff, fl_xlate(BADFILE), filename);

Loading Translation Files

int fl_xlate_init(char FAR *file, char FAR *buff, uint len)int fl_xlate_load(char FAR *file)

When loading translation files, the file fllang.lst in \flink\install is examined to determine the current language. It is appended to the {FLINK}/MSG path used to load the master file as well as user-defined files.

If the user-specified file contains path information, it is folded into the {FLINK}/MSG/<lang> path when loading the file.

The function fl_xlate_init( ) starts a fresh translation tree and loads the default translation file master.txt. The user-specified translation file is then loaded on top of the existing definitions. Duplicate definitions are superseded by the last file loaded. The function returns the total number of translations loaded from both the master.txt file as well as the user-specified file or returns ERROR.

The function does not use the buff and len parameters of fl_xlate_init( ) but are retained to stay compatible with existing code.

The function fl_xlate_load( ) loads the specified file into the current translation tree, replacing any duplicate keys. The function returns the number of entries loaded from this file or returns ERROR.

Example 2

If the current language variable is defined to be DE for German, the following call:

fl_xlate_init(“iml”, NULL, 0)

loads {FLINK}/MSG/DE/master.txt into the tree and then loads {flink}/msg/de/iml.txt into the tree. The return value is the total number of translations loaded from both files (duplicates are counted only once).

The call

fl_xlate_load(“iml”)

loads {FLINK}/MSG/DE/iml.txt into the tree and returns the number of translations.



•

•

•

•The call

fl_xlate_load(/temp/test)

still loads /temp/test.txt into the tree and returns the number of translations.

Translating

char FAR *fl_xlate(char FAR *key)

The function fl_xlate( ) returns a pointer to the translation text for the requested key if the key is found in the tree. The pointer to the original key is returned if no translation is found.

Managing Multiple Translation Trees

void FAR *fl_xlate_get_tree( void )

void FAR *fl_xlate_set_tree( void *p )

The function fl_xlate_get_tree( ) returns the address of the current translation tree or NULL if no translation files are loaded.

The function fl_xlate_set_tree( ) sets the current translation tree to the specified address. Future file loads and translations are facilitated using this tree.

Example 3

void *tree1, *tree2 ; /* pointers to 2 trees */

fl_xlate_load(“file1") ;tree1 = fl_xlate_get_tree() ;

fl_xlate_load(“file2") ;tree2 = fl_xlate_get_tree() ;

fl_xlate_set_tree(tree1) ;printf(“%s\n”, fl_xlate(“token”)) ;

fl_xlate_set_tree(tree2) ;printf(“%s\n”, fl_xlate(“token”)) ;

fl_xlate_set_tree( ) may also be used to start a fresh tree, as in the following example:

Example 4

fl_xlate_set_tree(NULL) ; /* start new tree */



6

PA

K L

ibrary S

ervices

Extended Characters

Because FactoryLink is translated into several languages, it is important to know that extended characters present in foreign languages are interpreted by the various programs you use to edit files.

All translated text returns with the characters in the Windows codepage 1252. It is important that the translated files in the FactoryLink ECS baseline, like multilanguage TXT files (*.mlt), remain in this representation so you can convert from 1252 to other codepages for other platforms. For this reason, any edits to these files must be performed on a Windows or VMS platform.

When it is necessary to edit a file that contains text in a foreign language, make sure to preserve the 1252 representation. Most Windows-based products should be able to handle the 1252 codepage correctly, for example, Microsoft Word, Microsoft Write, Notepad, and Codewright. You may want to choose one of these editors as your best choice for editing text files with foreign language data. If you cannot see all the characters clearly, it may be necessary to select another font.



•

•

•

•

7

PA

K A

PI R

eference

Lib

rary



PAK API Reference Library

The FactoryLink Library offers a set of services that supports the creation of FactoryLink tasks, such as functions to read and write data contained in the real-time database. Where possible, the API is consistent across operating systems and platforms. This permits programs written in ANSI C to be compiled without source modification on any of the FactoryLink platforms. You can upgrade the hardware platform by physically porting the application over to a different platform and recompiling it.

This chapter provides the following information about each API function:

• Syntax: Valid format for this function

• Arguments: List containing the following information about each argument:

• Type

• Name

• Direction (input = in; output = out; or both = in/out)

• Description

• Returns: Description of the returned data from the function, usually a symbolic representation representing the integer value returned by the function, such as ERROR or GOOD.

• Remarks: Additional information about the function, such as code fragments in the C language.

• See also: Lists related function(s).

PAK API REFERENCE LIBRARY


•

•

•

•

CT_CLOSE

Close a CT archive.

Syntax #include <flib.h>

int ct_close(CT* ctp);

Returns GOOD

CT_NULL_POINTER

CT_FILE_NOT_OPEN

CT_CANNOT_CLOSE_FILE

See also “ct_open”

CT_CLOSE_OBJ

Object CT API.

Syntax #include <objct.h>

int ct_close_obj(CT* objct);

Returns CT_NULL_PTR

CT_FILE_NOT_OPEN

CT_CANNOT_CLOSE_FILE

Remarks Function ct_close_obj( ) closes the object CT. The CT handle should not be referenced after being closed.

See also “ct_open_obj”

Arguments CT* ctp in CT file buffer.

Arguments CT* ctp in Object CT handle.



7

PA

K A

PI R

eference

Lib

rary

CT_FIND_INDEX

Find an index.


int ct_find_index(CT* ctp, char* ndx);

Returns GOOD

CT_NULL_POINTER

CT_FILE_NOT_OPEN

CT_SEEK_ERROR

CT_READ_ERROR

CT_BAD_DATA

CT_BAD_INDEX

Remarks Find an index by matching the name field.

CT_FIND_OBJ

Object CT API.


int ct_find_obj(CT* objct, char* objname, FLOBJREC* rec;


char* ndx in Name field.

Arguments CT* objct in Object CT handle.

char* objname in Name of object to find.

FLOBJREC* rec out Buffer for object definition.



•

•

•

•Returns GOOD

ERROR

Remarks Function ct_find_obj( ) searches the given object CT for the given objname and returns its definition.

Function ct_find_obj( ) employs a binary search.


CT_GET_HDRLEN Get the length of the current CT table header.

Syntax include <flib.h>

int ct_get_hdrlen(CT* ctp);

Returns Length of the header. The return value is undefined if the CT archive is not opened.

Remarks Determine the length of the table header of the currently selected CT table.

See also “ct_read_hdr”

CT_GET_NAME

Get the name of the current CT table.


char *ct_get_name(CT* ctp);

Returns Table name. The return value is undefined if the CT archive is not opened.

Remarks Returns a pointer to the name field of the currently selected CT table. Do not modify the memory pointed to by the return value.

CT_GET_NCTS

Determine the number of CT tables in the archive.

Arguments CT* ctp in Ct file buffer.




7

PA

K A

PI R

eference

Lib

rary


int ct_get_ncts(CT* ctp);

Returns Number of CT tables. The return value is undefined if the CT archive is not opened.

CT_GET_NRECS

Determine the number of records in the last selected CT table.


int ct_get_nrecs(CT* ctp);

Returns Number of records. The return value is undefined if the CT archive is not opened.

CT_GET_RECLEN

Determine the record length of records in current CT table.


int ct_get_reclen(CT* ctp);

Returns Length of individual records. The return value is undefined if the CT archive is not opened.

Remarks All tables have fixed-length records.

CT_GET_TYPE

Get the type field from the current CT table.







•

•

•

•int ct_get_type(CT* ctp);

Returns Table type number. The return value is undefined if the CT archive is not opened.

CT_NRECS_OBJ

Object CT API.


int ct_nrecs_obj(CT* objct, u32* nrecs);

Returns GOOD

ERROR

Remarks Function ct_nrecs_obj( ) returns the total number of objects contained within the given object CT.


“ct_read_objs”

CT_OPEN

Open a CT archive file.


int ct_open (CT* ctp, char* dirp, char* namep);

Returns GOOD

CT_NULL_POINTER



u32* nrecs out Number of objects in given CT.

Arguments CT* ctp in/out CT file buffer.

char* dirp in Base path name.

char* namep in CT file name.



7

PA

K A

PI R

eference

Lib

rary

CT_CANNOT_OPEN_FILE

CT_READ_ERROR

CT_BAD_MAGIC

Remarks ct_open( ) places information about the CT archive into the buffer ctp points to. The archive is positioned at the first table in the archive.

CT_OPEN_OBJ

Object CT API.


int ct_open_obj(CT* objct, char* flapp);

Returns GOOD

CT_NULL_PTR

CT_CANNOT_OPEN_FILE

CT_READ_ERROR

CT_BAD_MAGIC

Description Function ct_open_obj( ) opens the object CT. This CT handle is passed to all subsequent object CT API calls.

See also “ct_close_obj”

CT_READ_HDR

Read the header for ctp into buffer.


int ct_read_hdr(CT* ctp, void* hdrp);

Arguments CT* objct in/out Object CT handle.

char* flapp in Application directory.


void* hdrp in CT header buffer.



•

•

•

•Returns GOOD

CT_NULL_POINTER

CT_FILE_NOT_OPEN

CT_BAD_INDEX

CT_SEEK_ERROR

CT_READ_ERROR

Remarks Call ct_read_index( ) before calling ct_read_hdr( ).

CT_READ_INDEX

Read and index from a CT archive.


int ct_read_index (CT* ctp, uint ndx);

Returns GOOD

CT_NULL_POINTER

CT_FILE_NOT_OPEN

CT_BAD_INDEX

CT_SEEK_ERROR

CT_READ_ERROR

Remarks Each table in the archive has an associated index containing information about the table. The index is read into the CT file buffer ctp points to. Reading an index selects a specific CT for reading.

CT_READ_OBJS

Object CT API.



uint ndx in Index to read.



7

PA

K A

PI R

eference

Lib

rary

int ct_read_objs(CT *objct, FLOBJREC* recs, u32 srec, u32 nrecs);

Returns GOOD

ERROR

Remarks Function ct_read_obsj( ) reads the given number of definitions (nrecs) into target buffer recs, beginning at record srec.


“ct_nrecs_obj”

CT_READ_REC

Read a record from the current CT into memory.


int ct_read_rec(CT* ctp, void recp, uint rec);

Returns GOOD

CT_NULL_POINTER

CT_FILE_NOT_OPEN

CT_BAD_INDEX

CT_BAD_RECORD

CT_SEEK_ERROR

CT_READ_ERROR


FLOBJREC* recs out Buffer for object definitions.

u32 srecs in Starting record number.

u32* nrecs out Number of records to read.


void recp out Record buffer.

uint rec in Record number.



•

•

•

•Remarks Read the indicated record from the currently selected CT into the memory pointed to

by the buffer.

CT_READ_RECS

Read records from the current CT into memory.


int ct_read_recs(CT* ctp, void* recp, uint rec, uint recs);

Returns GOOD

CT_NULL_POINTER

CT_FILE_NOT_OPEN

CT_BAD_INDEX

CT_BAD_RECORD

CT_SEEK_ERROR

CT_READ_ERROR

Remarks Read the indicated records from the currently selected CT into the memory pointed to by the buffer. Reading begins at record number rec.

FL_CHANGE_READ

Read the first real-time database element that has changed since it was last read.


int fl_change_read(id_t id, TAG* tp, uint n, uint* ip, void* vp);


void* recp out Record buffer.

uint rec in Starting record number.

uint recs in Number of record to read.

Arguments id_t id in Caller’s FactoryLink ID.

TAG* tp in Pointer to tag array specifying which elements to examine.



7

PA

K A

PI R

eference

Lib

raryReturns GOOD

ERROR: if error, call the fl_errno( ) function with the caller’s FactoryLink ID and it returns one of the following errors:

FLE_NULL_POINTER

FLE_BAD_ARGUMENT

FLE_NO_CHANGE

FLE_LOCK_FAILED

FLE_BAD_TAG

Remarks Test for a change in value of one or more elements in the real-time database. The calling process is immediately informed (it is never blocked) as to whether any of the specified real-time database elements changed since last read. ip specifies the first element to examine; however, in contrast to fl_change_wait( ), ip does not wrap around the tag array.

In the case of a message element, be sure the m_ptr and m_mbx members of value area vp are initialized.

In the case of a mailbox element, the value passed back is the MBXMSG for the head message without the associated message data.

FL_CHANGE_WAIT

Read the first real-time database element that has changed since it was last read; if no change, go to sleep until a change occurs.


int fl_change_wait (id_t id, TAG* tp, uint n, uint* ip, void* vp);

uint n in Number of elements involved.

uint* ip out Pointer to index into tag array to be used and updated, if necessary, by the kernel.

void* vp out Pointer to area to receive value of the first changed element, if r==GOOD.




•

•

•

•

Returns GOOD


FLE_NULL_POINTER

FLE_BAD_ARGUMENT

FLE_NO_CHANGE

Remarks Wait on a change in value of one or more elements in the real-time database. If any of these elements has changed, control is returned immediately to the caller as in fl_change_read( ). Otherwise, the calling process is put to sleep (blocked) until one or more of the specified real-time database elements changes. At this point, it is awakened. While sleeping the calling task is also awakened if another process wakes it up. This can be done either directly via fl_wakeup( ) or indirectly via fl_set_term_flag( ). Although all n elements are waited upon, only one value is read and returned in vp. This is the one detected as the first one to change. In deciding which element is first, ip is used in wraparound fashion within the tag array.

In the case of a message element, be sure the m_ptr and m_mbx members of value area vp are initialized.

In the case of a mailbox element, the value passed back is the MBXMSG for the head message without the associated message data.

FL_CLEAR_CHNG

Clear the calling task change-status flags for specified real-time database elements.


int fl_clear_chng(id_t id, TAG* tp, uint n);

TAG* tp in Pointer to tag array specifying which elements to examine.


uint* ip out Pointer to index into tag array to be used and updated, if necessary, by the kernel.

void vp out Pointer to area to receive the value of the first changed element, if r==GOOD.




7

PA

K A

PI R

eference

Lib

rary

Returns GOOD


FLE_NULL_POINTER

FLE_LOCK_FAILED

FLE_BAD_TAG

Remarks Clear (to 0) the change state of the specified real-time database elements for the calling process only. This function undoes action of fl_set_chng( ). It is also useful for establishing initial conditions for a programming loop.

FL_CLEAR_WAIT

Clear the calling task wait flags for specified real-time database elements.


int fl_clear_wait(id_t id, TAG* tp, uint n);

Returns GOOD


FLE_NULL_POINTER

FLE_LOCK_FAILED

FLE_BAD_TAG

Remarks Clear (to 0) the wait flag of the specified real-time database elements for the calling process only. Also, use this function to establish initial conditions.

TAG* tp in Pointer to tag array.



TAG* tp in Pointer to tag array.




•

•

•

•

FL_COUNT_MBX

Determine the number of messages in a mailbox, validate a mailbox, or monitor a mailbox.


int fl_count_mbx(id_t id, TAG mbx, uint* np);

Returns GOOD: if good, also returns np.

ERROR: if error, call the fl_errno( ) function with the caller’s FactoryLink ID, and it returns one of the following errors:

FLE_NULL_POINTER

FLE_BAD_TAG

FLE_NOT_MAILBOX

FLE_LOCK_FAILED

FLE_LOCK_EXPIRED

Remarks Use fl_count_mbx( ) to determine how many messages are present in a mailbox. Generally, call fl_count_mbx( ) prior to allocating space for an array of MBXMSGs and calling fl_query_mbx( ). Also, use this function to validate a mailbox TAG and to monitor a mailbox.


TAG mbx in Mailbox to be accessed.

uint np out Message count to be filled in by the kernel.



7

PA

K A

PI R

eference

Lib

rary

FL_DBFMTT

Prepare a formatted string from a set of real-time database element values.


int fl_dbfmtt(id_t id, int maxlen, char bp0, char fp, TAG* args);

Returns Length of string

Remarks This function is similar to the C-language function sprintf( ). The format string can contain a format specifier of the following form:

%m.nc

where

m Represents the width of the output (optional). If m is preceded by a hyphen, the output is left justified. By default, the output is right justified.

n Represents the precision of the output (optional)

c Is one of the following:

Char Output

B String representing a DIGITAL value as ON or OFF

b Number representing a DIGITAL value as 0 or 1

d Integer value in base 10

u Unsigned integer value in base 10

x Integer value in base 16 (hexadecimal)

o Integer value in base 8 (octal)

c Single character

s Character string

Arguments id_t id in Task ID used to access real-time database.

int maxlen in Maximum number of characters that can be stored in the output buffer.

char bp0 out Pointer to memory buffer that stores formatted output.

char fp in Format string.

TAG* args in Tag array to be read from real-time database.



•

•

•

•f Floating-point number

g Floating-point number

% A percent sign

The next element in the args array for each format specifier is used to read a value from the real-time database. The element value is converted to the appropriate type for the format specifier and then formatted into the output buffer.

FL_ERRNO

Return the last FactoryLink error number generated by the calling process.


int fl_errno(id_t id);

Returns GOOD

Last Error Number

Remarks Returns the last FactoryLink error number generated by the calling process during the last call to the kernel that resulted in an error.

FL_FIND_GLOBAL_TAG

Retrieve tag number for one or more global element IDs for any accessible domain.

Syntax int fl_find_global_tag(TAG* tagp, uint n, uint* ids,

char* app, char* domain);

Returns Number of elements read from global CT file


Arguments TAG* tagp out Array where tag numbers are returned.

uint n in Number of elements to find.

uint* ids in Array of identification numbers.

char* app in Application directory ({FLAPP}).

char* domain in Current domain name.



7

PA

K A

PI R

eference

Lib

rary

Remarks Function fl_find_global_tag( ) performs searches for global tags based on the application domain hierarchy.

If fl_global_tag is called from the SHARED domain, it looks in the GLOBAL.CT configuration table for tags matching elements defined in the SHARED domain.

If it is called from the USER domain, it searches first for global tags defined in the USER domain, then in the SHARED domain.

GLOBAL.CT contains global elements available to all tasks. The GLOBAL.CT is searched for a matching value for each member of the ids array. The associated element is then copied into the corresponding member of the tagp array.

The id values are defined in FLIB.H.

The following code illustrates an example of the use of this function:

#include <flib.h>

…

uint ids[3] = {GT_SECONDS, GT_MINUTES, GT_HOURS};

TAG gtags[3];

ANA vals[3];

/* Find the tag numbers for the elements where the

timer task is updating the seconds, minutes, and hours */

fl_find_global_tag(&gtags[0], 3, &ids[0],getenv(“FLAPP”), setenv(“FLDOMAIN));;

/* Read the time tags */

fl_read(taskid, &gtags[0], 3, &vals[0]);

seconds = vals[0];

minutes = vals[1];

hours = vals[2];

FL_FORCED_WRITE

Force-write a specified element into the real-time database.




•

•

•

•int fl_forced_write(id_t id, TAG* tp, uint n, void* vp);

Returns GOOD


FLE_NULL_POINTER

FLE_LOCK_FAILED

FLE_BAD_TAG

FLE_OUT_OF_MEMORY

FLE_FLOAT_NAN

FLE_FLOAT_POS_INF

FLE_FLOAT_NEG_INF

Remarks This function operates similarly to fl_write( ) except all change states are set on regardless of whether the new values written into the database are the same as the previous values stored there. Upon completion of writing, those client processes waiting on any of the elements involved are awakened.

FL_GET_APP_DIR

Return the application directory for the specified process.


int fl_get_app_dir(id_t id, char* dir);

Returns GOOD: if good, dir is filled in.


TAG* tp in Pointer to tag array specifying which elements to force-write.

uint n in Number of elements to be force-written.

void* vp in Pointer to area holding values.


char* dir out Pointer to directory string to be returned.



7

PA

K A

PI R

eference

Lib

rary

ERROR: if error, an invalid FactoryLink ID is assumed.

Remarks fl_get_app_dir( ) returns the application directory for the process specified by the FactoryLink ID (usually, but not necessarily, the caller’s ID). It returns the application directory as a full path name, including a drive letter, if applicable.

This directory is the root directory for all dynamic files of a particular FactoryLink application.

FL_GET_CMD_LINE

Return the command line for the specified process.


int fl_get_cmd_line(id_t id, char* line);



Remarks fl_get_cmd_line( ) returns the command line for the process specified by the FactoryLink ID (usually, but not necessarily, the caller’s ID). The command line for a process is an ASCII string that generally contains instructions to the process to alter its normal behavior and additional environmental information.

FL_GET_COPYRT

Return a pointer to a copyright message for FactoryLink.


char* fl_get_copyrt(void);

Arguments None.

Returns Pointer to copyright message.

Remarks Do not modify the pointer returned by this function.


char* line out Pointer to command line to be filled in by the kernel.



•

•

•

•

FL_GET_CTRL_TAG

Return the control tag that refers to a digital or analog real-time database element for the specified process.


int fl_get_ctrl_tag(id_t , TAG* tag);

Returns GOOD: if good, tag is filled in.


Remarks fl_get_ctrl_tag( ) returns the control tag, which refers to a digital or analog real-time database element, for the process specified by the FactoryLink ID (which is not necessarily, and usually is not, the caller’s ID). The control tag for a process is used to control starting and stopping of the process. Any process may write a value of 1 or any other nonzero value to the control tag to tell the Run-Time Manager to start the process. Likewise, it may write a value of 0 to tell the Run-Time Manager to stop the process by setting the termination flag of the process.

FL_GET_ENV

Return the KENV structure of the client process.


int fl_get_env(id_t id, KENV* uep);

Returns GOOD

ERROR

Remarks Return a KENV structure describing the environment of the given client process, usually the calling process. The Run-Time Manager calls fl_set_env( ) to define this structure before the client process is started. This function returns all fields of the KENV structure.


TAG* tag out Pointer to control tag to be returned.

Arguments id_t id in Client FactoryLink ID (0-30) used as an index into array of KENVs kept by the kernel.

KENV* uep out Pointer to KENV structure to be returned.



7

PA

K A

PI R

eference

Lib

rary

FL_GET_MSG_TAG

Return the value of the real-time database message element for the specified process.


int fl_get_msg_tag(id_t id, TAG* tag);



Remarks fl_get_msg_tag( ) returns the value of a real-time database message element for the process specified by the FactoryLink ID (usually, but not necessarily, the caller’s ID). The MSG database element is written by the process and read by the Run-Time Manager. Its ASCII value continually describes what the process is doing, what problems it is encountering, and other similar information (another self-reporting mechanism). It is passed directly from the Run-Time Manager to the Real-Time Graphics process for display on the Run-Time Manager screen.

FL_GET_PGM_DIR

Return the program directory for the specified process.


int fl_get_pgm_dir(id_t id, char* dir);



Remarks fl_get_pgm_dir( ) returns the program directory for the process specified by the FactoryLink ID (usually, but not necessarily, the ID of the caller). The program directory is returned as a full path name, including a drive letter, if applicable.

This directory is the root directory for all static files, that is, for all files of an installed FactoryLink system but not part of any FactoryLink application.


TAG* tag out Pointer to message element to be returned.


char* dir out Pointer to directory string to be returned.



•

•

•

•

FL_GET_SERIAL

Return a pointer to the serial number assigned to the FactoryLink system.

Syntax char* fl_get_serial(void);

Arguments None.

Returns If successful, the function returns a pointer to serial number of the FactoryLink system.

If unable to access the kernel (task not initialized with the kernel), the function returns NULL.


FL_GET_STAT_TAG

Return the value of the real-time database analog status element for the specified process.


int fl_get_stat_tag(id_t id, TAG* tag);



Remarks fl_get_stat_tag( ) returns the value of the status element for the process specified by the FactoryLink ID (not necessarily the caller’s ID). The ANA status real-time database element is written by the process and read by the Run-Time Manager. Its numeric value continuously reflects the self-reported status of the process, as follows.


TAG* tag out Pointer to status element to be returned.

Status Symbolic Name Meaning

0 FLS_INACTIVE Process is inactive (not running).

1 FLS_ACTIVE Process is active (running).

2 FLS_ERROR Error (non-fatal error occurred).

3 FLS_STARTING Starting (initialization in progress).

4 FLS_STOPPING Stopping (shutdown in progress).



7

PA

K A

PI R

eference

Lib

rary

The Run-Time Manager converts the status value to an ASCII string and passes it to the Real-Time Graphics process for display on the Run-Time Manager screen.

FL_GET_TAG_INFO

Get the information associated with a specified list of real-time database elements.


int fl_get_tag_info (TAG* tp, uint n, i16* dp, u16* op);

Returns GOOD

ERROR

Remarks The dp array is filled in with one of the following values that correspond to the elements passed to it

Other Error (non-fatal error occurred).

Symbolic Name Status Meaning

FLS_INACTIVE 0 Inactive (not running).

FLS_ACTIVE 1 Active (running).

FLS_ERROR 2 Non-fatal error encountered.

FLS_STARTING 3 Starting/initialization.

FLS_STOPPING 4 Stopping/exiting.

Arguments TAG* tp in Pointer to tag array specifying which elements are involved.


i16* dp out Pointer to description array to be returned.

u16* op out Pointer to offset array to be returned.

Value Description

FL_BAD_DATA Element is out-of-range (bad t_data field).



•

•

•

•

The kernel fills in the op array with the offset into the vp buffer where the value is stored if fl_read( ), fl_write( ) or fl_forced_write( ) are called with the argument list (id, tp, n, vp). The caller may set either or both of the pointers dp or op to NULL if he does not wish to receive corresponding information, fl_get_tag_info( ) if all n elements in the tp array are valid, and ERROR if one or more of them is bad.

FL_GET_TICK

Get the current clock tick and/or current date and time maintained and reported by the operating system.


int fl_get_tick(u32* tickp, KDT* datetimep);

Returns Always GOOD

Remarks The clock tick is graduated in millisecond units and is non-decreasing until wraparound time (about once a month). The chief use is in measuring elapsed time. The date and time are stored in a DATETIME structure familiar to the operating system. Either tickp or datetimep may be NULL, which the kernel interprets as a lack of interest in the corresponding value; therefore, the kernel does not store the value.

FL_BAD_TYPE Element is a bad t_type field.

FL_UNDEFINED Element is undefined.

FL_DIGITAL Element is a digital (DIG).

FL_ANALOG Element is an analog (ANA).

FL_MESSAGE Element is a message (MSG).

FL_LANALOG Element is a long analog (longana).

FL_FLOAT Element is floating point (FLP).

FL_MAILBOX Element is mailbox (holds MBXMSGs).

Value Description

Arguments u32 tickp out Pointer to location for storing clock tick.

KDT* datetimep out Pointer to location for storing data and time.



7

PA

K A

PI R

eference

Lib

rary

FL_GET_TITLE

Return a pointer to the name of the product.


char* fl_get_title(void);

Arguments None.

Returns Pointer to name of product.


FL_GET_VERSION

Get the kernel version number.


uint fl_get_version();

Arguments None.

Returns FactoryLink kernel version number. Numerically returns version x.y as (x * 256) + y.

FL_GLOBAL_TAG

Retrieve the tag number for one or more global elements.


Returns Number of elements read from the global CT file.

Remarks GLOBAL.CT contains global elements available to all tasks. GLOBAL.CT is searched for a matching value for each member of the ids array. The associated element is then copied into the corresponding member of the tagp array.

The id values are defined in FLIB.H.

The following code illustrates an example of the use of this function:

Arguments TAG* tagp out Array where tag numbers are returned.

uint n in Number of elements to read.

uint* ids in Array of identification numbers.



•

•

•

•#include <flib.h>

…

uint ids[3] = {GT_SECONDS, GT_MINUTES, GT_HOURS};

TAG gtags[3];

ANA vals[3];

/* Find the tag numbers for the elements where the

timer task is updating the seconds, minutes, and hours */

fl_global_tag(&gtags[0], 3, &ids[0]);

/* Read the time tags */

fl_read(taskid, &gtags[0], 3, &vals[0]);

seconds = vals[0];

minutes = vals[1];

hours = vals[2];

A smart run-time task can initiate a shutdown of the FactoryLink system. To cause the Run-Time Manager to begin an immediate system shutdown, the task writes a value of 1 (ON) to the global, predefined analog element, RTMCMD.

FL_HOLD_SIG

Prevent or allow signal delivery for the calling process.


int fl_hold_sig(id_t id, int sig, int hold);

Returns Previous hold value (1 or 0) for the signal


int sig in Signal (0-31) to be affected.

int hold in Hold value:

1 = prevent signal delivery.

0 = allow signal delivery.



7

PA

K A

PI R

eference

Lib

rary

ERROR: if error, call the fl_errno( ) function with the caller’s FactoryLink ID and it returns FLE_BAD_ARGUMENT.

Remarks Initially, all signals except 0 and 1 are held; that is, by default, signals 0 and 1 are deliverable to the calling process, but others are not. A FactoryLink process wishing to be notified when its tag list of real-time database elements has changed must execute the following function to allow delivery of this signal:

fl_hold_sig(id, FLC_SIG_TAG_LIST_CHANGED, 0);

It is legal to hold any signal with fl_hold_sig( ), including signals 0 and 1.

FL_ID_TO_NAME

Translate a FactoryLink ID to a process name.


int fl_id_to_name(id_t id, char* name);

Returns GOOD: if good, name is filled in.


Remarks fl_id_to_name( ) checks the FactoryLink ID and, if the ID is valid, returns the associated process name.

FL_LIMIT_MBX

RTDB Access API.


int fl_limit_mbx(id_t, u16 dir,

TAG* mbxp, u16 nmbx,

u16* klimp;

Arguments id_t id in FactoryLink ID to be translated.

char* name out Pointer to process name to be returned.

Arguments id_t id in Task ID.



•

•

•

•

Returns GOOD: operation successful.

ERROR: Operation failed.

Remarks Function fl_limit_mbx( ) sets or gets the number kf Kbytes held by the given mailbox. If the limit is set to zero, the number if Kbytes a mailbox can reference is determined by the application system default as set by the Run-Time Manager.

See also “fl_write_mbx”

“fl_errno”

FL_LOCK

Lock the real-time database on behalf of the calling process.


int fl_lock(id_t id);

Returns GOOD

ERROR

Remarks Only one client process may have the real-time database locked at any given time. If the calling process calls fl_lock( ) and the real-time database is already locked by that same process, a counter is incremented and the lock remains in effect for the caller. This counter allows calls to fl_lock( ) and fl_unlock( ) to be nested.

u16 dir in Direction of information. If dir is

FL_FUNC_SET: sets mbx limit(s)

FL_FUNC_GET: returns mbx limit(s)

TAG* mbxp in Mailbox tags to set/get limits for.

u16 nmbx in Number of mailbox tags.

u16* klimp in/out If setting values, the new limits are passed within this array.

If getting values, the mailbox limits are returned within this array.




7

PA

K A

PI R

eference

Lib

rary

If another client process has already locked the real-time database, the caller is put to sleep (blocked) until his lock request can be honored. Upon return from fl_lock( ), only the calling process is granted access to the real-time database until it makes a corresponding call to fl_unlock( ), provided it does not execute fl_wait( ), either directly or indirectly. fl_wait( ) releases its lock and puts it to sleep. When it awakes, the lock is reinstated.

If the caller wants to keep the real-time database locked and thereby retain exclusive access to it, it must not call fl_change_wait( ) or write any synchronous elements via fl_write( ) or fl_forced_write( ).

FL_NAME_TO_ID

Translate a process name to a FactoryLink ID.


id_t fl_name_to_id(id_t id, char* name);

Returns FactoryLink ID

ERROR: if error, an invalid process name is assumed

Remarks fl_name_to_id( ) searches the domain of the given task id for the specified process name; and, if the process name is found, returns the associated FactoryLink ID.

FL_PATH_ACCESS

Check file access mode for a given file.

Syntax #include <flpath.h>

int fl_path_access(NPATH path);

Returns The file access mode of the file as one of the following character strings:

NPATH_READ

Arguments id_t id in Pointer to process name to be translated.

char* name in Task ID of calling task.

Arguments NPATH* path in Pointer to a previously allocated NPATH structure containing a normalized path name buffer.



•

•

•

•NPATH_WRITE

NPATH_READ | NPATH_WRITE

If specified file does not exist, returns ERROR.

Remarks The function fl_path_access( ) returns a string informing the calling program of the mode(s) (read-only, write-enable, or read/write) the calling program is authorized to access the specified file in, if available.

See also fl_path and related calls

FL_PATH_ADD

Catenates two normalized paths.


void fl_path_add(NPATH* path1, NPATH* path2);

Returns N/A

Remarks fl_path_add( ) catenates two paths. Any missing component of the second path p2 is taken from the first path p1 or from the current directory if the first path is null.


FL_PATH_ADD_DIR

Adds one subdirectory specification per call to the end of the directory portion of a path.


void fl_path_add_dir(NPATH* path, char* dir);

Arguments NPATH* path1 in/out Pointer to a previously allocated NPATH structure containing a normalized path name buffer.

NPATH* path2 in Pointer to a previously allocated NPATH structure containing a normalized path name buffer.

Arguments NPATH* path in/out Pointer to a previously allocated NPATH structure containing a normalized path name buffer.

char* dir in Directory name in system-specific format.



7

PA

K A

PI R

eference

Lib

rary

Returns N/A

Remarks fl_path_add_dir( ) adds a subdirectory specification to the end of the directory portion of a path. Only one subdirectory can be added to a path during each call to fl_path_add_dir( ). The subdirectory name should not contain any path-separator characters.


FL_PATH_ALLOC

Allocate a normalized path name buffer.


NPATH* fl_path_alloc(void);

Arguments None.

Returns If successful, returns a pointer to an allocated normalized path buffer.

If unsuccessful, returns NULL; an invalid process name is assumed.

Remarks The function fl_path_alloc( ) allocates and returns a pointer to a normalized path buffer. Programmers should call this function, rather than allocate the NPATH structure directly so a buffer for system-dependent information can be added to the path buffer.


FL_PATH_CLOSEDIR

Ends a directory search for a file.


void fl_path_closedir(NPATH* path);

Returns N/A

Remarks fl_path_closedir( ) ends a directory search.

See also “fl_path_opendir” and related calls




•

•

•

•

FL_PATH_CREATE

Create an empty file using the complete path specified.


int fl_path_create(NPATH* path);

Returns GOOD

ERROR

Remarks fl_path_create( ) creates an empty file using the complete path specified by the given NPATH. The file may then be opened, copied, referenced, or closed by any task with the proper file access privileges.

FL_PATH_CWD

Build a normalized path for the current working directory.


NPATH *fl_path_cwd(NPATH* path);

Returns Pointer to a normalized path buffer. The pointer is returned in the variable named in the call: PATH = fl_path_cwd( ).

NULL

Remarks fl_path_cwd( ) builds a normalized path for the current working directory. If the NPATH argument is NULL, fl_path_cwd( ) first calls fl_path_alloc( ) to allocate a NPATH buffer. Either way, the working directory may now be accessed using the path name built.

FL_PATH_DATE

Places formatted system date and time stamp from a specified file’s header into specified buffer.






7

PA

K A

PI R

eference

Lib

rary

long fl_path_date(NPATH* path, char* buf, size_t length);

Returns File date-and-time stamp.

ERROR

Remarks fl_path_date( ) formats the date and time stamp on a file (the date/time the file was last updated) into the caller’s buffer and returns the date and time (concatenated) as a long integer.

FL_PATH_GET_SIZE

Returns the size in bytes of the specified file.


long fl_path_get_size(NPATH* path);

Returns Size of file in bytes

ERROR

Remarks fl_path_get_size( ) returns the size of a specific file in bytes.

FL_PATH_GET_TYPE

Returns the file type of the specified file.


long fl_path_get_size(NPATH* path);


char* buf out Pointer to buffer for receiving data.

size_t length in Length of output buffer.





•

•

•

•Returns File type as one of the following constants:

NPATH_REGULARNPATH_DIRECTORYERROR

Remarks fl_path_get_type( ) returns the type of the file.

fl_path_get_type( ) returns the file type of the file specified. One of the following constants is returned:

NPATH_REGULAR

NPATH_DIRECTORY

fl_path_get_type( ) returns the file type of the file specified. One of the following constants is returned:

NPATH_REGULARNPATH_DIRECTORY

FL_PATH_INFO

Initialize date, time, size, and type of files allowed for the specified path.


int fl_path_info(NPATH* path);

Returns GOOD

ERROR

Remarks fl_path_info( ) initializes the date, time, size, and type for the path. If the path does not exist, fl_path_info( ) returns ERROR. Otherwise, it returns GOOD.

This function is called automatically by fl_path_opendir( ) and fl_path_readdir( ).

FL_PATH_MKDIR

Creates the directory specified by the directory portion of the indicated path.





7

PA

K A

PI R

eference

Lib

rary

int fl_path_mkdir(NPATH* path);

Returns GOOD

ERROR

Remarks fl_path_mkdir( ) creates the directory given by the directory portion of the path, if the directory does not already exist. It creates all directories and subdirectories necessary for the path, up to and including the last subdirectory specified in the NPATH structure.

For example, if none of the following directories exist:

/test

/test/mystuff

/test/mystuff/log

the following code fragment in C creates them all, in hierarchical order:

NPATH* np;

np = fl_path_set_dir(NULL, /test/mystuff/log);

fl_path_mkdir(np);

This function returns GOOD if the directories already exist. It returns ERROR only if at least one of the directories cannot be created because of a system error or insufficient privilege levels on the part of the caller.

See also “fl_path_rmdir” and related calls

FL_PATH_NORM

Convert part or all of a system-specific path string into a normalized path.


NPATH* fl_path_norm(NPATH* path, char* path_buf);



char* path_buf in Source string.



•

•

•

•Returns Pointer to the NPATH structure; also, if the pointer argument p passed in was NULL,

an NPATH buffer has been allocated and the pointer value is now set.

NULL

Remarks fl_path_norm( ) converts a system-specific path string into a normalized path. Any or all components of the path may be left out. If the NPATH argument is NULL, fl_path_norm( ) first calls fl_path_alloc( ) to allocate a NPATH buffer.

FL_PATH_OPENDIR

Begins a directory search for a file.


int fl_path_opendir(NPATH* path);

Returns GOOD

ERROR

Remarks fl_path_opendir( ) begins a directory search operation. The current directory information contained in NPATH is used as the directory to search and the current wild card pattern is used to select files. fl_path_opendir( ) returns GOOD if the directory could be opened for search or ERROR if it could not.

fl_path-opendir( ) reads the first entry in the directory.

See also “fl_path_closedir” and related calls

FL_PATH_READDIR

Reads next matching file from directory during a directory search for a file.


int fl_path_readdir(NPATH* path);

Returns GOOD





7

PA

K A

PI R

eference

Lib

rary

ERROR

Remarks fl_path_readdir( ) reads the next matching file in the directory and places the name of the file into the file name component of the path. The file type, date, time, and size are also stored in the NPATH structure. fl_path_readdir( ) returns GOOD if a matching file was found or ERROR, if not found.

The following code fragment in C demonstrates how to use directory search functions to print a directory listing:

NPATH* p;char date[80];char time[80];char fullpath[MAX_PATH_NAME];

= fl_path_norm(NULL, *.*);if ( fl_path_opendir(p) == ERROR )

{printf(Directory Not found\n);return;}

do{fl_path_date(p, date);fl_path_time(p, time);fl_path_sys(p, fullpath);printf(%s %s %s\n, date, time, fullpath);} while ( fl_path_readdir(p) != ERROR );fl_path_closedir(p);fl_path_free(p);

See also “fl_path_opendir”

“fl_path_closedir” and related calls

FL_PATH_REMOVE

Delete the file specified by the complete path given.




•

•

•

•int fl_path_remove(NPATH* path);

structure containing a normalized path name buffer

Returns GOOD

ERROR

Remarks fl_path_remove( ) removes the file specified by the complete path given.

See also “fl_path_create” and related calls

FL_PATH_RMDIR

Delete the directory specified by the directory portion of the indicated path.


int fl_path_rmdir(NPATH* path);

Returns GOOD

ERROR

Remarks fl_path_rmdir( ) deletes the directory given by the directory portion of the path.

See also “fl_path_mkdir” and related calls

FL_PATH_SET_DIR

Replaces the directory portion of the specified path with the directory argument specified converted to normalized form.


NPATH* fl_path_set_dir(NPATH* path, char* dir);






7

PA

K A

PI R

eference

Lib

rary

Returns Pointer to NPATH structure

NULL

Remarks fl_path_set_dir( ) replaces the directory portion of the path with the specified directory argument after converting the argument to normalized form. If the NPATH argument is NULL, fl_path_set_dir( ) first calls fl_path_alloc( ) to allocate a NPATH buffer. The file name, extension, and version are not modified by the fl_path_set_dir( ) function.

The fl_path_set_dir( ) function can be used to convert a system-specific path string into a normalized path if the path is known to refer to a directory.

See also fl_path( ) and related calls

FL_PATH_SET_DEVICE

Replaces the drive (device) name portion of the specified path with the argument specified after converting the argument to normalized form.


void fl_path_set_device(NPATH* path, char* drive);

Returns N/A

Remarks fl_path_set_device( ) replaces the drive (device) name portion of the path with the specified argument after converting the argument to normalized form.


FL_PATH_SET_EXTENSION

Replaces the file extension portion of the specified path with the argument specified after converting the argument to normalized form.


char* dir in Directory name in system-specific format.


char* drive in Device (drive) name in system-specific format.



•

•

•

•void fl_path_set_extension(NPATH* path, char* extension);

Returns N/A

Remarks fl_path_set_extension( ) replaces the file extension portion of the path with the specified argument after converting the argument to normalized form.


FL_PATH_SET_FILE

Replaces the file name portion of the specified path with the specified argument after converting the argument to normalized form.


void fl_path_set_file(NPATH* path,char* file);

Returns N/A

Remarks fl_path_set_file( ) replaces the file name portion of the path with the specified argument after converting the argument to normalized form.


FL_PATH_SET_NODE

Replaces the node name portion of the specified path with the specified argument after converting the argument to normalized form.



char* extension

in File name extension in system-specific format.


char* file in File name in system-specific format.



7

PA

K A

PI R

eference

Lib

rary

void fl_path_set_node(NPATH* path, char* node);

Returns N/A

Remarks fl_path_set_node( ) replaces the node name portion of the path with the specified argument after converting the argument to normalized form.


FL_PATH_SET_PATTERN

Sets a wild card pattern for subsequent directory searches.


void fl_path_set_pattern(NPATH*path, char* pattern);

Returns N/A

Remarks fl_path_set_pattern( ) sets a wild card pattern in the specified portion of the path in normalized form for subsequent directory searches.


FL_PATH_SYS

Convert a normalized path into a system-specific path string.



char* node in Node name in system-specific format.


char* pattern in Wild card pattern in system-specific

format.



•

•

•

•char *fl_path_sys(NPATH* path, char* syspath, size_t length);

Returns Pointer to a system-specific converted path string.

NULL

Remarks fl_path_sys( ) converts a normalized path into a system-specific path string. If the path argument is null, fl_path_sys( ) calls the C function malloc to allocate memory for the resulting path. The caller should call free to release the memory when it is no longer needed.

Example:

The following example opens a specified AC file in the {FLINK}/ac directory:

NPATH *np = (NPATH *)Null;

FILE *ac_file;char *flink; /* Buffer containing FLINK path*/ char *filename; /* Buffer containing AC file name */

np = fl_path_alloc();if (np == NULL)

return ERROR;fl_path_sys(path, flink, sizeof(flink));np = fl_path_add_dir(np, ac);fl_path_set_file(np, filename);fl_path_set_extension(np, ac);fl_path_set_version(np, "");ac_file = fl_path_fopen(np, r);fl_path_free(np);if (ac_file == NULL)return ERROR;


char* syspath out Destination string.

size_t length in String length.



7

PA

K A

PI R

eference

Lib

rary

FL_PATH_TIME

Places formatted system time stamp from a specified file’s header into specified buffer.


long fl_path_time(NPATH* path, char* buf, size_t length);

Returns Path date and time-stamping.

ERROR

Remarks fl_path_time( ) formats the time stamp on a file (the time, not including day or date, when the file was last updated) into the caller’s buffer. The format of the result from this function is operating-system dependent.

FL_PROC_EXIT

Detaches the task from the kernel.


int fl_proc_exit(id_t id);

Returns GOOD

ERROR

Remarks This function renounces all further access to the real-time database.

FL_PROC_INIT

Initialize the FactoryLink calling process.



char* buf out Buffer to contain returned time stamp.

size-t length in Length of output buffer.




•

•

•

•int fl_proc_init(char* task, char* desc);

Returns If successful at registering the start-up process with the kernel, function returns the calling routine FactoryLink task ID.

If unsuccessful, function returns one of the following negative (sign bit on) error codes:

FLE_NO_FLINK_INIT

FLE_BAD_PROC_NAME

FLE_ALREADY_ACTIVE

FLE_NULL_POINTER

FLE_NO_PROC_INIT

FLE_PROC_TABLE_FULL

Remarks This API has been retained from previous releases of FactoryLink to maintain compatibility for users to upgrade with no changes to existing startup code. However, new tasks should be written to use fl_proc_init_app( ) to register with the kernel. Any task, even one written for a previous release, may now override the environment values (use command arguments), if desired, by calling fl_proc_init_app( ). This API now calls the new version.

The current fl_proc_init( ) is now implemented as:

int fl_proc_init(char* task, char* desc){char flname[MAX_USR_NAME] ;char fluser[MAX_USR_NAME] ;char fldomain[MAX_USR_NAME]; fl_getvar(FLNAME, flname, sizeof(flname)) ; fl_getvar(FLDOMAIN, fldomain, sizeof(fldomain)) ; fl_getvar(FLUSER, fluser, sizeof(fluser)) ; return fl_proc_init_app(task,desc,flname,fldomain,fluser);}

See also ““””

Arguments char* task in Pointer to process name, 32 characters maximum, null-terminated.

char* desc in Pointer to process description, 80 characters maximum, null-terminated.



7

PA

K A

PI R

eference

Lib

rary

FL_PROC_INIT_APP

Initialize the calling process and register it with the FactoryLink kernel for a specific application/domain (replaces fl_proc_init).


fl_proc_init_app(char* task, char* desc,

char* flname, char* fldomain, char* fluser);

The flname argument specifies the name of the invocation the task is registering with. Normally, the value of the environment variable FLNAME is used.

The fldomain argument specifies the domain the task is registering for and is associated with at run time. Normally, the value of the environment variable FLDOMAIN is used.

The fluser argument specifies which instance of the specified domain the task is registering for. Normally, the value of the environment variable FLUSER is used.

Returns Calling routine FactoryLink task ID

If unsuccessful at registering the start-up process with the kernel, returns one of the following negative (sign bit on) error codes:

FLE_NO_FLINK_INIT

FLE_BAD_PROC_NAME

FLE_ALREADY_ACTIVE

FLE_NULL_POINTER

FLE_NO_PROC_INIT

FLE_PROC_TABLE_FULL

Arguments char* task in Pointer to process name, 32 characters maximum, null-terminated.

char* desc in Pointer to process description, 80 characters maximum, null-terminated.

char* flname in Pointer to application invocation name ({FLNAME}).

char* fldomain in Pointer to domain name ({FLDOMAIN}).

char* fluser in Pointer to user name ({FLUSER}).



•

•

•

•Remarks A calling process must pass a process name and description to fl_proc_init_app( ).

After validating the name, the kernel returns the FactoryLink ID for use in subsequent kernel calls to identify the caller.

Multiple threads of a single process can execute separate fl_proc_init_app( )s. In these cases, the kernel regards the threads as different client processes and assigns distinct IDs and kernel areas. Be aware the process that obtains an ID is the only process allowed to use that ID. Unpredictable behavior can result if a process or thread uses an ID not initially assigned to it.

FL_QUERY_MBX

Query a mailbox for a range of queued messages.


int fl_query_mbx(id_t id, TAG mbx, MBXMSG* mmp, uint i, uint n, uint* np);

Returns GOOD: if good, also fills in mmp and np


FLE_NULL_POINTER

FLE_BAD_TAG

FLE_NOT_MAILBOX

FLE_NO_MESSAGES

FLE_LOCK_FAILED

FLE_LOCK_EXPIRED



MBXMSG* mmp out Pointer to array of mailbox messages to filled in by the kernel.

uint i in Index relative to head of queue.

uint n in Requested number of mailbox messages.

uint* np out Actual number of mailbox messages to be filled in by the kernel.



7

PA

K A

PI R

eference

Lib

rary

Remarks Use this function to read one or more mailbox message headers without reading their message data and without dequeueing them. The MBXMSG holds information about the message, such as type, who sent it, and length of its data. Therefore, call fl_query_mbx( ) prior to allocating space for the message data and calling fl_read_mbx( ). The argument i specifies where, relative to the head of the message queue, reading is to begin (i = 0 means start at the head itself, i = 1 means skip the first message and start with the second, and so on). The message at the head of the queue is the oldest message in the mailbox. The argument n specifies how many maximum mailbox messages are requested to be read and the kernel fills in np with the actual number read.

FL_READ

Read specified elements from the real-time database.


int fl_read(id_t id, TAG* tp, uint n, void* vp);

Returns GOOD


FLE_NULL_POINTER

FLE_LOCK_FAILED

FLE_BAD_TAG

Remarks The elements may have mixed data types, as with all database access calls. The values of the elements are read from the real-time database and placed in the private data area of the calling process pointed to by vp. After each element is read, its change bit for the calling process is cleared. The change state for other client processes are


TAG* tp in Pointer to tag array specifying which elements to read.


void* vp out Pointer to area to receive values.



•

•

•

•unaffected. When reading blocks of mixed tag types, use fl_get_tag_info( ) to find out how much memory to prepare before calling fl_read( ) when reading blocks of mixed tag types.

See also “fl_read_no_clear”

FL_READ_APP_MBX

Read and dequeue a message from a mailbox in a specific application instance. (Replaces fl_read_mbx).


int fl_read_app_mbx(id_t id, id_t rid, MBX mbx, MBXMSG* msg, uint i);

Returns GOOD: if good, also fills msg and message data


FLE_NULL_POINTER

FLE_BAD_TAG

FLE_NOT_MAILBOX

FLE_NO_MESSAGES

FLE_ACCESS_DENIED

FLE_LOCK_FAILED

FLE_LOCK_EXPIRED


id_t rid in FactoryLink ID of process owning the mailbox.

MBX mbx in Mailbox to be accessed.

MBXMSG* msg out Pointer to a single mailbox message to be returned.




7

PA

K A

PI R

eference

Lib

rary

Remarks Use fl_read_app_mbx( ) to read a single mailbox message together with its message data. After this is done, the message is deleted or dequeued from the mailbox. If the buffer provided by the caller is not large enough, message data may be lost.

Just as in fl_query_mbx( ), the argument i specifies which mailbox message, relative to the head of the message queue, is to be read. However, fl_read( ) is less flexible because it always reads from the head message. The following call:

fl_read_app_mbx(id, id, &mbxtag, mmp, 0);

is equivalent to:

fl_read(id, &mbx, 1, mmp);

FL_READ_MBX

Read and dequeue a message from a mailbox (Obsolete. See fl_read_ app_mbx).


int fl_read_mbx(id_t id, TAG mbx, MBXMSG* mmp, uint i);

Returns GOOD: if good, also fills mmp and message data.


LE_NULL_POINTER

FLE_BAD_TAG

FLE_NOT_MAILBOX

FLE_NO_MESSAGES

FLE_ACCESS_DENIED

FLE_LOCK_FAILED

FLE_LOCK_EXPIRED



MBXMSG* mmp out Pointer to a single mailbox message to be returned.




•

•

•

•Remarks This API has been retained from previous releases of FactoryLink to maintain

compatibility for users to upgrade with no changes to existing startup code. However, new tasks should be written to use fl_read_app_mbx( ) with additional capabilities for multi-user systems. fl_read_mbx( ) can only be used to send messages to tasks in the same domain instance.

The following function call:

fl_read_mbx(id, &mbxtag, mmp, 0) ;

is equivalent to:

fl_read_app_mbx (id, id, &mbxtag, mmp, O) ;

FL_READ_NO_CLEAR


int fl_read(id_t id, TAG* tp, uint n, void* vp);;

Returns GOOD


FLE_NULL_POINTER

FLE_LOCK_FAILED

FLE_BAD_TAG

Remarks Function fl_read_no_clear( ) behaves exactly the same as function fl_read( ), except that the change bits for the reading tasks are not cleared. This enables the program to obtain the latest value of a tag while preserving the current state of the tag change bit such that a changed value can be processed at some later point.

See also “fl_change_read”

“fl_read”


TAG* tp in Pointer to tag array specifying which elements to read.


void* vp out Pointer to area to receive values.



7

PA

K A

PI R

eference

Lib

rary

FL_RECV_SIG

Receive a signal for the calling process.


int fl_recv_sig(id_t id);

Returns The signal (0-31) received.


FLE_NO_SIGNALS

FLE_LOCK_FAILED

FLE_LOCK_EXPIRED

Remarks If two or more signals are active and deliverable when fl_recv_sig( ) is called, the lowest numbered active signal is delivered to the caller. With the exception of signals 0 and 1, once a signal has been delivered, it is deactivated. This means once signals 0 and 1 are activated, they can never be deactivated.

FL_SEND_SIG

Send a signal to a target process.


int fl_send_sig(id_t id, char* name, int sig);



char* name in Name of FactoryLink process the signal is to be sent to.

int sig in Signal (0-31) to be sent.



•

•

•

•Remarks It is legal to send any signal to any active FactoryLink process. If the intended

recipient of the signal is asleep or waiting to lock or to access the database in the kernel and the signal is not being held, the recipient is immediately awakened and returned the error code FLE_SIGNALLED. The recipient should then call fl_recv_sig( ) to see which signal was sent.

Note the following function:

fl_ set_term_flag(id, name) ;

duplicates precisely the following function:

fl_send_sig(id, name, FLC_SIG_TERM_FLAG_SET ;

FL_SET_CHNG

Set the calling task change-status flags for specified real-time database elements.


int fl_set_chng(id_t id, TAG* tp, uint n);

Returns GOOD


FLE_NULL_POINTER

FLE_LOCK_FAILED

FLE_BAD_TAG

Remarks Set the change state of the specified real-time database elements for the calling process only to ON. This establishes initial conditions prior to entering a programming loop, particularly those that use fl_change_read( ) or fl_change_wait( ) to read real-time database values.


TAG* tp in Pointer to tag array specifying which elements are involved.




7

PA

K A

PI R

eference

Lib

rary

FL_SET_OWNER_MBX

Set the owner of a mailbox.


int fl_set_owner_mbx(id_t id, TAG mbx, uint onoff);

Returns GOOD


FLE_BAD_TAG

FLE_NOT_MAILBOX

FLE_ACCESS_DENIED

Remarks Use this function to set the owner of a mailbox.

If the value of onoff is TRUE, the owner of the mailbox is set to the calling task.

If the value of onoff is FALSE, the mailbox ownership is removed.

When a write is performed on the mailbox, the owner of a mailbox is signaled with flc_sig_message_received( ).

See also “fl_send_sig”

FL_SET_TERM_FLAG

Set the termination flag of a client process.


int fl_set_term_flag(id_t id, char* name);


TAG mbx in Mailbox to modify.

uint onoff in Flag to indicate operation.


char* name in Pointer to name of process the

termination flag is to be set for.



•

•

•

•Returns GOOD


FLE_BAD_PROC_NAME

FLE_NO_PROC_INIT

Remarks Set the termination flag of a client process within the same domain as the caller, which may be different from the calling process. Normally, only the Run-Time Manager uses this service.

FL_SET_WAIT

Set the calling task wait flags for specified real-time database elements.


int fl_set_wait(id_tid, TAG* tp, uint n);

Returns GOOD


FLE_NULL_POINTER

FLE_LOCK_FAILED

FLE_BAD_TAG

Remarks Set the wait flag of the specified real-time database elements for the calling process only to ON. This function is used in conjunction with fl_wait( ) to wait on a set of real-time database elements.

FL_SLEEP

Delay execution of the task for the indicated number of milliseconds.



TAG* tp in Pointer to tag array specifying which elements are involved.




7

PA

K A

PI R

eference

Lib

rary

void fl_sleep(ulong msecs);

Returns None.

Remarks The actual resolution of the delay is system-specific; however, at most, the delay is one second.

FL_TEST_TERM_FLAG

Ask the kernel the current status of current task termination flag.


int fl_test_term_flag(id_t id);

Returns OFF

ON

ERROR

Remarks Test the termination flag of the calling process and return its state to OFF or ON.

If the flag is ON, another client process (usually the Run-Time Manager) has requested that the caller exit via fl_proc_exit( ).

FL_UNLOCK

Unlock the real-time database for the calling process.


int fl_unlock(id_t id);

Returns GOOD

ERROR: if error, call the fl_errno( ) function with the caller’s FactoryLink ID for details.

Arguments ulong msecs in Number of milliseconds to delay.





•

•

•

•Remarks Calls to fl_lock( ) and fl_unlock( ) nest; one call to fl_unlock( ) undoes one previous

call to fl_lock( ).

FL_WAIT

Wait to read, write, or access the real-time database or certain elements in the database.


int fl_wait(id_t id, int req);

Returns GOOD


FLE_BAD_ARGUMENT

FLE_WAIT_FAILED

FLE_TERM_FLAG_SET

Remarks Ensure the fl_wait( ) function call is embedded between calls to functions fl_lock( ) and fl_unlock( ); otherwise, the task keeps the run-time database locked. Normally, a task only waits to read a value; therefore, the constant FLC_WAIT_READ is passed into the function.

FL_WAKEUP

Awaken a mask of FactoryLink client processes.


int fl_wakeup(id_t id, mask_t* mask, int req);


int req in Command; must have one of the

following symbolic values:

FLC_WAIT_READ.

FLC_WAIT_WRITE.

FLC_WAIT_ACCESS.




7

PA

K A

PI R

eference

Lib

rary

Returns GOOD


Remarks The calling process must pass a pointer to a bit mask of processes to be awakened. Only tasks in the caller’s domain can be affected. The kernel modifies this bit mask to reflect the processes that were actually sleeping at the time the call to fl_wakeup( ) occurred and were awakened.

The caller must also pass a symbolic command by setting req to one of the following symbolic commands:

FLC_WAIT_READ

FLC_WAIT_WRITE

FLC_WAIT_ACCESS

Setting req to FLC_WAIT_READ wakes only those processes waiting to read the database, which are those that have completed fl_wait( ), directly or indirectly, with req to FLC_WAIT_READ.

Similarly, setting req to FLC_WAIT_WRITE wakes only those waiting to write to the database.

Finally, setting req to FLC_WAIT_ACCESS wakes all of those waiting to do anything to the database, which is all of those sleeping while waiting to do anything except lock the database.

FL_WAKEUP_PROC

Awaken a specified FactoryLink process.


mask_t* mask in Pointer to bit mask of client processes to be awakened and updated by the kernel to reflect those that were actually asleep and have been awakened.

int req in Command; must have one of the

following symbolic values:

FLC_WAIT_READ.

FLC_WAIT_WRITE.

FLC_WAIT_ACCESS.



•

•

•

•int fl_wakeup_proc(id_t id, char* name, int req);

Returns GOOD


Remarks fl_wakeup_proc( ) is identical to fl_wakeup( ) except the caller specifies a task name instead of a mask of tasks to wake up.

See also “fl_wakeup”

FL_WRITE

Write specified elements into the real-time database.


int fl_write(id_t id, TAG* tp, uint n, void* vp);

Returns GOOD


FLE_NULL_POINTER

FLE_LOCK_FAILED

FLE_BAD_TAG

FLE_OUT_OF_MEMORY


char* name in Name of task to wake.

int req in Wake-up requests.


TAG* tp in Pointer to tag array specifying which elements are to be written.

uint n in Number of elements to be written.

void* vp in Pointer to area holding the values.



7

PA

K A

PI R

eference

Lib

rary

FLE_FLOAT_NAN

FLE_FLOAT_POS_INF

FLE_FLOAT_NEG_INF

Remarks The elements may have mixed data types. The values of the elements are read from the private data area pointed to by vp and written into the kernel database. After each value transfer, vp is incremented by the size of the element. If the new value of the element is different from its previous value, the element change state for all client processes is set to ON after it is written. Those processes waiting on a change to this element are then awakened.

The amount of data that can be written to a message tag is established by the length of data of the first write to that tag. The one exception is if an explicit message length is set within the tag definition.

For cases in which the length has not been pre-defined and the task needs to initialize the space allocated to the message for that value, then:

set m_ptr member of the MSG structure is set to NULL

set m_max field is set to a non-zero value

This allocates space for the message based on the value of m_max but will not set the change flag for the tag. This works only if no prior writes to the message tag have occurred.

FL_WRITE_APP_MBX

Write and queue a message into a mailbox. (Replaces fl_write_mbx).


int fl_write_app_mbx(id_t id, id_t wid, TAG mbx, MBXMSG* msg);

Returns GOOD



id_t wid in FactoryLink ID of process owning the mailbox.


MBXMSG* msg in Pointer to a single mailbox message to be returned.



•

•

•

•FLE_NULL_POINTER

FLE_BAD_TAG

FLE_NOT_MAILBOX

FLE_NO_MESSAGES

FLE_ACCESS_DENIED

FLE_OUT_OF_MEMORY

FLE_LOCK_FAILED

FLE_LOCK_EXPIRED

Remarks Use fl_write_app_mbx( ) to write a single mailbox message together with its message data to a mailbox by application instance. The message being written is added to the end of the queue. Prior to making this call, the caller must fill in the MBXMSG and the message data. The additional arguments in the current API allow the caller to specify the ID of the owner of the mailbox and an index into the queue. The owner’s ID is used to determine which instance of the mailbox to write this message into.

Note that within the same domain instance, fl_write( ) does the same thing as fl_write_app_mbx( ) when passed a mailbox TAG. That is, the function call

fl_write_app_mbx(id, id, &mbx, mmp) ;

is equivalent to:

fl_write(id, &mbx, 1, mmp) ;

FL_WRITE_MBX

Write and queue a message into a mailbox. (Obsolete. See fl_write_ app_mbx( )).


int fl_write_mbx(id_t id, TAG mbx, MBXMSG* mmp);

Returns GOOD


FLE_NULL_POINTER



MBXMSG* mmp in Pointer to a single mailbox message.



7

PA

K A

PI R

eference

Lib

rary

FLE_BAD_TAG

FLE_NOT_MAILBOX

FLE_NO_MESSAGES

FLE_ACCESS_DENIED

FLE_OUT_OF_MEMORY

FLE_LOCK_FAILED

FLE_LOCK_EXPIRED

Remarks This API has been retained from previous releases of FactoryLink to maintain compatibility for users to upgrade with no changes to existing startup code. However, new tasks should use fl_write_app_mbx( ) with additional capabilities for multi-user systems. fl_write_mbx( ) can only be used to send messages to tasks in the same domain instance.

fl_write_mbx(id, &mbxtag, mmp) ;

is equivalent to:

fl_write_app_mbx(id, Id, &mbxtag, mp) ;

FL_XLATE

Translate a key to its associated message.


char* fl_xlate (char* key);

Returns Pointer to message if key found; equal to keyptr if key not found

Remarks This function returns the text associated with the passed in key. The associations must have been previously created by loading a message translation file via fl_xlate_init( ) and/or fl_xlate_load( ).

Example 1

Allocate a message array, such as message[ ], and call the translation function to access messages in the message file and put the result in message[ ]. In the following example, the function copies the string normal shutdown (the message associated with the key SHUTDOWN) into message[ ].

Arguments char* key in Pointer to key to search for.



•

•

•

•char message[100];strcpy(message, fl_xlate(SHUTDOWN));

See also “fl_xlate_init”

“fl_xlate_load”

FL_XLATE_INIT

Message translation initialization; loads the first message file.


int fl_xlate_init (char* name, char* bp, uint blen);

Returns Number of messages read and buffered or ERROR.

Remarks This function, along with fl_xlate( ), comprises the basis of the message-translation facility. These two functions allow run-time tasks to print messages stored in external disk files called message files.

When called to initialize the message translation environment, the function fl_xlate_init( ) starts a fresh translation tree and loads the default translation file MASTER.TXT. The user-specified translation file is then loaded on top of the existing definitions. Duplicate definitions are superseded by the last file loaded. The function returns the total number of translations loaded from both the MASTER.TXT file as well as the user-specified file or it returns ERROR if there has been an error.

The buff and len parameters of fl_xlate_init( ) are not used by the function but were retained to stay compatible with existing code.

A task that uses the message translation facility can be written so it is independent of the messages it prints. It is dependent on the mnemonic keys but not the messages. In particular, it may be written so it is independent of the language the messages are written in. Achievement of this independence is the main purpose of message translation.

Arguments char* name in Name of message file.

char* bp Unused parameter that remains for backward compatibility.

uint blen Unused parameter that remains for backward compatibility.



7

PA

K A

PI R

eference

Lib

rary

Message files are ASCII text files that can be edited and changed with an ordinary text editor. The current working copies of these files on a FactoryLink system are in the directory {FLINK}/MSG/{LANG} and all are assumed to have the extension .TXT. Message files must conform to the following rules:

The message translation functions assume lines beginning with an asterisk are comments and ignores these lines. They also ignore blank lines.

Non-comment, non-blank lines serve to translate a key to an associated message. They must have the following form:

KEY white space MESSAGE

The message may be enclosed within double quote marks for clarity and to avoid the stripping of leading and trailing white space by the translation function. It may contain %, the substitution character used by PRINTF and SPRINTF.

A vertical bar (|) is allowed as a separator within the white space for compatibility with the format of FactoryLink .KEY files.

When editing a message file, place the most commonly used messages near the beginning of the file so access to the commonly used messages is quicker than to other messages, particularly when the buffer in use is small.

To use the message-translation functions, a task first calls the initialization function, which opens the message file {FLINK}/MSG/EN/RUNMGR.TXT, as shown in the following example:

fl_xlate_init(RUNMGR, NULL, 0);

This function loads the contents of message file {FLINK}/MSG/EN/RUNMGR.TXT into an in-memory binary tree which is sorted by message token.

See also “fl_xlate”

“fl_xlate_load”

“fl_xlate_set_tree”

“fl_xlate_get_tree”

FL_XLATE_LOAD

Load the specified file (passed as a parameter) into the current translation tree replacing any duplicate key.


int fl_xlate_load (char* fname);

Arguments char* fname in File name to load tree data from.



•

•

•

•Returns Number of entries loaded from this file.

ERROR

Remarks The function fl_xlate_load( ) loads the specified file into the current translation tree, replacing any duplicate keys. The function returns the number of entries loaded from this file or returns ERROR.

To load a new tree, an alternate tree to the default tree should have been created previously using the fl_xlate_set_tree( ) function. The new tree becomes the default tree into which the keys from the xlate file are loaded. Tasks may maintain more than one translation tree.

FactoryLink determines the language currently running and loads the text file from the correct language subdirectory under {FLINK}/MSG/{XX} where XX represents the currently selected FactoryLink language.

Example 1

int num_msg;num_msg = fl_xlate_init(runmgr, NULL, 0);if (num_msg == 0)return ERROR;rum_msg = fl_xlate_load(iml);if (num_msg == 0)return ERROR;printf(%s\n, fl_xlate(token));

Example 2

If the current language variable is not defined, the call:

num_msg = fl_xlate_init(iml, NULL, 0)

loads the {FLINK}/MSG/master.txt file into the tree and then loads the {FLINK}/MSG/iml.txt file into the tree. The return value is the total number of translations loaded from both files. Duplicates are only counted once.

The call

num_msg = fl_xlate_load(iml)

loads the file {FLINK}/MSG/iml.txt into the tree and returns the number of translations.

The call

num_msg = fl_xlate_load(/temp/test)

loads the file /TEMP/test.txt into the tree and returns the number of translations.

Example 3

If the current language variable is defined as DE, the following call:



7

PA

K A

PI R

eference

Lib

rary

num_msg = fl_xlate_init(iml, NULL, 0)

loads the {FLINK}/MSG/DE/master.txt file into the tree and then loads the {FLINK}/MSG/DE/iml.txt file into the tree. The return value is the total number of translations loaded from both files. Duplicates are counted only once.

The call

num_msg = fl_xlate_load(iml)

now loads the file {FLINK}/MSG/DE/iml.txt into the tree and returns the number of translations.

The call

num_msg = fl_xlate_load(/temp/test)

still loads the file /TEMP/test.txt into the tree and returns the number of translations.


“fl_xlate_init”



FL_XLATE_GET_TREE

Returns the address of the current translation tree or the string NULL if no translation files have been loaded.


void* fl_xlate_get_tree( void );

Return Address of the current translation tree; returns NULL if no translation files have been loaded

Remarks This is useful when a program maintains multiple translation trees. This function returns the address of the current translation tree (default translations for FactoryLink tasks) is returned by calling this function.

Tasks may maintain more than one translation tree. Translation files may be kept in libraries, one per language used, for ease of use. This guarantees all tasks remain language-independent and allows run-time tasks to use the fl_xlate( ) functions for all message output.

Example

void *english, *french; /* pointers to 2 trees */

int num_msg1, num_msg2;



•

•

•

•num_msg1 = fl_xlate_init(english/iml, NULL, 0);

english = fl_xlate_get_tree();

num_msg2 = fl_xlate_init(french/iml, NULL, 0);

french = fl_xlate_get_tree();

fl_xlate_set_tree (english); /* Switch to English tree */

printf (%s\n, fl_xlate(token);

fl_xlate_set_tree (french); /* Switch to French tree */


You may switch translation trees at any point in the program and switch back when ready without losing any data.


“fl_xlate_init”



FL_XLATE_SET_PROGPATH

Overrides the environment variable {FLINK}, allowing programs to support the -p command parameter for overriding the default program directory.


int fl_xlate_set_progpath(char* progname);

Returns The number of characters in the program path name.

FL_XLATE_SET_TREE

Sets the current translation tree to the tree at the specified address. Ensuing file loads and translations use this tree.


Arguments char* progname in Pointer to path of program directory to be used for translation.



7

PA

K A

PI R

eference

Lib

rary

void* fl_xlate_set_tree( void* tree);

Returns Pointer sent by the programmer.

NULL

Remarks This function is useful when a program maintains multiple translation trees. This function switches the current active translation tree (that referenced by subsequent fl_xlate( ) calls).

This function also starts a fresh translation tree file.

Tasks may maintain more than one translation tree. Translation files may be kept in libraries, one per language used, for ease of use. This guarantees all tasks remain language-independent and allows run-time tasks to use the fl_xlate( ) functions for all message output.

Example 1

void *english, *french; /* pointers to 2 trees */

int num_msg1, num_msg2;

num_msg1 = fl_xlate_init(english/iml, NULL, 0);

english = fl_xlate_get_tree();

num_msg2 = fl_xlate_init(french/iml, NULL, 0);

french = fl_xlate_get_tree();

fl_xlate_set_tree (english); /* Switch to English tree */


fl_xlate_set_tree (french); /* Switch to French tree */


You switch translation trees at any point in the program and switch back when ready without losing any data.

The following example shows fl_xlate_set_tree( ) starting a fresh tree:

fl_xlate_set_tree(NULL) ; /* start new tree */


“fl_xlate_init”


“fl_xlate_load”

Arguments void tree in Pointer to tree used for translation.



•

•

•

•

FLDTP_ACTION_GET_ARGS

Syntax #include <fldtp.h>

int fldtp_action_get_args(FLDTP_ACTION* ap, void*** f_argv);

Returns >=0; number of arguments

FLDTP_E_{…} error code

Remarks Function fldtp_action_get_args( ) returns the number of arguments associated with the given action record. It also returns the handle to the argument array itself. This array should be treated as read-only.

See also “fldtp_action_set_args”

FLDTP_ACTION_GET_DESTROYF

Direct Tag Processing API.


int fldtp_action_get_destroyf(FLDTP_ACTION* ap, FLDTP_FUNC_DESTROY* destroyf);

Returns FLDTP_E_GOOD

FLDTP_e_{…} error code

Remarks Function fldtp_action_get_destroyf( ) returns a pointer to the destruction notification function associated with the given action record.

See also “fldtp_action_set_destroyf”

FLDTP_ACTION_GET_ID


Arguments FLDTP_ACTION* ap in DTP action handle.

VOID*** F_ARGV out Argument array.


FLDTP_FUNC_DESTROY* destroyf out Destruction function pointer.



7

PA

K A

PI R

eference

Lib

rary

int fldtp_action_get_id(FLDTP_ACTION* ap, void*** id);



Remarks Function fldtp_action_get_id( ) returns the identifier bound to the given action record.

See also “fldtp_action_set_id”

FLDTP_ACTION_GET_PRIORITY


int fldtp_action_get_priority(FLDTP_ACTION* ap, long* prio);



Remarks Function fldtp_action_get_priority( ) returns a processing priority that has been assigned to the given action record.

See also “fldtp_action_set_priority”

FLDTP_ACTION_SET_ARGS


int fldtp_action_set_args(FLDTP_ACTION* ap, short f_argc, void* f_argv[]);


void*** id out ID to associate with the given record.


long* prio out Priority assigned to given record.

Arguments FLDTP_ACTION* ap in/out DTP action handle.

short f_argc in Number of arguments in the array.

VOID*[ ] f_argv in Argument array.



•

•

•

•Returns FLDTP_E_GOOD


Remarks Function fldtp_action_set_args( ) binds user data to the given action record. This allows the process function to have all salient information immediately available.

Consider the typedef FLDTP_FUNC_ACTION process functions must conform to:

typedef void (*FLDTP_FUNC_ACTION) (TAG*, VAL*, short, void**);

When processing tag values, the DTP calls the process function pointed to by afunc with its tag, its value, and a pair of user-defined arguments. The short and void** parameters, as shown in the above typedef, are the f_argc and f_argv set using fldtp_action_set_args( ).

Arguments f_argc and f_argv define the user arguments to pass to the process function. Function fldtp_action_set_args( ) makes a copy of void pointer array f_argv when attaching it to the given action record. As such, the caller need not to preserve the void pointer array afterwards.

The data the pointer within f_argv array references is arbitrary. This should be information that the process function needs in order to process the associated tag.

See also “fldtp_action_get_args”

“fldtp_action_set_destroyf”

“fldtp_insert”

FLDTP_ACTION_SET_DESTROYF


int fldtp_action_set_destroyf(FLDTP_ACTION* ap, FLDTP_FUNC_DESTROY* destroyf);



Remarks Function fldtp_action_set_destroyf( ) attaches a destruction notification function to the given action record. This function is called just prior to the action record being destroyed. Action records are destroyed as a result of a DTP removal call or as part of destroying the DTP it is attached to.


FLDTP_FUNC_DESTROY* DESTROY out Destruction function pointer.



7

PA

K A

PI R

eference

Lib

rary

Consider the typedef FLDTP_FUNC_DESTROY process functions must conform to:

typedef void (*FLDTP_FUNC_DESTROY) (TAG*, short, void**);

The short and void** parameters, as shown in the above typedef, are the f_argc and f_argv set using fldtp_action_set_args( ).

The main motivation for associating a destruction function with an action record is to provide an easy mechanism to release memory referenced in the f_argv void array. If the action record is the sole user of attached information, this destruction callback allows the user to release it.

See also “fldtp_action_get_destroyf”

“fldtp_action_set_args”

“fldtp_remove”

“fldtp_remove_group”

“fldtp_destroy”

FLDTP_ACTION_SET_ID


int fldtp_action_set_id(FLDTP_ACTION* ap, void* id);



Remarks Function fldtp_action_set_id( ) binds an identifier to the given action record.

Setting the ID provides a mechanism for differentiating one action record from another, either by groups or by individuals. The most common use for this ID is the removal of a group of action records from the DTP based on this ID.

The ID is a void* and, by default, ID comparisons are based on equality. This default comparison can be superseded with a user provided function.

See also “fldtp_action_get_id”


“fldtp_set_comparef”


void* id in ID to associate with the given record.



•

•

•

•

FLDTP_ACTION_SET_PRIORITY


int fldtp_action_set_priority(FLDTP_ACTION* ap, long prio);



Remarks Function fldtp_action_set_priority( ) binds a processing priority to the given action record. The action record priority controls the order simultaneous tag changes are processed in. The default priority for action records in 0.

The priority is only considered when the DTP is processing by priority.

See also “fldtp_action_get_priority”

“fldtp_set_proc_by”

FLDTP_CHANGE_READ


int fldtp_change_read(FLDTP* dtp, id_t task_id,int start_from, FLDTP_TAG** dtp_tag, VAL* val);



long prio in Priority assigned to the given record.

Arguments FLDTP dtp in DTP action handle.

id_t task_id in Argument array.

int start_from in Read next tag that changes, starting from:

FLDTP_READ_TOP

or

FLDTP_READ_NEXT.

FLDTP_TAG** dtp_tag Out Tag value that has changed.

VAL* val Out Tag value.



7

PA

K A

PI R

eference

Lib

rary


Remarks Analogous to fl_change_read( ), function fldtp_change_read( ) reads the value of the next changed tag. The definition of next is set by the start_from parameter. Only a single pass through the tags is made.

See also “fldtp_proc_wait”

FLDTP_CREATE


int fldtp_create(FLDTP* dtp);



Remarks Function fldtp_create( ) allocates, initializes, and returns a DTP handle. This DTP handle is passed in all subsequent calls to the FLDTP API.

See also “fldtp_destroy”

FLDTP_DESTROY


int fldtp_destroy(FLDTP* dtp);



Remarks Function fldtp_destroy( ) releases the DTP handle along with all resources held by it. This handle should not be referenced once it is destroyed.

See also “fldtp_create”

FLDTP_GET_COMPAREF


Arguments FLDTP* dtp out DTP handle.

Arguments FLDTP* DTP in/out DTP handle.



•

•

•

•int fldtp_set_comparef(FLDTP* dtp, FLDTP_FUNC_COMPARE* cfunc);



Remarks Function fldtp_get_comparef( ) returns the function used when comparing the IDs associated with an action record.

See also “fldtp_get_compare”

FLDTP_GET_MSGLEN


int fldtp_get_msglen(FLDTP* dtp, int* msglen);



Remarks Function fldtp_get_msglen( ) returns the size for the buffer used to read the value of a message tag from the real-time database.

See also “fldtp_get_msglen”

FLDTP_GET_TAGCNT


int fldtp_get_tagcnt(FLDTP* dtp, long* tagcnt);

Arguments FLDTP* dtp in DTP handle.

FLDTP_FUNC_COMPARE* CFUNC out Function to compare IDs with.


int* msglen out Length of message read buffer.


long* tagcnt out Number of tags referenced by the DTP.



7

PA

K A

PI R

eference

Lib

rary



Remarks Function fldtp_get_tagcnt( ) returns the number of unique tags inserted into the given DTP.

See also “fldtp_insert”

FLDTP_INSERT


int fldtp_insert(FLDTP* dtp, TAG* tag, FLDTP_FUNC_ACTION afunc, FLDTP_ACTION** ap);



Remarks Function fldtp_insert( ) registers a tag with its action into the DTP. The dtp argument specifies which DTP instance to insert into. The tag argument specifies the tag to be processed. The afunc argument specifies the process function to use for processing the given tag. The typedef FLDTP_FUNC_ACTION defines the Syntax the process function must conform to:

typedef void (*FLDTP_FUNC_ACTION) (TAG*, VAL*, short, void**);

When processing tag values, the DTP calls the process function pointed to by afunc with its tag, its value, and a pair of user-defined arguments. The short and void** parameters, as shown in the above typedef, are an argc/argv combination analogous to the arguments to the main routine of a C program.

It is legal to insert the same tag multiple times. In such a case, the process function will be called for each insertion. In FactoryLink terminology, DTP supports using the same tag to trigger several events.

See also “fldtp_action_set_args”

“fldtp_remove”

Arguments FLDTP* dtp in/out DTP handle.

TAG* tag in Tag to process.

FLDTP_FUNC_ACTION afunc in Function to process tag with.

fldtp_action** ap out Record created by insertion.



•

•

•

•

FLDTP_PROC


int fldtp_proc(FLDTP* dtp, id_t task_id);



Remarks Function fldtp_proc( ) immediately invokes all action records inserted into the given DTP. For each action record, the associated tag is read and its action function invoked with the tag value. Only a single pass through the tags is made.



FLDTP_PROC_ACTION


int fldtp_proc_action(FLDTP* dtp, FLDTP_ACTION* ap, id_t task_id);



Remarks Function fldtp_proc_action( ) reads the tag and invokes the action function associated with the given action record handle.

See also “fldtp_insert”

FLDTP_PROC_CHANGE



id_t task_id in Task handle.


FLDTP_ACTION* ap in Action record handle.




7

PA

K A

PI R

eference

Lib

rary

int fldtp_proc_change(FLDTP* dtp, id_t task_id);



Remarks Function fldtp_proc_change( ) invokes the action functions bound to those tags within the DTP that have changed. Only a single pass through the tags is made.

This function is similar to function fldtp_proc_wait( ), except it does not put the task to sleep. Hence, the function is most useful for tasks that must poll the real-time database because they are waiting on external events (network traffic, GUI events).



FLDTP_PROC_TAG


int fldtp_proc_tag(FLDTP* dtp, TAG* tag, id_t task_id);



Remarks Function fldtp_proc_tag( ) reads the tag and processes all action records associated with it. Priority-based processing is honored by this function.



FLDTP_PROC_WAIT





TAG* tag in Tag to execute all action records with.




•

•

•

•int fldtp_proc_wait(FLDTP* dtp, id_t task_id);



Remarks Function fldtp_proc_wait( ) invokes the action functions bound to those tags within the changed DTP. Only a single pass through the tags is made.

If no changes are outstanding when calling this function, then it puts the task to sleep until one of the tags within DTP tags changes. Upon awakening, any changed tags are processed before the function returns to the caller.

Function fldtp_proc_wait ( ) is the most commonly used of the DTP process functions.

See also “fldtp_proc_change”


FLDTP_REMOVE


int fldtp_remove(FLDTP* dtp, FLDTP_ACTION* ap);



Remarks Function fldtp_remove( ) deletes the given action record from the DTP. If a destruction function is associated with the action record, it is invoked during the removal.

Removing the action record from the DTP destroys it. As such, the action record handle should no longer be referenced after the fldtp_remove( ) call.

See also “fldtp_action_set_destroyf”

“fldtp_insert”




FLDTP_ACTION* ap in/out Record to remove.



7

PA

K A

PI R

eference

Lib

rary


FLDTP_REMOVE_GROUP


int fldtp_remove_group(FLDTP* dtp, TAG* tag,

FLDTP_FUNC_ACTION afunc, void* id);



Remarks Function fldtp_remove_group( ) deletes a group of action records from the DTP based on any combination of tag, action function pointer, and/or ID. Passing NULL for parameter tag, afunc, or id excludes that parameter from being included in the removal criteria.

For example, passing NULL for both tag and afunc means that all action records whose ID matches parameter id will be removed. The parameters passed as NULL are not considered as part of the removal criteria.

Whenever an action record is removed, its destruction handler, if set, is invoked.


“fldtp_action_set_destroyf”

“fldtp_insert”

“fldtp_remove”

FLDTP_SET_COMPAREF



TAG* tag in Tag to process.

FLDTP_FUNC_ACTION afunc in Function to process tag with.

void* id out Record created by the insertion.



•

•

•

•int fldtp_set_comparef(FLDTP* dtp, FLDTP_FUNC_COMPARE cfunc);



Remarks fldtp_set_comparef( ) establishes the function to use when comparing the IDs associated with an action record. Typedef FLDTP_FUNC_COMPARE defines the Syntax to which the comparison function must conform:

typedef int (*FLDTP_FUNC_COMPARE) (void* , void*);

#define FLDTP_ID_SAME 0

#define FLDTP_ID_DIFF 1

The comparison function is used when removing action records based on a particular ID. The user provided comparison function returns constant FLDTP_SAME_ID for equivalent IDs or constant FLDTP_DIFF_ID for different ones.

The default comparison is a simple equality (void* a == void* b). Setting the comparison function to NULL returns the DTP back to this default.



FLDTP_SET_MSGLEN


int fldtp_set_msglen(FLDTP* dtp, int msglen);




FLDTP_FUNC-COMPARE cfunc in Function to compare IDs with.


int msglen in New length for message read buffer.



7

PA

K A

PI R

eference

Lib

rary

Remarks Function fldtp_set_msglen( ) establishes a new size for the buffer used to read the value of a message tag from the real-time database. The default size is 80 characters.

See also “fldtp_get_msglen”

FLDTP_SET_PROC_BY


int fldtp_set_proc_by(FLDTP* dtp, int proc_by);



Remarks fldtp_set_proc_by( ) determines the order by which simultaneous tag changes are processed. The selection of process order profoundly affects the operation of the DTP. The following discusses the behavior of both.

Processing by first-in-first-out, or FLDTP_BY_FIFO( ), is analogous to how most FactoryLink tasks currently operate. The order of processing mirrors the order unique tag entries are inserted into the DTP. This manner of processing is optimal since the value of a single tag is stored in memory at any one time. It is also the default mode of processing unless the DTP is explicitly set otherwise.

Processing by priority, or FLDTP_BY_PRIO( ), invokes change handlers based on an ascending order of priorities. Priority-based processing begins by taking a snapshot of all changed tags with their values. Then, the process functions for the changed tags are invoked in order of their assigned priority. As a result, the overhead of tag processing increases in terms of reaction time and memory use.

Unless your task has specific requirements that one action always be processed prior to another, use FLDTP_BY_FIFO( ).

See also “fldtp_action_set_priority”

FLDTP_WAIT



int proc_by in Process by constant

FLDTP_BY_FIFO or FLDTP_BY_PRIO.



•

•

•

•int fldtp_wait(FLDTP* dtp, id_t task_id);



Remarks fldtp_proc_wait( ) is analogous to fl_wait( ) in that the task goes to sleep until one of the tags inserted into the DTP changes. Unlike the PAK function, fldtp_wait( ) returns immediately if one of the tags within the DTP has changed prior to invoking this function.

See also “fldtp_proc_change”

FLNTAG_CALC_BASE

Normalized Tag API.

Syntax #include <flntag.h>

int flntag_calc_base(FLNTAG* ntag, TAG* tag, char* def_dims, TAG* base);

Returns FLNTAG_E_GOOD

FLNTAG_E_HANDLE

FLNTAG_E_INVARG

FLNTAG_E_DIMNUM

FLNTAG_E_DIMSIZ



Arguments FLNTAG* ntag in FLNTAG to obtain definition with.

TAG* tag in RTDB location (tag) for reference contained within the given ntag.

char* def_dims in Dimensions defined for the given record.

TAG* base out Base RTDB location (tag) for object referenced by ntag.



7

PA

K A

PI R

eference

Lib

rary

Remarks Given a normalized tag reference, its RTDB location and its dimension definition, function flntag_calc_base( ) calculates the RTDB location for the base of the given ntag. For nonarrayed objects, the location of a tag reference always equals the base tag location obtained from the object definition.

This function is commonly called during the loading of a task CT. CTs often contain the reference string, the RTDB location for the reference string, and the dimension definition for the object being referenced. This function uses these three pieces of information to obtain the base location for reference.

See also “flntag_create”

“flntag_find_def”

FLNTAG_CALC_TAG

Normalized Tag API.


int flntag_calc_tag(FLNTAG* ntag, TAG* base, char* def_dims, TAG* tag);


FLNTAG_E_HANDLE

FLNTAG_E_INVARG

FLNTAG_E_DIMNUM

FLNTAG_E_DIMSIZ

Remarks Given a normalized tag reference, its base RTDB location, and its dimension definition, function flntag_calc_tag( ) calculates the RTDB location for the given ntag. For nonarrayed objects, the location of a tag reference always equals the base tag location obtained from the object definition.

Code Sample: Converting a FLNTAG to a TAG

Arguments FLNTAG* ntag in FLNTAG to obtain definition for.

TAG* base in RTDB location (tag) for base of the reference contained within given ntag.

char* def_dims in Dimensions defined for given object.

TAG* tags out Base RTDB location (tag) for object referenced by ntag.



•

•

•

•#include <flntag.h>

/*

* Function convert_ntag2tag() returns the RTDB location for the

* given reference.

*/

int convert_ntag2tag(FLNTAG *ntag, CT *objct, TAG *tag)

{

FLOBJREC def

int rv;

if ((rv = flntag_find_def(ntag, objct, &def) == FLNTAG_E_GOOD)

{

rv = flntag_calc_tag(ntag,

flobjrec_get_tag(&def),

flobjrec_get_dimen(&def),

tag);

}

return rv;

}


“flntag_find_def”

FLNTAG_CREATE

Normalized Tag API.


FLNTAG* flntag_create(void);

Returns This function returns:

Type Description



7

PA

K A

PI R

eference

Lib

rary

Remarks Function flntag_create( ) allocates a normalized tag instance. This handle is subsequently passed to all other flntag_…( ) functions.

See also “flntag_destroy”

FLNTAG_DESTROY

Normalized Tag API.

Syntax: #include <flntag.h>

FLNTAG* flntag_destroy(FLNTAG* ntag);

Remarks Function flntag_destroy( ) releases all resources associated with the given handle. This handle should not be referenced after being destroyed.


FLNTAG_FIND_DEF

Normalized Tag API.


int flntag_find_def(FLNTAG * ntag, CT* objct, FLOBJREC* rec);


FLNTAG_E_GENERAL

FLNTAG_E_HANDLE

FLNTAG_E_INVARG

FLNTAG Normalized tag instance handle.

NULL Memory allocation failure.

Arguments FLNTAG* ntag in/out Handle to release.

Arguments FLNTAG* ntag in FLNTAG to obtain definition for.

CT* objct in Object CT handle.

FLOBJREC* REC OUT Definition for object referenced by ntag.



•

•

•

•Remarks Function flntag_find_def( ) returns the definition for the object referenced by the

given ntag. This definition is obtained by searching the application object CT.

Parameter objct, a required argument for this function, is obtained via function ct_open_obj( ).


“flntag_parse_ref”

“ct_open_obj”

FLNTAG_FIND_TAG

Normalized Tag API.


int flntag_find_tag(FLNTAG* ntag, CT* objct, TAG* tag);


FLNTAG_E_GENERAL

FLNTAG_E_HANDLE

FLNTAG_E_INVARG

FLNTAG_E_DIMNUM

FLNTAG_E_DIMSIZ

Remarks Function flntag_find_tag( ) returns the RTDB location (the tag) for the object referenced by the given ntag. This location is obtained by searching the application object CT for the object definition, obtaining the base RTDB location from that definition, and finally, calculating the offset from the base if the tag is an arrayed element.

For example, if the ntag equates to reference x[3], function flntag_find_tag( ) returns RTDB location for x[3], not x[0].

Parameter objct, a required argument for this function, is obtained via function ct_open_obj( ).

Arguments FLNTAG* ntag in FLNTAG to obtain object for.

CT* objct in Object CT handle.

TAG* tags out RTDB location (tag) for object referenced by ntag.



7

PA

K A

PI R

eference

Lib

rary

See Also: “flntag_create”

“flntag_calc_tag”


“ct_open_obj”

FLNTAG_GEN_OBJNAMEFLNTAG_GEN_REFFLNTAG_GEN_STR

Normalized Tag API.


int flntag_gen_str(FLNTAG* ntag, u16 incl, char* outstr, int maxlen);

#define flntag_gen_objname(ntag, outstr, maxlen) \ flntag_gen_str(ntag,FLNTAG_S_DIMEN, outstr, maxlen);

#define flntag_gen_ref(ntag, tagref, maxlen) \flntag_gen_str(ntag, 0, tagref, maxlen);

Returns RTN>0

FLNTAG_E_HANDLE

FLNTAG_E_INVARG

Arguments FLNTAG* ntag in FLNTAG to generate string for.

u16 incl in Bit-wise OR-flags for components to include within generated string.

FLNTAG_S_NODE.

FLNTAG_S_NAME.

FLNTAG_S_DIMEN.

FLNTAG_S_MEMBER.l

char* outstr out Target buffer for generated string.

If NULL, string is not generated.

int maxlen in Maximum number of characters to write to outstr buffer.



•

•

•

•Remarks Function flntag_gen_str( ) generates the reference string to which the given ntag

equates. When nonzero, parameter incl, a bit mask, includes one or more components from the resulting string.

Normally, the entire reference is desired and the macro flntag_gen_ref( ) can be used to build it.

Macro flntag_gen_objname( ) can be used for cases where the object name is needed.



FLNTAG_GET_DIMENFLNTAG_GET_MEMBERFLNTAG_GET_NAMEFLNTAG_GET_NODE

Normalized Tag API.


char* flntag_get_dimen(FLNTAG* ntag);

char* flntag_get_member(FLNTAG* ntag);

char* flntag_get_name(FLNTAG* ntag);

char* flntag_get_node(FLNTAG* ntag);

Returns VALUE STRING

Remarks Normalized tags consist of four components: node, name, dimension, and member. This set of flntag_get_…( ) functions allows the caller to obtain the current value of an individual component. All values are returned as null-terminated strings.

Currently, these entry points are implemented as macros, which return a pointer to the private members of the FLNTAG structure. These addresses must be treated in a read-only manner.


“flntag_gen_str”

“flntag_set_dimen”

Arguments FLNTAG* ntag in FLNTAG whose components are being obtained.



7

PA

K A

PI R

eference

Lib

rary

“flntag_set_member”

“flntag_set_name”

“flntag_set_node”

FLNTAG_PARSE_BRKT4DIMSFLNTAG_PARSE_COMMA4DIMS

Normalized Tag API.


i16 flntag_parse_brkt4dims(char* dimstr, u16* dims, u16 dimslen);

i16 flntag_parse_comma4dims(char* dimstr, u16* dims, u16 dimslen);

Returns >=0

FLNTAG_E_HANDLE

FLNTAG_E_INVARG

FLNTAG_E_REFSYN

Remarks Functions flntag_parse_brkt4dims( ) and flntag_parse_comma4dims( ) parses the given dimension string and returns the number of dimensions contained within it. These functions can also return the value of the each individual dimension as a u16 array.

Function flntag_parse_brkt4dims( ) expects dimension strings such as [2][4].

Function flntag_parse_comma4dims( ) expects dimension strings such as 2,4.

See also “flntag_parse_ref”

Arguments char* dimstr in Dimension string to parse.

u16* dims out Size of each dimension found in parsed string returned within array of u16s.

If equal to NULL, this information is not returned.

u16 dimslen in Length of given dims array.

This prevents overwrites if the number of dimensions exceed size of array.



•

•

•

•

FLNTAG_PARSE_REF

Normalized Tag API.


int flntag_parse_ref(FLNTAG* ntag, char* ref);

Return FLNTAG_E_GOOD

FLNTAG_E_HANDLE

FLNTAG_E_INVARG

FLNTAG_E_REFSYN

Remarks Function flntag_parse_ref( ) parses the given object reference string and loads its components into the given normalized tag handle. Each component is validated to ensure it has a legal syntax.

The previous contents of the given ntag are overwritten by this operation.


“flntag_gen_ref”

FLNTAG_SET_DIMENFLNTAG_SET_MEMBERFLNTAG_SET_NAMEFLNTAG_SET_NODE

Normalized Tag API.


int flntag_set_dimen(FLNTAG* ntag, char* dimen);

int flntag_set_member(FLNTAG* ntag, char* member);

int flntag_set_name(FLNTAG* ntag, char* name);

Arguments FLNTAG* ntag in/out FLNTAG to load according to given reference.

char* ref in Reference to parse.



7

PA

K A

PI R

eference

Lib

rary

int flntag_set_node(FLNTAG* ntag, char* node);


FLNTAG_E_HANDLE

FLNTAG_E_INVARG

FLNTAG_E_REFSYN

Remarks Normalized tags consist of four components: node, name, dimension, and member. This set of flntag_set_…( ) functions allows an individual component of the FLNTAG to be modified.

Valid syntax is enforced by these functions. The enforced rules include the following

See also flntag_set and related functions

“flntag_create”

“flntag_gen_str”

“flntag_get_dimen”

“flntag_get_member”

“flntag_get_name”

“flntag_get_node”

Arguments FLNTAG* ntag in/out FLNTAG whose components are being set.

char* value in Target set value.

Type Description

flntag_set_node

flntag_set_name

flntag_set_member

Allowed characters are _@$ and alphanumeric.

First character cannot be numeric.

flntag_set_dimen String containing dimensions delineated by brackets: [4] [5].



•

•

•

•

FLOBJREC_GET_CHGBITS FLOBJREC_GET_DESCR FLOBJREC_GET_DIMENFLOBJREC_GET_DOMAINFLOBJREC_GET_NAMEFLOBJREC_GET_PERWHEN FLOBJREC_GET_TAGFLOBJREC_GET_TYPE

Object CT API.


u16 flobjrec_get_chgbits(FLOBJREC* rec);

char* flobjrec_get_descr(FLOBJREC* rec);

char* flobjrec_get_dimen(FLOBJREC* rec);

char* flobjrec_get_domain(FLOBJREC* rec);

char* flobjrec_get_name (FLOBJREC* rec);

u16 flobjrec_get_perwhen(FLOBJREC* rec);

TAG* flobjrec_get_tag(FLOBJREC* rec);

char* flobjrec_get_type(FLOBJREC* rec);

Returns VALUE

Remarks This set of flobjrec_get_…( ) functions allows the caller to obtain an attribute value from an object definition.

While most of the return values are self-explanatory, a few require more detail.

Function flobjrec_get_chgbits( ) refers to a persistence attribute, namely whether to set the change bit on when restoring the persistent value. The value is 1 for set-the-change-bit and 0 for not.

Arguments FLOBJREC* REC in FLOBJREC whose components are being obtained.



7

PA

K A

PI R

eference

Lib

rary

Function flobjrec_get_perwhen( ) refers to a persistence attribute, namely whether to save the object value based on time, on value change, or on domain persistence settings. The legal values for this attribute are as follows

Function flobjrec_get_tag( ) returns the base RTDB location. For arrayed objects, this is the RTDB location for the object that has all dimensions equal to zero.

Currently these entry points are implemented as macros, which, in some cases, return a pointer to the private members of the FLOBJREC structure. These addresses must be treated in a read-only manner.

See also “ct_find_obj”

“ct_open_obj”

MAKE_FULL_PATH

Combine the directory and file name into a full path name.


void make_full_path(char* fpathp, char* dpathp, char* rpathp);

Returns No values

Remarks The name of the file to be added to the directory may contain a relative path.

Value Meaning

0 No persistence of value.

1 Timed-based persistence.

2 Exception-based persistence.

3 Time-based and exception-based persistence.

4 Domain setting persistence.

Arguments char* fpathp out Buffer where full path is returned.

char* dpathp in Base directory.

char* rpathp in Name of file to be added to directory.



•

•

•

•To maintain backward compatibility with previous releases, make_full_path( ) has been retained in FLIB, but it is currently implemented using the fl_path( ) functions. For new development, fl_path( ) functions should be used.

void make_full_path(pathp, dirp, filep)

{

NPATH *p1;

NPATH *p2;

p1 = fl_path_alloc( );

p2 = fl_path_alloc( );

if ( dirp == NULL )

fl_path_cwd(p1);

else

fl_path_set_dir(p1, dirp);

fl_path_norm(p2, filep);

fl_path_add(p1, p2);

fl_path_sys(p1, pathp, MAX_PATH);

fl_path_free(p1);

fl_path_free(p2);

}

See also fl_path( ) and related functions

SPOOL

Spool a file or line.


int spool (id_t id, char* flags, char* message,length;




7

PA

K A

PI R

eference

Lib

rary

char* flags in Pointer to zero-terminated string. String specifies file or line to be printed, output device to be used (Devices 1 through 5), type of data (text or binary) to be expected, and whether to delete the file (assuming file, not line, is specified) after successful printing. The following recognized characters determine these actions and may or may not be displayed in the string.

Char. ActionB Use binary mode in

reading and printing file or line. Send Binary ON command sequence before beginning and Binary OFF sequence upon completion of print job.

D Delete file after successful printing.

L Print line that follows (message specifies line to be printed).

# Use output Device number # (where # stands for digit from 1-5 with default = 1).

char* message in Pointer to character string.

int length in Length in bytes of the message Value string. Used if both the L and B flags are specified, which means the message string is not necessarily zero-terminated. It may contain any ASCII characters, including 00 hexameter string.



•

•

•

•Do not specify both the L and D flags in the same job request. Any other combination is permitted. The order of characters in the flags string is immaterial.

Returns A signed integer (an int) that indicates the status of the job request. A value of zero indicates the request has been accepted and queued by the SPOOL task. Any non-zero value indicates some sort of error has occurred.

If the return value is negative, it was not received by the SPOOL task.

If the return value is positive, it was received by SPOOL but could not be processed.

Specifically, the return values have the following meanings

Remarks The SPOOL function is related to the FactoryLink Print Spooler task.

Print Spooler Task

Return Value Meaning

-3 Request too long (flags and message strings combined exceed 128 bytes; program error is likely cause).

-2 Request not sent (caused by another task repeatedly tying up channel to SPOOL task).

This can only be caused by a program error in one of the tasks running on the system. The task waits a few seconds before retrying the request. Should subsequent retry attempts fail, the calling task prints an informative error message, such as Print Spooler is temporarily unavailable, and takes appropriate action.

-1 Request sent to SPOOL task, but no reply was received.

The likely cause is the SPOOL task is not running. The task prints an error message, such as Print Spooler not running, and either quits or finds an alternate way to output its data.

0 Request accepted and queued by SPOOL task.

1 Request has a bad flags argument and was rejected, caused by either a non-existent output device or a program error. If the output device does not exist, no entry displays in the Print Spooler Configuration table for the given device number.

2 Request could not be processed because the spool queue is full; requesting task may wish to try again later.



7

PA

K A

PI R

eference

Lib

rary

The Print Spooler processes job requests from other FactoryLink tasks running on the system. These job requests specify either a line to be output or a file to be printed on a printer or other output device or file.

The task initiating the job request must be an integral part of the request itself or specify what file or line is to be printed, which output device is to be used, and what type of data (text or binary) printed.

When the SPOOL task receives a job request, it checks to see whether the designated output device is processing earlier requests. If the output device is busy, it queues, or spools, the current request. Otherwise, it processes the request immediately. Requests queued for later processing are not prioritized. In effect, printing occurs on all output devices simultaneously.

EXAMPLES

The following examples in C illustrate how to use the SPOOL function:

Example 1

int spool(id, “2", ”C:/CONFIG.SYS", 0);

MEANING: Print the indicated text file on Device 2.

Example 2

int spool(id, “L”, “** WARNING: Line pressure LOW. *”, 0);

MEANING: Print the indicated line on Device 1 (the default printer).

Example 3

int spool(id, B3, C:/{FLINK}/USR/TASK.DAT, 0);

MEANING: Print the indicated binary data file on Device 3.

Example 4

int spool(id, D, C:/SOURCE/TEST.LOG, 0);

MEANING: Print the indicated text file on Device 1 and delete the file afterwards.

In all of these examples, the value of int should be checked. The only possible return values in these examples are -2 through 2.



•

•

•

•

8

PA

K A

PI R

eference

Lib

rary



FactoryLink Menu Creation Tool

INTRODUCTION

The FactoryLink Menu Creation Tool allows developers the ability to customize the menus available in the FactoryLink Configuration Explorer. Developers can add menu options to pop-up menus in the Configuration Explorer tree, extending the functionality of the FactoryLink development environment.

Customization of the FactoryLink menus allows developers a great deal of flexibility. It should be noted, however, that improper use of the Menu Creation Tool can produce undesirable effects (e.g. vital menu items disappearing or functioning improperly). Users of the Menu Creation Tool should have a sound fundamental understanding of FactoryLink and the underlying technologies before modifying the menu structure.

STARTING FACTORYLINK MENU CREATION TOOL

1 From Windows Explorer, find the Program Files>USDATA>Application Objects folder.

2 Locate the FlinkMenuEditor.exe program icon and double-click to launch the Menu Creation Tool.

FACTORYLINK MENU CREATION TOOLUser Interface Description


•

•

•

•

USER INTERFACE DESCRIPTION

There are three panes or work areas in the Menu Creation tool. The Menu Nodes pane displays all the existing menu nodes in the current FactoryLink application. The Context Menu Items pane shows the existing Context Menu items available for the selected Menu Node. Clicking on a context menu entry in this pane will display its corresponding properties in the Property Browser pane.

There are four controls at the bottom of the Menu Creation window:

ClassesButton

The classes button allows you to select .....

Menu NodePane

Context MenuItems Pane

Property BrowserPane

FACTORYLINK MENU CREATION TOOLQuick Start Procedure


8

PA

K A

PI R

eference

Lib

rary

Disable MenuCaching

Checkbox

To improve performance the Menu Creation tool caches the current menu structure upon startup. Recent changes to the menu structure may not be displayed. Selecting this checkbox will ensure that the most current menu structure is displayed.

Menus Button

Close Button Saves all changes and closes the Menu Creation tool.

QUICK START PROCEDURE

The following example is provided to demonstrate the addition of a very simple item to the FactoryLink Application menu. In this example, you will add a context menu item to launch a specific document file for editing. Selecting the menu item within Configuration Explorer will launch Microsoft Word and load a specific document file.

To add a menu item, perform the following steps.

1 In the Menu Nodes pane, expand the tree to display a FactoryLink application object.

2 Select the application icon.



•

•

•

• 3 In the Context Menu pane, right click on Standard Menu and click Add Menu Item from the

pop-up menu. The Add Menu Item dialog will be displayed.

4 In the Caption field, enter Open Design Doc.

5 In the Key field, enter DOCS.



8

PA

K A

PI R

eference

Lib

rary

6 Click the Action tab to display the options for this menu entry.

7 In the Action Type drop-down list, select Shell.

8 In the Program Path box, enter the path to Microsoft Word.

9 In the Program Arguments, enter the name of an existing Word document.

10 In the Program Directory, enter the path to the Word document.

11 Click OK to save your changes. Close the FactoryLink Menu Creation tool by clicking the Close button.



•

•

•

•To see the results of adding this menu item, open Configuration Explorer and right-click on the application icon. The pop-up menu will include the new item labeled Open Design Doc. Selecting this item will launch Microsoft Word and open the appropriate document.

FACTORYLINK MENU CREATION TOOLAdding Menu Items


8

PA

K A

PI R

eference

Lib

rary

ADDING MENU ITEMS

The Add Menu Items dialog is the primary tool for customizing the Configuration Explorer menus. There are two tabs on the dialog. The Display tab configures the appearance and behavior of the new menu item. The Action tab is used to configure the actions and events associated with selecting the new menu item.

Configuring Display Options

The following fields and controls are available on the Display tab.

Caption This field defines the text to be displayed on the menu item. To implement hot-key functionality, place the ampersand character (&) before the appropriate letter in the caption.

Key This field defines the internal identifying key for the menu item.

Position Index This field determines the order in which menu items are displayed. Menu items are displayed in descending order according to this value. For example, if you want the items Valve, Pump, and Motor to be displayed in that order, assign them position indexes in descending order:



•

•

•

•Valve 100Pump 300Motor 500

Position ItemKey

Menu ItemOperations

Selecting the + option will cause the new menu item to be added to the appropriate pop-up menu. Selecting the - option will prevent the associated item from being displayed in the pop-up menu. Selecting the = option will cause the new menu item to replace the menu item corresponding to the Key field, defined above.

Menu ItemStyle

These radio buttons define the type of menu selection used. Normal menu items simply cause the specified action to occur. Checked/Unchecked items are toggled between two states, generally on or off. Present/Not Present menu items

The following items are used to configure the state of the menu item. State information is read from an existing object within the FactoryLink workspace.

Prog/Class ID The program or class ID of the status component from which the state information is to be read

ReverseStatus Value

Check this box if you wish to reverse the Boolean value of the state value read from the object

StatusComponent

Properties

This button allows you to create a list of the status properties required by the status component. To add a property, enter it in the text entry box and click the Add button. To remove a property from the list, select it in the list and click the Remove button.

If the status component requires a property value in order to return status information, use the Set Property Value button to establish the value.

Configuring Action Options

There are four types of available actions that can be associated with custom menu items. The appearance of the Action tab will vary depending on which item is selected in the Action Type drop-down list.



8

PA

K A

PI R

eference

Lib

rary

The following paragraphs describe the configuration of the available actions.

Shell Actions

The Shell action causes an external executable to be launched in a new window.

Note: Environment variables may be used in any of the following items. Environment variables should be enclosed by the percent (%) character, as in %USERNAME%. Substitued parameters should be preceded by the dollar sign character ($).

Program Path Full path to the executable program to be launched by the menu selection.

ProgramArguments

This field can contain any program arguments required by the executable.

ProgramDirectory

Full path of the working directory for the executable program.

Disable OutputWindows

Check this option if you wish to suppress any output display for the shell program. For example, if you are shelling to a batch file, but wish to hide the output window for the batch file from the user, you would check this box.



•

•

•

•Launching COM Components

Selecting the Action Type of COM Component will cause the appropriate component to be started.

The following configuration options are available to COM components launched from the custom menu item:

Prog/Class ID This field contains the program or class ID for the COM component to be launched.

Frame LaunchType

The following items are used to define and set properties required for the component:

RequiredProperty

This part of the dialog allows you to create a list of the properties required by the COM component. To add a property, enter it in the text entry box and click the Add button. To remove a property from the list, select it in the list and click the Remove button.

If the status component requires a property value in order to function properly, use the Set Property Value button to establish the value.



8

PA

K A

PI R

eference

Lib

rary

Launching Visual Components

Selecting the Action Type of Visual Component will cause the appropriate component to be started. Typically this action would be used to launch components with a visual user interface, such as a Visual Basic program.

The following configuration options are available to visual components launched from the custom menu item:

Prog/Class ID This field contains the program or class ID for the COM component to be launched.

Window Style There are up to six options available from the Window Style drop-down list. These options configure how the visual component is displayed:

Active Doc Loads the component in an ActiveX browser window within the Configuration Explorer window.

Dockable Tool Loads the component as a dockable tool inside the Configuration Explorer.

Product Tab Loads the component as a tabbed dialog inside the Configuration Explorer



•

•

•

•Modeless Form Loads the component in new window, external to

Configuration Expolorer

Form View Loads the component as a form inside Configuration Explorer

MDI Child Loads the component as a separate pane inside Configuration Explorer

Form Caption Defines the caption used for the component. This field supports $ properties and environment variables.

The following items are used to define and set properties for the component:

RequiredProperty

This part of the dialog allows you to create a list of the properties required by the COM component. To add a property, enter it in the text entry box and click the Add button. To remove a property from the list, select it in the list and click the Remove button.

If the status component requires a property value in order to function properly, use the Set Property Value button to establish the value.

When a visual component is launched, there may be various other component windows open within Configuration Explorer. It may be desirable to have the contents of these windows synchronized with the new component. To establish this synchronization, the following items are used to configure the synchronization for the component:

Synchroniza-tion Key

Defines the key for the synchronization process

Synchroniza-tion Type

Defines the type of synchronization implemented. Selecting Family will... need info.

FACTORYLINK MENU CREATION TOOLBrowsing Node Properties


8

PA

K A

PI R

eference

Lib

rary

Launching Containers

Selecting the Action Type of Container will cause the appropriate container to be started. No configuration is required for container objects, as the actions will be initiated by the container.

BROWSING NODE PROPERTIES

USING CUSTOM ICONS

The Menu Creation Tool also allows developers to customize the icons used in the Configuration Explorer tree. Custom icons can be either .ico files or .bmp files. For best results, icons should be 16X16 pixel.bmp files with magenta as the transparent color. The finished icon file should be placed in the Program Files\USDATA\Studio\Icons\16X16 directory.

Once you have created your icon, perform the following steps to change the icon for a specific node class:

1 From Windows Explorer, find the Program Files>USDATA>Application Objects folder.

FACTORYLINK MENU CREATION TOOLUsing Custom Icons


•

•

•

• 2 Locate the FlinkMenuEditor.exe program icon and double-click to launch the Menu Creation

Tool.

3 In the Menu Nodes pane, double-click the icon of the item you wish to change. The Node Properties property sheet will be displayed.

4 In the Value column, double-click the icon you wish to change. Enter the name of the new icons (without the file extension) and click OK to save your changes.

If Configuration Explorer is running, it must be restarted for the new icons to be visible.

• • • • • • • • • • • • • • • • • • • • • • • • • • • • • •

Part I

293

Part IIConfiguration PAK


• • • •

Configuration PAK at a Glance

Using Configuration PAK


1. Read what the Configuration PAK does and about required hardware and software.

Chapter 9, “Configuration PAK Overview”

2. Read about Configuration Architecture, including configuration storage, configuration sessions, and data structure hierarchy.

Chapter 10, “Configuration Architecture”

3. Read about Library Services, including configuration session API, attributes catalog API, configuration database API, object database API, and exception handling.

Chapter 11, “Configuration PAK Library Services”

4. Read about the API Reference Guide. Chapter 13, “Configuration PAK API Reference Library”

CONFIGURATION PAK AT A GLANCE

276/ FactoryLink 7.0 / Programmer’s Access Kit

•

•

•

•


• • • •

9

Co

nfig

uratio

n P

AK

O

verview

Chapter 9

Configuration PAK Overview

The Configuration PAK (CFGPAK) is a collection of software libraries, C-language source modules, and related documentation used to design and construct programs that directly manipulate the configuration databases of a FactoryLink application.

Users generally configure tasks, or more specifically configuration databases, using FactoryLink’s Configuration Manager. The Configuration Manager (FLCM) provides an interactive, graphical interface to view, add, modify, and/or delete task information within a particular application. As the user alters this task configuration, FLCM maintains the application integrity by validating new records, creating undefined tags, and recording the location of tag references.

Programs created with CFGPAK are able to automate many of the operations found in FLCM, saving users from manually importing and exporting configuration using FLCM. For example, a programmable logic controller (PLC) software package could scan the active PLC addresses and enter corresponding read/write records into that driver’s configuration databases.

This part assumes the reader is proficient at PAK task creation; therefore, it does not cover material found in Part One: FactoryLink Programmer’s Access Kit (PAK).

CONFIGURATION PAK OVERVIEWRequired Hardware and Software


•

•

•

•

REQUIRED HARDWARE AND SOFTWARE

CFGPAK is a FactoryLink option layered upon the FactoryLink Programmer’s Access Kit (PAK). All requirements as stated in Chapter 9, “Configuration PAK Overview” of Part I in this manual apply to the CFGPAK.

INSTALLATION

To install the Configuration Databases Programmer’s Access Kit, consult the Windows NT and Windows 95 Installation Guide” regarding the installation of option media.


• • • •

10

Co

nfig

uratio

n

Arch

itecture

Chapter 10

Configuration Architecture

Some basic concepts must be understood to construct a program that manipulates configuration databases. This chapter introduces the concepts used in writing a program incorporating CFGPAK. Topics include:

• Configuration Storage

• Configuration Sessions

• Data Structure Hierarchy

The order of these topics parallels the order of the client task usage of these resources. The layered CFGPAK architecture enforces this ordering.

For example, configuration tables cannot be accessed until a configuration session is established.

This chapter presents a general understanding of the entire system to assist you in understanding the details included in the next chapter.

CONFIGURATION ARCHITECTUREConfiguration Storage


•

•

•

•

CONFIGURATION STORAGE

FactoryLink applications consist of a heterogeneous set of configuration databases, drawing files, and Math & Logic scripts. CFGPAK groups these storage entities into three types:

• Reserved configuration databases (CDBs)

• Task CDBs

• External configuration

CFGPAK provides access to the application’s reserved and task CDBs. Reserved CDBs are those the system maintains internally and are indirectly altered by the user. FactoryLink development tools, such as the configuration manager (FLCM), manage these tables behind the scenes. The system tables are DOMAIN, OBJECT, TYPE, and XREF. Internal constraints apply to these tables and the CFGPAK prevents invalid alterations of them.

Task CDBs are the physical storage for the configuration entered into the panels of FLCM. The information contained therein directs the task to its run-time duties. The CDB itself is a relational database table. It consists of one or more records (or rows), each comprised of several fixed-length fields.

Tasks are often configured by more than one CDB, and these CDBs are usually related in a manner similar to SQL’s (Structured Query Language) definition of a primary key. A primary key is a combination of one or more fields whose values form a unique identifier for each record in the table. Given this primary key, a record from one table can be related to one or more records in a secondary table. By including the primary key in records of a related table, an association forms between the related table and the table owning the primary key. This is known as a one-to-many relationship, and these types of relationships are a prevalent theme throughout task CDB configuration.

External configuration refers to task configuration that cannot be adequately described by a CDB. The most conspicuous example of this are the graphics files developers edit via the

Reserved Table Description

domain Holds the configured SHARED and USER domains for the application.

object Holds the object or tag definitions.

type Holds the type for the RTDB segments within the kernel.

xref Holds the object cross-reference records.

CONFIGURATION ARCHITECTUREConfiguration Sessions


10

Co

nfig

uratio

n

Arch

itecture

Application Editor (APPEDIT). Currently, external configuration is implemented internally and support for it is not provided as part of CFGPAK.

Note: The one exception to this is the tag modification routines, where the renaming of a RTDB object or tag propagates to all affected drawings and logic scripts.

CONFIGURATION SESSIONS

Altering an application requires referencing both system as well as application files. As such, a configuration session is an attachment to a given FactoryLink system (FLINK) and a given FactoryLink application (FLAPP). From the FLINK, the CFGPAK obtains the definitions for the configurable tasks declared in the various attribute catalogs (AC), key files, and include files. From the FLAPP, the CFGPAK attaches to the actual CDBs that contain the configuration data.

The main focus of CFGPAK users is to alter task CDBs. However, session-level overhead must be processed prior to manipulating task configuration. Namely, the caller needs to navigate through the available configurable options to locate the task(s) of interest. The session facilitates this.

When establishing a configuration session, the session first determines what tasks are available for configuration. Since the Attribute Catalog (AC) defines the structure of a task CDB, the presence of an AC file within the session’s FLINK of an AC ultimately determines whether a task can be configured. However, the presence alone does not determine whether the session will see an AC.

When establishing a configuration session, the session determines AC availability via file: {FLINK}/ac/ac2ct.map. Among other purposes, this map cross-references a CDB to the AC that defines it. The map file is generated during the system installation, and its contents are derived from the union of all AC entries enumerated in the various titles files located in the {FLINK}/ac directory.

A TITLES file is a text file containing a list of AC files. The TITLES file FLCM uses to build its main menu list is located at {FLINK}/ac/titles. All AC files listed in the TITLES file must exist in the {FLINK}/ac directory. If an AC file does not exist, the titles entry is ignored, because FLCM assumes the absent AC file is for an option that has not been purchased.

CONFIGURATION ARCHITECTUREConfiguration Sessions


•

•

•

•

In the preceding figure, the TITLES file references AC file sys.ac, which in turn references the configuration CDB named SYS. While this may seem fairly straight forward, it is a common failure point where CFGPAK fails to locate its target CDB definition.

Common failure scenarios are

• An AC file is not referenced within the TITLES file and is not included in the AC-to-CT map generation process.

• An AC file is referenced within the TITLES file is missing from the FactoryLink system. Once again, CFGPAK ignores any entries for absent AC files.

• An AC file entry is missing from the AC-to-CT map file but is in the TITLES file. This means the TITLES file was updated after the last time the map file was updated.

sys.ac

itimer.ac

etimer.ac

CT "sys" , "sys" , "System Configuration Information"

FIELD. . .. . .

END

AC File (SYS.AC)Titles File

Titles file to AC to CDB relationship

CONFIGURATION ARCHITECTUREData Structure Hierarchy


10

Co

nfig

uratio

n

Arch

itecture

DATA STRUCTURE HIERARCHY

The data structure hierarchy is best conveyed by defining who the players are and how they interrelate. The data structures are:

The following graph depicts how these structures are linked to each other. The library services provide entry points your CFGPAK program can navigate through this hierarchy with and obtain the desired handle.

Data Structure Description

flCfgSess Configuration session handle.

flCfgAC Attributes catalog handle.

flCfgCDB Configuration database (CDB) handle.

flCfgDom Configuration database domain field handle.

flCfgSel Configuration database select field handle.

flCfgSeq Configuration database sequence field handle.

flCfgFld Configuration database data field handle.

Data Structure Hierarchy

CONFIGURATION ARCHITECTUREData Structure Hierarchy


•

•

•

•


• • • •

11

Co

nfig

PA

K L

ibrary

Services

Chapter 11

Configuration PAK Library Services

This chapter describes the general purpose and usage for the services found within CFGPAK. Detailed information regarding these functions can be found in the API reference guide. This chapter gives an overview of the following:

• Configuration Session API (flCfgSess)

• Attributes Catalog API (flCfgAC)

• Configuration Database API (flCfgCDB, flCfgSel, flCfgFld)

• Object Database API (flCfgObj, flCfgTag)

• Exception Handling

To illustrate the usage of each service, a thread of constructing a configuration utility for the FactoryLink PAK Skeleton task runs though this chapter. When the PAK option is installed into your FactoryLink system, the source/support files for the Skeleton task are placed in directory {FLINK}/src/examples/skeleton where {FLINK} is the location of the FactoryLink system.

CONFIGURATION PAK LIBRARY SERVICESConfiguration Session API


•

•

•

•

CONFIGURATION SESSION API

A configuration session provides the environment applications are modified through. Function flCfgSess_open( ) requires two inputs to open a session: the FactoryLink system directory {FLINK} and the application directory {FLAPP}. Upon successfully accessing system files in the given {FLINK} and {FLAPP}, flCfgSess_open( ) returns a session handle.

Similar to FLCM, the application must exist in order to open a session. Opening a session will not create an application.

Once a session is open, the next step towards accessing a configuration database is to locate its schema definition. Since attribute catalogs (ACs) contain these definitions, the AC associated with the target task needs to be located. To locate a particular AC, use functions flCfgSess_num_ac( ) and flCfgSess_nth_ac( ) to iterate through all ACs known to the session.

After the program completes accessing an application configuration, it should close its session. Closing the session flushes all disk buffers, closes all open databases files, and releases the memory attached to the session.

API Call Description

flCfgSess_open Opens/creates a configuration session.

flCfgSess_close Closes/destroys a configuration session.

flCfgSess_num_ac Gets the number of ACs within the session’s FLINK.

flCfgSess_nth_ac Gets/loads an attribute catalog (AC).



11

Co

nfig

PA

K L

ibrary

Services

Code Sample: Open/Close Session

int main(int argc, char *argv[])

{

flCfgSess *sess;

int rv;

/* Open a session - specify target FLINK & FLAPP */

rv = flCfgSess_open(getenv("FLINK"), getenv("FLAPP"), &sess);

if (rv != FLCFG_E_GOOD)

{

printf("Error(%d): unable to open edit session\n", rv);

return 1;

}

....

. Operate on session handler

....

/* Close the session and exit */

flCfgSess_close(&sess);

return 0;

}

The program seeks out a particular AC after opening a session. In the case of the Skeleton task, the program searches through the ACs known to the session for the one associated with task SKEL.



•

•

•

•Code Sample: Locating an AC

{

flCfgSess *sess;

flCfgAC *cfgacp;

flCfgCDB *cfgcdbp;

int k, j;

int rv;

....

. Open session “sess”

....

/* find the AC for the skeleton task */

cfgacp = NULL;

for (k = 0; k < flCfgSess_num_ac(sess); k++)

{

/* First, get a handle to an AC within the FLINK */

flCfgSess_nth_ac(sess, k, &cfgacp);

if (stricmp(flCfgAC_get_task(cfgacp), "SKEL") == 0) break;

cfgacp = NULL;

}

if (cfgacp == NULL)

{

printf("Cannot find skeleton task AC\n");


return 1;

}

/* Print out AC header information */

printf("AC :%s(%s) - %s\n",

CONFIGURATION PAK LIBRARY SERVICESAttribute Catalog API


11

Co

nfig

PA

K L

ibrary

Services

flCfgAC_get_task(cfgacp),

flCfgAC_get_filename(cfgacp),

flCfgAC_get_title(cfgacp));

....

. Continue processing

....

If the search for an AC fails, there are two likely causes. One is the AC file is not listed in the text file: {FLINK}\ac\titles. If not, append an entry for the AC file to the TITLES file. The other failure point is an entry for the AC file is missing from file: {FLINK}\ac\ac2ct.map. If so, type and execute “acctmgr -c -d” at the system command prompt. This utility rebuilds the AC-to-CT mapping for all AC files referenced within the various FactoryLink TITLES files.

ATTRIBUTE CATALOG API

Attribute Catalogs contain descriptions (or schemas) of one or more configuration databases (CDB) utilized by a particular task. As such, the AC structure also serves as a header to the individual table definitions. Information about the AC file is available via access functions flCfgAC_get_filename( ), flCfgAC_get_task( ), and flCfgAC_get_title( ).

What is an Attributes Catalog (AC)

As a header, the AC provides access to the top level configuration databases described within it. Often times, these top-level CDBs maintain a one-to-many binding with other, lower-level configuration databases. In such a case, data in one row of a header CDB may point towards


flCfgAC_get_filename Gets AC file name.

flCfgAC_get_task Gets AC associated task.

flCfgAC_open_cdbs Opens/creates AC configuration databases.

flCfgAC_close_cdbs Closes configuration databases defined within an AC.

flCfgAC_get_title Gets AC title.

flCfgAC_num_hdrcdb Gets number of ACs within the session FLINK.

flCfgAC_nth_hdrcdb Gets/loads an Attribute Catalog.



•

•

•

•multiple, related entries in another CDB. The Skeleton task AC illustrates this.

Code Sample: The Skeleton Task AC

* Attribute Catalog for Skeleton Task

TASK "SKEL", "Skeleton FL Task" * Task name and Title


CT "skeltags", "skeltags", "Tag List"

EDIT DEFAULT * Default Editing

VALIDATE DEFAULT * Default validation

PANEL "", 100, 100, 700, 500 * Initial position

FIELD "TAG", "TAG", 48, 0, "", "", 0, 0, ""

HEADING "Tag Name", 96

DOMAIN "DOMAIN", 8

SELECT "TABLE_NAME", 16 * Primary Key

SEQ "TABLE_NBR", 10 * Sequence Number

INDEX "skeltags", "DOMAIN+TABLE_NAME+TABLE_NBR", 34 *Index file,key

END


CT "skeltrig", "skeltrig", "Trigger Tags"

EDIT DEFAULT * Default Editing

VALIDATE DEFAUL * Default validation

PANEL "", 200, 0, 700, 500 * Initial position

FIELD "TRIGGER", "TAG", 16, 0, "TYPED", "DIGITAL", 0,

HEADING "Trigger Tag", 96

FIELD "TABLE_NAME", "CHARACTER", 16, 0, "", "", 0, 0, ""

HEADING "Table Name", 96

RELATE "skeltags", "TABLE_NAME", "skeltags"

DOMAIN "DOMAIN", 8

SEQ "TABLE_NBR", 10 * Sequence Number

INDEX "skeltrig", "DOMAIN+TABLE_NBR", 18 * Index file, key

END



11

Co

nfig

PA

K L

ibrary

Services

The preceding AC defines one header CDB named skeltrig. It is related to another CDB named skeltags via the field TABLE_NAME. In other words, for every row within CDB skeltrig, there will be zero or more rows in CDB skeltags with that same value in its TABLE_NAME field.

Note: Be aware that this is not the complete story since a row’s domain is also part of the relation. However, this topic is better left till when discussing the flCfgCDB( ) API.

Accessing CDBs Defined Within an AC

When the desired AC has been located, the configuration databases defined by that AC must be opened in order to access their schemas and value contents. Function flCfgAC_open_cdbs( ) opens, and optionally creates the CDB files if they do not yet exist, all databases defined by the given AC.

Code Sample: Opening an AC’s CDBs

flCfgAC *cfgacp;

flCfgCDB *cfgcdbp;

int k, j;

int rv;

....

. Open session “sess” and locate the SKEL AC

....

/* Open/create the tables defined within the SKEL AC */

if ((rv = flCfgAC_open_cdbs(cfgacp, 1)) != FLCFG_E_GOOD)

{

printf("Error(%d): unable to open SKELETON tables\n", rv);


return 1;

}

....

. Process the CDB

....

flCfgAC_close_cdbs(cfgacp);

....



•

•

•

•. Continue processing

....

Functions flCfgAC_num_hdrcdb( ) and flCfgAC_nth_hdrcdb( ) allow the caller to step through the top-level CDBs attached to the given AC. If the case of the skeleton task, the hdrcdb count would be 1, the skeltrig database.

Code Sample: Stepping through an AC’s top-level CDBs

....

. Have obtained AC handle “cfgacp” the session

....

/* Interrogate the SKELETON configuration definition */

for (j = 0; j < flCfgAC_num_hdrcdb(cfgacp); j++)

{

flCfgAC_nth_hdrcdb(cfgacp, j, &cfgcdbp);

printf("\tCDB: %s - %s\n",

flCfgCDB_get_name(cfgcdbp),

flCfgCDB_get_title(cfgcdbp));

....

. Do something w/ the “hdrcdb”

....

}

CONFIGURATION PAK LIBRARY SERVICESConfiguration Database API


11

Co

nfig

PA

K L

ibrary

Services

CONFIGURATION DATABASE API

Up to this point, most of the work has been navigating through the application to locate the configuration databases (CDB) to be accessed. Next comes manipulation of the CDB schemas and contents via the CDB API. At the top level are access functions to get the CDB name and title. Beyond that, things get more involved.

Interrogating a CDB Schema

The schema of a CDB is split internally into four categories:

• Domain field

• Select fields

• Sequence field

• Data fields

Functions are provided that return handles to these components of the CDB’s schema. These functions are:


flCfgCDB_get_name Gets the name of the configuration database (CDB).

flCfgCDB_get_title Gets CDB title.


flCfgCDB_get_domfld Gets CDB domain field.

flCfgCDB_num_selfld Gets CDB number of select fields.

flCfgCDB_nth_selfld Gets handle to nth select field.

flCfgCDB_find_selfld Gets handle to select field with the given name.

flCfgCDB_get_seqfld Gets CDB sequence field.

flCfgCDB_num_fld Gets CDB number of fields.

flCfgCDB_nth_fld Gets handle to nth field.

flCfgCDB_find_fld Gets handle to field with the given name.



•

•

•

•• flCfgCDB_get_domfld( )

• flCfgCDB_nth_selfld( )

• flCfgCDB_get_seqfld( )

• flCfgCDB_nth_fld( )

We provide name-based search functions for component types where multiple fields may apply.

Given a field handle, information about the field, such as name, title, or size, can be retrieved. The handle is also used for setting field values when reading and writing CDB records. The functions that manipulate the four components of a CDB are as follows:

Domain Field API

Most CDBs associate their records with a domain. If a domain field is present, it is always considered part of the selection criteria (see section “Reading Configuration from a CDB”).

Select Field API

Selection fields exist for CDBs whose records depend on the values of another table (API refers to these as relate CDBs). There may be many select fields, as many as required to uniquely bind the CDBs records to an individual record in the header table.

API Calls Description

flCfgDom_get_name Gets domain field name.

flCfgDom_get_size Gets domain field size.

flCfgDom_get_value Gets domain value for selected row.

flCfgDom_set_value Sets domain value for next selection or write.


flCfgSel_get_name Gets select field name.

flCfgSel_get_size Gets select field size.

flCfgSel_get_value Gets select value for selected row.

flCfgSel_set_value Sets select value for next selection or write.



11

Co

nfig

PA

K L

ibrary

Services

Sequence Field API

Sequence fields maintain the order of row entry. Maintaining this order allows FLCM to show CDB contents in a consistent manner, as opposed to potentially showing a different ordering of rows between editing sessions. Almost all tables have a sequence field.

Field (Configuration Data) API

All CDBs have data fields. Data fields hold the task configuration information, as opposed to the other fields that mainly serve to organize and/or sort the data.

To illustrate, consider the following function that prints the schema for a given handle to a CDB to stdout . This example shows how to go through the fields that make up a table as well as how to obtain the properties of each field.

Code Sample: Exploring a CDB schema

static void dump_cdb_schema(flCfgCDB *cfgcdbp, int indent)

{

flCfgDom *cfgdomp;

flCfgSel *cfgselp;

flCfgSeq *cfgseqp;


flCfgSeq_get_name Gets sequence field name.

flCfgSeq_get_size Gets sequence field size.

flCfgSeq_get_value Gets sequence value for selected row.

flCfgSeq_set_value Sets sequence value for next selection or write.


flCfgDom_get_name Gets domain field name.

flCfgDom_get_size Gets domain field size.

flCfgDom_get_value Gets domain value for selected row.

flCfgDom_set_value Sets domain value for next selection or write.



•

•

•

•flCfgFld *cfgfldp;

int m, n;

flCfgCDB_get_domfld(cfgcdbp, &cfgdomp);

if (cfgdomp != NULL)

{

for (n = 0; n < indent; n++)

printf("\t");

printf("Domain: %s(%d) - Domain Field\n",

flCfgDom_get_name(cfgdomp),

flCfgDom_get_size(cfgdomp));

}

for (m = 0; m < flCfgCDB_num_selfld(cfgcdbp); m++)

{

flCfgCDB_nth_selfld(cfgcdbp, m, &cfgselp);


printf("\t");

printf("Select: %s(%d) - %s\n",

flCfgSel_get_name(cfgselp),

flCfgSel_get_size(cfgselp),

flCfgSel_get_title(cfgselp));

}

flCfgCDB_get_seqfld(cfgcdbp, &cfgseqp);

if (cfgseqp != NULL)

{


printf("\t");



11

Co

nfig

PA

K L

ibrary

Services

printf("Sequence: %s(%d) - Sequence Field\n",

flCfgSeq_get_name(cfgseqp),

flCfgSeq_get_size(cfgseqp));

}

for (m = 0; m < flCfgCDB_num_fld(cfgcdbp); m++)

{

flCfgCDB_nth_fld(cfgcdbp, m, &cfgfldp);


printf("\t");

printf("Field: %s(%d) - %s\n",

flCfgFld_get_name(cfgfldp),

flCfgFld_get_size(cfgfldp),

flCfgFld_get_title(cfgfldp));

}

}



•

•

•

•Reading Configuration from a CDB

At its simplest usage, reading data is a four-step sequence involving four functions:

1. Function flCfgCDB_select_begin( ) initiates the selection criteria and table locks.

2. A call to function flCfgCDB_select_first( ) takes the selection criteria and positions the record pointer on the first row that matches that criteria.

3. Function flCfgCDB_select_next( ) is called as many times as needed to visit all rows that match the selection criteria.

4. Finally, a call to flCfgCDB_select_end( ) releases all locks and resources held on behalf of the selection.

Given the above, an overview of how selection criteria works within FLCM and the CFGPAK is needed. All CDBs have a primary index (it is the first INDEX listed within an AC CT definition). This index equates to the selection criteria. For header CDBs, the most common index expression is “DOMAIN+SEQ”. Ignoring sequence number (SEQ) for now, selections against header CDBs are for all rows within a particular domain.

To illustrate, consider the following function dump_cdb_contents( ) that prints the contents of a table to stdout, and all tables related to it, for a particular domain.


flCfgCDB_ select_begin Begins a select of data from CDB.

flCfgCDB_ select_criteria Reads header’s select values into the relate CDB.

flCfgCDB_ select_current Reads values of currently selected row.

flCfgCDB_ select_first Moves first row that meets selection criteria.

flCfgCDB_ select_next Moves next row that meets selection criteria.

flCfgCDB_ select_rowno Moves to row with the given number.

flCfgCDB_ select_end Ends selection of data from CDB.

flCfgCDB_ num_relatecdb Gets number of CDBs related on the given CDB.

flCfgCDB_ nth_relatecdb Gets handle of nth related CDB.

flCfgCDB_rowno Gets number for currently selected row.



11

Co

nfig

PA

K L

ibrary

Services

Code Sample: Reading the CDB’s contents

static void dump_cdb_contents(flCfgCDB *cfgcdbp, char *domain, int indent)

{

char fldbuf[256];

flCfgCDB *relcdbp;

flCfgDom *cfgdomp;

flCfgSel *cfgselp;

flCfgFld *cfgfldp;

int rv;

int m, n;

memset(fldbuf, 0, sizeof(fldbuf));

flCfgCDB_get_domfld(cfgcdbp, &cfgdomp);

<step 1> if ((rv = flCfgCDB_select_begin(cfgcdbp == FLCFG_E_GOOD)

{

if ((domain != NULL) && (cfgdomp != NULL))

<step 2a> flCfgDom_set_value(cfgdomp, domain);

<step 2b> rv = flCfgCDB_select_first(cfgcdbp);

}

while (rv == FLCFG_E_GOOD)

{

....

. Print out current record (use flCfgFld_get_value() for each field).

....

for (m = 0; m < flCfgCDB_num_relatecdb(cfgcdbp); m++)

{

flCfgCDB_nth_relatecdb(cfgcdbp, m, &relcdbp);

dump_cdb_contents(relcdbp, NULL, indent+1);

}



•

•

•

•<step 3> rv = flCfgCDB_select_next(cfgcdbp);

}

<step 4> flCfgCDB_select_end(cfgcdbp);

}

In the code sample above , the CDB handle and selection domain are passed into the function. The steps in this procedure include:

1 Attach to the table by beginning the selection.

2 Once the selection has begun, adjust the selection criteria for the given domain and then position on the first record matching this criteria.

3 Step through all rows tied to that domain.

4 Once all rows are exhausted, the selection is ended.

In the previous code sample, the segment

for (m = 0; m < flCfgCDB_num_relatecdb(cfgcdbp); m++)

{

flCfgCDB_nth_relatecdb(cfgcdbp, m, &relcdbp);

dump_cdb_contents(relcdbp, NULL, indent+1);

}

illustrates accessing data in another CDB that relates to the current row of the CDB being processed. In the example, the related CDBs are iterated through, and for each, the dump function is called recursively. What is not obvious here is that the selection criteria is being implicitly defined for these related CDBs. When the selection for a related CDB is begun, the select field values are set equal to the field values found in the header CDB. This is why NULL is being passed as the domain value. When dumping related CDBs, use the domain value of the header row.



11

Co

nfig

PA

K L

ibrary

Services

Writing Configuration to a CDB

Writing to a CDB almost equates to reversing the function call order of the selection (reading) process. Prior to invoking the insert, the values associated with the field handles must be set to the values to be inserted. These values are referenced by the writer functions such as function flCfgCDB_row_insert( ) when it inserts a row.

Inserting a Row into a CDB

When a row is inserted, the values specified for the data fields are validated. The validation performed is equivalent to the validation performed by FLCM. As with FLCM, any tags referenced by the newly inserted row will have a corresponding entry made in the cross-reference databases.

The sequence field has a unique property when a row is being inserted. Since the sequence number exists to sort records according to their entry order, the field itself is generally hidden from the user. As such, its value is automatically generated by FLCM. In keeping with this theme, the insert routine will automatically assign the next appropriate sequence value to the given row when the sequence value is set to zero. Unless your program has a need to sort records in a particular order, use this auto-assignment mechanism as it will prevent the inappropriate assignment of the same sequence number to two records.

Code Sample: Writing a Row into a Header CDB

static int skel_insert_table(flCfgCDB *skelp, char *dom, char *tbl, char *trig)

{

flCfgDom *domfldp;

flCfgSeq *seqfldp;

flCfgFld *tblfldp;

flCfgFld *trigfldp;

flCfgValErr valerr;

int rv;


flCfgCDB_row_insert Inserts a row.

flCfgCDB_row_validate Validates set entries for a row.

flCfgCDB_select_delete Deletes currently selected row.

flCfgCDB_select_update Updates currently selected row.



•

•

•

•/* Locate the needed table components */

if ((flCfgCDB_get_seqfld(skelp, &seqfldp) != FLCFG_E_GOOD)

|| (flCfgCDB_find_fld(skelp,"TABLE_NAME",&tblfldp) != FLCFG_E_GOOD)

|| (flCfgCDB_find_fld(skelp, "TRIGGER", &trigfldp) != FLCFG_E_GOOD)

|| (flCfgCDB_get_domfld(skelp, &domfldp) != FLCFG_E_GOOD))

{

return RV_ERROR;

}

flCfgDom_set_value(domfldp, dom);

flCfgSeq_set_value(seqfldp, 0); /* 0 means to autoset the seq # */

flCfgFld_set_value(tblfldp, tbl);

flCfgFld_set_value(trigfldp, trig);

rv = flCfgCDB_row_insert(skelp, &valerr);

switch (rv)

{

case FLCFG_E_GOOD:

rv = RV_GOOD;

break;

case FLCFG_E_VALERR:

printf("Validation Error: %s(%s): %s\n",

flCfgValErr_get_fldname(&valerr),

flCfgValErr_get_fldvalue(&valerr),

flCfgValErr_get_valmsg(&valerr));

rv = RV_ERROR;

break;

default:

printf("Insert error: %d\n", rv);

rv = RV_ERROR;

break;

}



11

Co

nfig

PA

K L

ibrary

Services

return rv;

}

When inserting into a relate CDB, the values for the select fields must be set as well. While this can be explicitly done by calling flCfgSel_set_value( ), it is best to use the values within the relations. This guarantees records will not be inserted in relate CDBs that have no owning row in the header CDB.

For example, if tag A_SEC is inserted into table SKELTAGS with an association to skeltrig table TBL_A and no entry for table TBL_A exists in the skeltrig CDB, the inserted row will be an orphan.

Function flCfgCDB_select_criteria( ) loads the domain and relate values for the currently selection record of its header CDB(s) into the given CDB handle. In the following code sample, the row insertion into CDB SKELTAG has its domain and table name fields set the value of the row currently selected in the SKELTRIG CDB. As such, the row is guaranteed not to be an orphan.

Code Sample: Writing a Row into a Relate CDB

static int skeltag_insert_row(flCfgCDB *skeltagp, char *tag)

{

flCfgFld *fldp;

flCfgValErr valerr;

int rv;

/* Get the handle to the tag field */

i f (flCfgCDB_find_fld(skeltagp, "TAG", &fldp) != FLCFG_E_GOOD)

return RV_ERROR;

/*

* Load in the selection values for the current row of SKELTAG’s

* header CDB (SKELTRIG)

*/

if (flCfgCDB_select_criteria(skeltagp) != FLCFG_E_GOOD)

return RV_ERROR;

/* Set the tag value and insert the row */



•

•

•

•flCfgFld_set_value(fldp, tag);

rv = flCfgCDB_row_insert(skeltagp, &valerr);

switch (rv)

{

case FLCFG_E_GOOD:

rv = RV_GOOD;

break;


printf("Validation Error: %s(%s = %s): %s\n",

flCfgValErr_get_ctname(&valerr),




rv = RV_ERROR;

break;

default:


rv = RV_ERROR;

break;

}

return rv;

}

Updating a Row Within a CDB

Row updates and selections are closely coupled operations. In order for a row to be updated, it must first be selected. In other words, once the target row is selected, a call to function flCfgCDB_select_update( ) modifies that row with the given values set within the CDB handle. Of note here is an update may affect more the currently selected row. If one or more fields of the update are related upon by another CDB, the update propagates to these relate CDBs. This propagation preserves the relation between the updated row and those rows related upon it.

In all cases, the affected cross-reference database entries are updated accordingly (additions, deletions, and/or modifications).



11

Co

nfig

PA

K L

ibrary

Services

Consider the following code sample. Once the record for the given domain and table name has been selected, the new values are set within the skeltrig CDB handle and the update function invoked. If only the trigger field value is different, then the update stops at modifying the selected row. However, if the table name field value is different, all records in the related skeltags CDB are also updated with the new table name.

For example, if the table name is switched from T1 to T2, then all rows in the skeltags CDB whose table name value is T1 becomes T2.

Code Sample: Updating a CDB Row

static int skel_upd_table(flCfgCDB *skelp, char *dom, char *tbl,

char *newtbl, char *newtrig)

{

flCfgDom *domfldp;

flCfgFld *tblfldp;

flCfgFld *trigfldp;

char *tblval;

int tblsize;

int found;

int rv;

/* Locate the needed table components */

if ((flCfgCDB_find_fld(skelp, "TABLE_NAME", &tblfldp) !=

FLCFG_E_GOOD)

|| (flCfgCDB_find_fld(skelp, "TRIGGER", &trigfldp) != FLCFG_E_GOOD)


{

return RV_ERROR;

}

....

. Select the record that matches the given domain and table name (params ‘dom’+‘tbl’)

....

/* If the requested table exists, update it. */

if (found)

{



•

•

•

•flCfgValErr valerr;

flCfgFld_set_value(tblfldp, newtbl);

flCfgFld_set_value(trigfldp, newtrig);

rv = flCfgCDB_select_update(skelp, &valerr);

switch (rv)

{

case FLCFG_E_GOOD:

rv = RV_GOOD;

break;


printf("Validation Error: %s(fld=%s; val=%s): %s\n",

flCfgValErr_get_ctname(&valerr),




rv = RV_ERROR;

break;

default:

printf("Update error: %d\n", rv);

rv = RV_ERROR;

break;

}

}

else

{

rv = RV_ERROR;

}

....

. End the open selection held open for the update: flCfgCDB_select_end(skelp);

....

return RV_GOOD;



11

Co

nfig

PA

K L

ibrary

Services

}

Deleting a Row from a CDB

As with row updates, row deletion and selection are coupled operations. For a row to be deleted, it must first be selected. Function flCfgCDB_select_delete( ) removes both the currently selected row and all rows in the relate CDBs tied to that row. Also, any tags referenced within the deleted row(s) have their corresponding cross-reference database entries removed.

Be aware that deleting a row positions the active selection onto the next row that meets the selection criteria. As such, function flCfgCDB_select_current( ) is called to iterate through a selection after a delete as opposed to the standard call to function flCfgCDB_select_next( ).

Consider the following code sample. It begins by selecting all tables associated with a given domain. Once the selection has begun, it iterates through all the records, searching for the given table name. Upon finding the target record, the procedure deletes the record and proceeds onto the next record by calling function flCfgCDB_select_current( ) because the delete call has already positioned it onto the next record.

Code Sample: Deleting a Row from a CDB

static int skel_delete_table(flCfgCDB *skelp, char *domain, char *tbl)

{

flCfgDom *domfldp;

flCfgFld *tblfldp;

char *tblval;

int tblsize;

int found;

int rv;

/* Locate the needed table components */

if ((flCfgCDB_find_fld(skelp,"TABLE_NAME",&tblfldp) != FLCFG_E_GOOD)


{

return RV_ERROR;

}

tblsize = flCfgFld_get_size(tblfldp)+1;

if ((tblval = (char*) malloc(tblsize)) == NULL)



•

•

•

•return RV_ERROR;

if ((rv = flCfgCDB_select_begin(skelp)) == FLCFG_E_GOOD)

{

flCfgDom_set_value(domfldp, domain);

rv = flCfgCDB_select_first(skelp);

}

found = 0;


{

flCfgFld_get_value(tblfldp, tblval, tblsize);

if (strcmp(tblval, tbl) == 0)

{

flCfgCDB_select_delete(skelp);

rv = flCfgCDB_select_current(skelp);

}

else

{

rv = flCfgCDB_select_next(skelp);

}

}

flCfgCDB_select_end(skelp);

free(tblval);

return RV_GOOD;

}



11

Co

nfig

PA

K L

ibrary

Services

Multi-user Access to a CDB

For the general case, the CFGPAK automatically handles the multi-user considerations that arise when manipulating the application’s CDBs. However, cases exist where the locking and releasing of one or more CDBs need to be explicitly managed by the CFGPAK program. To illustrate, consider the following code sample.

Code Sample: CDB Locking to Support Selection by Row Number

flCfgCDB_lock(cfgcdbp, 0);

if ((rv = flCfgCDB_select_begin(cfgcdbp)) != FLCFG_E_GOOD)

return;

if (flCfgCDB_select_first(cfgcdbp) == FLCFG_E_GOOD)

flCfgCDB_rowno(cfgcdbp, &rowno);

flCfgCDB_select_end(cfgcdbp);

....

. Process <Block A> - Other processes may access CDB ‘cfgcdbp’.

....

if ((rv = flCfgCDB_select_begin(cfgcdbp)) == FLCFG_E_GOOD)

rv = flCfgCDB_select_rowno(cfgcdbp, rowno);

flCfgCDB_select_end(cfgcdbp);

flCfgCDB_unlock(cfgcdbp, 0);

In the preceding sequence, CDB locking prevents the row number from being invalidated by the operations of another process. If the lock was not held over the life of both selections, another process could be deleting and adding rows to the CDB during the time spent in <Block A>.

Consider the following sequence of events that may occur in the absence of a lock on the CDB.


flCfgCDB_lock Establishes a read/write lock on a CDB.

flCfgCDB_unlock Releases lock held on CDB.



•

•

•

•1. The CFGPAK program begins executing the code sample and remembers row number 5.

The CFGPAK program then enters the time-consuming operation represented as <Block A>.

2. Another user starts FLCM, selects the same CDB, and deletes the row tied to number 5. The user then adds a new row, which FLCM assigns number 5 since it is now available.

3. The CFGPAK program returns from <Block A> and selects row 5.

The above sequence represents a failure, since the row selected by the CFGPAK program is not the row it should be accessing. That row had been deleted and replaced by FLCM.

Therefore, locking prevents other processes from changing the state of CDB your CFGPAK program is operating on. However, be aware no other processes can access the CDB as long as the lock is held; therefore, the lock should be held as long as required to protect the entire transaction but released immediately upon completion.

CONFIGURATION PAK LIBRARY SERVICESObject Database API


11

Co

nfig

PA

K L

ibrary

Services

OBJECT DATABASE API

One of the application’s reserved configuration databases, the object database, holds all the tag definitions. The Object CDB API, which is essentially just another CDB, inherits most of its entry points from the standard CDB API.

However, the Object CDB is a reserved table. As such, it is best the code does not assume anything about the name or contents of the fields found within this table since these could change in the future. Also, numerous, system integrity rules apply to the manipulation of records found therein. In other words, keep with the flCfgObj API when accessing the object database as opposed to using the lower-level CDB functions.

Locating the Object CDB Handle

The first step in accessing the object database is to get a handle to its CDB. This handle is obtained via function flCfgObj_get_cdb( ). Given a session handle, this function returns the handle to that session’s object CDB.

The object CDB handle is a standard CDB handle. Any functions used to interrogate the schema definitions, as described in the CDB API chapter, are applicable.


flCfgObj_add Creates a tag definition.

flCfgObj_get_cdb Obtains session object CDB handle.

flCfgObj_select_begin Initiates selection against object CDB.

flCfgObj_select_current Reads currently selected tag definition.

flCfgObj_select_delete Deletes currently selected tag definition.

flCfgObj_select_end Ends selection against object CDB.

flCfgObj_select_first Reads first tag definition for given tag name.

flCfgObj_select_name Reads tag definition for given tag name.

flCfgObj_select_next Reads next tag definition in object CDB.

flCfgObj_select_update Updates currently selected tag definition.



•

•

•

•Tag Definition API

The transfer of definitions to and from the Object CDB API is conducted via a tag definition data structure. As such, functions have been provided to create, manipulate, and destroy this structure.


flCfgTag_create Allocates tag definition.

flCfgTag_clear_attrvals Clears all attribute values within tag definition.

flCfgTag_destroy De-allocates tag definition.

flCfgTag_get_attrval Gets value of tag definition attribute.

flCfgTag_get_attrvalp Gets pointer to value of tag definition attribute.

flCfgTag_set_attrval Sets value of tag definitions attribute.



11

Co

nfig

PA

K L

ibrary

Services

Tag definitions consist of many attributes, such as the tag name, its domain and its dimensions. The get and set functions provide access to all of these attributes. Instead of providing a separate access function for each function, each attribute is assigned an ID, which the caller passes into the get and set functions. The requested attribute value is then returned as a string (or a string is passed in when setting an attribute value).

Reading Tag Definitions

In general, selecting tag definitions differs little from selecting rows from any other table since the four step sequence of selection begin, first, next, and end applies to the object table as well.

All selections begin with a call to function flCfgObj_select_begin( ). A subsequent call to flCfgObj_select_first( ) selects the object CDB’s first tag definition. To select a particular tag, substitute a call to flCfgObj_select_name( ) for flCfgObj_select_first( ). This selects the object definition for the given name or the definition for the object, which falls alphabetically immediately after the given name should the target name not exist.

In either case, subsequent calls to flCfgObj_select_next( ) steps the caller through all remaining tag definitions. Once the selection is complete, a call to function flCfgObj_select_end( ) closes the operation.

Code Sample: Printing the Name of All Tags

static void dump_object(flCfgSess *sess)

{

Attribute ID Description

FLCFGTAG_ATTR_NAME Tag name

FLCFGTAG_ATTR_DOMAIN Tag domain

FLCFGTAG_ATTR_DIMEN Tag dimension maximums

FLCFGTAG_ATTR_TYPE Tag type

FLCFGTAG_ATTR_DESCR Tag description

FLCFGTAG_ATTR_DFLTVAL Tag default value

FLCFGTAG_ATTR_MSGLEN Tag message length

FLCFGTAG_ATTR_PERWHEN Tag persistence storage frequency

FLCFGTAG_ATTR_CHGBITS Tag persistence change bit initialization



•

•

•

•flCfgTag *tagp;

flCfgCDB *objp;

char *tagname;

int rv;

if (flCfgObj_get_cdb(sess, &objp) != FLCFG_E_GOOD)

{

printf("Cannot find object CDB\n");

return;

}

if (flCfgTag_create(&tagp) != FLCFG_E_GOOD)

return;

if (flCfgObj_select_begin(objp) != FLCFG_E_GOOD)

return;

rv = flCfgObj_select_first(objp, tagp);


{

flCfgTag_get_attrvalp(tagp, FLCFGTAG_ATTR_NAME, &tagname);

printf("\t%s\n", tagname);

rv = flCfgObj_select_next(objp, tagp);

}

flCfgTag_destroy(&tagp);

flCfgObj_select_end(objp);

}

Writing Tag Definitions

Writing to the object CDB equates to adding, modifying, or deleting a tag definition.



11

Co

nfig

PA

K L

ibrary

Services

Adding a Tag Definition

Function flCfgObj_add( ) creates a new tag according to the tag definition structure passed into it. Validation of all aspects of the proposed definition is conducted prior to its actual insertion. Specifics regarding any validation errors are returned via the flCfgValErr structure.

A member tag (i.e., x.raw) can be created if

1. the structured tag exists (i.e., x)

and

2. the member tag’s proposed definition has the same dimensions and domain as the structured tag.

Code Sample: Adding a Tag Definition

....

. Previously create flCfgTag and flCfgValErr structures and locate the object CDB handle.

....

flCfgTag_set_attrval(tagp, FLCFGTAG_ATTR_NAME, name);

flCfgTag_set_attrval(tagp, FLCFGTAG_ATTR_DOMAIN, dom);

flCfgTag_set_attrval(tagp, FLCFGTAG_ATTR_TYPE, type);

rv = flCfgObj_add(objp, tagp, valerr);

switch (rv)

{

case FLCFG_E_GOOD:

rv = RV_GOOD;

break;



flCfgValErr_get_ctname(valerr),

flCfgValErr_get_fldname(valerr),

flCfgValErr_get_fldvalue(valerr),

flCfgValErr_get_valmsg(valerr));

rv = RV_ERROR;

break;



•

•

•

•default:


rv = RV_ERROR;

break;

}

....

. Subsequently destroy flCfgTag and flCfgValErr structures and continue work.

....

Updating a Tag Definition

Function flCfgObj_select_update( ) modifies a tag definition. As with updating a row in a CDB, the tag definition must be selected prior to the update call.

This appears straight forward, but it is not. On one hand, changing non-core attributes is no different than any other CDB update, since the change only affects the one row in the object database. On the other hand, changing a core attribute, namely its dimension, domain, name, or type, requires application wide modifications.

To illustrate the costs of changing an object’s core attributes, consider the effects of changing an object’s name. Changing an object’s name is expensive since every reference to that object must be physically updated. For example, if the reference to the object is within a task’s CDB, the row in the task CDB must be modified. Furthermore, if that object is referenced by a Math & Logic script (also known as a PRG), all references in the script must be located, altered and validated. This case raises ambiguous situations, such as what if the new object name conflicts with the script’s local variable. Drawing files are another problem area For example, if a template was used to form the object reference, a decision to either reject the new name or drop the template association needs to be made.

The point is that changing an object’s core attributes is prone to being rejected for a wide variety of reasons. Furthermore the operation may generate warnings that require the user to decide whether to commit or rollback the change, such as whether to change the tag name even though a Math & Logic script does not validate. To communicate errors and warnings between the internals of the flCfgObj_select_update( ) function and the invoking CFGPAK program, a series of OK-CANCEL boxes are requested via the message box callback (for more information, see function flCfg_set_msgbox_handler( )). The responses to these dialogs control what action the update takes.

Note: Member tag names cannot be a source or target name string for a tag rename. For example, y cannot be renamed to x.raw, nor can x.raw be renamed to y.



11

Co

nfig

PA

K L

ibrary

Services

Code Sample: Changing the Name of a Tag

....

. Previously create flCfgTag and flCfgValErr structures and locate the object CDB handle.

....


return RV_ERROR;

rv = flCfgObj_select_name(objp, tagname, tagp);

if (rv == FLCFG_E_GOOD)

{

flCfgTag_set_attrval(tagp, FLCFGTAG_ATTR_NAME, newname);

rv = flCfgObj_select_update(objp, tagp, valerr);

switch (rv)

{

case FLCFG_E_GOO

rv = RV_GOOD;

break;



flCfgValErr_get_ctname(valerr),

flCfgValErr_get_fldname(valerr),

flCfgValErr_get_fldvalue(valerr),

flCfgValErr_get_valmsg(valerr));

rv = RV_ERROR;

break;

default:

printf("Rename error: %d\n", rv);

rv = RV_ERROR;

break;

}

}

else



•

•

•

•{

printf("Unable to locate tag to rename: %s\n", tagname);

rv = RV_ERROR;

}


....

. Subsequently destroy flCfgTag and flCfgValErr structures and continue work.

....

Deleting a Tag Definition

Function flCfgObj_select_delete( ) deletes a tag definition. As with deleting a row from a CDB, the tag definition to delete must be selected prior to the delete call. Before the tag is deleted, the function verifies that no references to that tag exist. If references exist, the deletion is rejected.

Structured tags further constrain the behavior of this function. If the tag being deleted is structured with one or more member, there must not be any references to the member tags, or the deletion will be rejected (if tag x is structured with a member tag x.raw, then a reference to tag x.raw prevents tag x from being deleted). Similarly, if no references exist to the structured tag or its members, then the removal of the structured tag deletes the member tags.

Code Sample: Deleting a Tag Definition

....

. Previously create flCfgTag structure and locate the object CDB handle.

....


return RV_ERROR;

rv = flCfgObj_select_name(objp, tagname, tagp);

if (rv == FLCFG_E_GOOD)

rv = flCfgObj_select_delete(objp);

else

rv = RV_ERROR;



11

Co

nfig

PA

K L

ibrary

Services


....

. Subsequently destroy the flCfgTag structures and continue work.

....

CONFIGURATION PAK LIBRARY SERVICESException Handling API


•

•

•

•

EXCEPTION HANDLING API

CFGPAK reports exceptions with return codes; however, return values often lack sufficient precision to report why the call failed. Hence, additional information about a failure can be obtained via the exception hooks discussed in this chapter.

CFGPAK exception handling consists of the following components:

• Return Codes and Error Messages

• Validation Errors

Return Codes and Error Messages

Whenever a CFGPAK function fails, it returns an error code as to the cause of the failure. Exception codes to expect from a function call are listed within the function’s description in Chapter 13, “Configuration PAK API Reference Library.”



11

Co

nfig

PA

K L

ibrary

Services

CFGPAK Error Codes

Error Code Definition Value Description

FLCFG_E_GOOD -0 No error occurred.

FLCFG_E_INTERNAL -1 General failure indicator.

FLCFG_E_INVARG -2 Invalid argument passed to function.

FLCFG_E_MEMORY -3 Memory allocation.

FLCFG_E_MULTSESS -4 Attempt to open more than one session.

FLCFG_E_NOFILE -5 File/CDB not found.

FLCFG_E_NOACLOAD -6 AC not loaded prior to function call.

FLCFG_E_CDBCLOSED -7 Cannot access closed CDB.

FLCFG_E_ENDOFSEL -8 No more rows match selection criteria.

FLCFG_E_NOTFOUND -9 Cannot find the requested handle.

FLCFG_E_ISOPEN -10 Attempt to open an already open CDB.

FLCFG_E_ACLOAD -11 Error occurred loading or parsing AC file.

FLCFG_E_ACMAP -12 Error occurred loading or parsing AC2CT map file. Executing utility ACCTMGR may fix this.

FLCFG_E_APPOPEN -13 Cannot open application system CDBs.

FLCFG_E_BADRELATE -14 Cannot find table/field for select relation.

FLCFG_E_DBERROR -15 Internal physical database I/O failure.

FLCFG_E_DBLOCK -16 Unable to lock CDB.

FLCFG_E_VALERR -17 Validation error on insert/update.

FLCFG_E_SELBEGUN -18 Cannot perform operation when a selection on given CDB has already begun. The select must be ended first.

FLCFG_E_NOSELBGN -19 Operation requires a begin selection.



•

•

•

•

CFGPAK Error Messages

When internal errors and warnings are encountered, additional, textual messages may be written to stdout. These strings provide more detailed information regarding the failure than can be provided by an error code.

However, it is likely that sending output to stdout is inappropriate for the application utilizing CFGPAK. For example, a GUI program may re-direct these outputs to a message box. To that end, function flCfg_set_msgbox_handler( ) allows a callback function to be installed directs all message to the given function pointer.

Furthermore, for more exotic activities, input from the user is necessary to direct the lower level CFGPAK functions how to proceed.

Code Sample: Prototype for the Message Box Callback

typedef int (*FLCFG_MBH)(char *title, char *msg, int boxtype);

Once a callback handler is set, all error message are passed to it. The arguments consist of a title string, a message string, and a box type request. Message box type requests are:

FLCFG_E_NOSSEL1ST -20 Operation requires prior select of first row.

FLCFG_E_INVUPD -21 Relate CDBs cannot update domain/select fields.

FLCFG_E_RSVDTBL -22 Illegal operation for reserved table.

FLCFG_E_REFEXIST -23 Illegal request for references to object exists.

FLCFG_E_TAGEDIT -24 Error encountered during tag definition update.


flCfg_set_msgbox_handler Set function to direct error and warning messages.

Box Type ID Description

FLCFG_MBOX_OK Single button (OK) message box.

FLCFG_MBOX_OKCANCEL Dual button (OK & CANCEL) message box.

Error Code Definition Value Description



11

Co

nfig

PA

K L

ibrary

Services

The callback function should return the ID of the button pressed. The button IDs are:

If no message box callback is set, the default CFGPAK message box handler writes the title and message to stdout, and then returns FLCFG_MBID_OK for OK message boxes or FLCFG_MBID_CANCEL for OK-CANCEL message boxes.

Validation Error Reporting for Inserts and Updates

When inserting or updating a row, the values contained therein may not be legal. Legality is determined either by restrictions specified in the CDB definition within the AC file or by an external validation routine. Should the prospective value of a field fail to validate, the insert or update call returns an error. When a validation failure occurs, the validation error structure passed into the insert function is filled with details about the nature of the violation. This information includes the violated field name, the offending value, and a message stating what is wrong with the value.

For example, if a field is designated as a NUMBER type with a valid range of 0 to 100, an attempt to insert a row with the value of 256 will be rejected. In this case, the function returns code FLCFG_E_VALERR, and the validation error structure contains specifics about the failure.


FLCFG_MBID_OK Single button (OK) message box.

FLCFG_MBID_CANCEL Dual button (OK & CANCEL) message box.


flCfgValErr_create Creates validation error structure.

flCfgValErr_clear Clears validation error structure.

flCfgValErr_destroy Destroys validation error structure.

flCfgValErr_get_ctname Gets validation error CDB (CT) name.

flCfgValErr_get_ fldname Gets validation error field name.

flCfgValErr_get_fldvalue Gets validation error field value.

flCfgValErr_get_valmsg Gets validation error field message.



•

•

•

•


• • • •

12

Lib

rary Services

Chapter 12

The Configuration Database Active-X Component

The FactoryLink CFGPAK Active-X control (OCX) exposes the functions of the FactoryLink CFGPAK C library as methods and events accessible to OLE containers that support scripting, such as Microsoft’s Visual Basic.

To install and register the CFGPAK component and its DLLs, run the installation executable located at {FLINK}\flcfgocx\flcfgocx.exe. The target directory for the installation should be the FactoryLink directory itself.

THE CONFIGURATION DATABASE ACTIVE-X COMPONENTUsing the CFGPAK OCX


•

•

•

•

USING THE CFGPAK OCX

All CFGPAK OCX methods are exposed at the root level of the object. This allows the OCX interface to closely mirror the C API, save for minor adjustments to method names. The functionality of the OCX method and its associated C function is equivalent.

The mapping of C-function name to OCX method name is as follows:

C-Function Name OCX Method Nameflcfg. (method)

flCfgAC_close_cdbs AcCloseCdbs

flCfgAC_get_filename AcGetFilename

flCfgAC_get_task AcGetTask

flCfgAC_get_title AcGetTitle

flCfgAC_nth_hdrcdb AcNthHdrcdb

flCfgAC_num_hdrcdb AcNumHdrcdb

flCfgAC_open_cdbs AcOpenCdbs

flCfgCDB_find_fld CdbFindFld

flCfgCDB_find_selfld CdbFindSelfld

flCfgCDB_get_domfld CdbGetDomfld

flCfgCDB_get_name CdbGetName

flCfgCDB_get_seqfld CdbGetSeqfld

flCfgCDB_get_title CdbGetTitle

flCfgCDB_lock CdbLock

flCfgCDB_nth_fld CdbNthFld

flCfgCDB_nth_relatecdb CdbNthRelatecdb

flCfgCDB_nth_selfld CdbNthSelfld



12

Lib

rary Services

flCfgCDB_num_fld CdbNumFld

flCfgCDB_num_relatecdb CdbNumRelateCdb

flCfgCDB_num_selfld CdbNumSelfld

flCfgCDB_row_insert CdbRowInsert

flCfgCDB_row_validate CdbRowValidate

flCfgCDB_rowno CdbRowno

flCfgCDB_select_begin CdbSelectBegin

flCfgCDB_select_criteria CdbSelectCriteria

flCfgCDB_select_current CdbSelectCurrent

flCfgCDB_select_delete CdbSelectDelete

flCfgCDB_select_end CdbSelectEnd

flCfgCDB_select_first CdbSelectFirst

flCfgCDB_select_last CdbSelectLast

flCfgCDB_select_next CdbSelectNext

flCfgCDB_select_previous CdbSelectPrevious

flCfgCDB_select_rowno CdbSelectRowno

flCfgCDB_select_update CdbSelectUpdate

flCfgCDB_unlock CdbUnlock

flCfgDom_get_name DomGetName

flCfgDom_get_size DomGetSize

flCfgDom_get_value DomGetValue

flCfgDom_set_value DomSetValue




•

•

•

•

For the most part, parameters for the OCX methods are the same as their related C functions. However, pointer arguments are passed as LONG types. For example, a flCfgSess* is passed by value as a long. Similarly, a flCfgCDB** is passed by reference as a long. CFGPAK OCX applications should treat these long values as opaque handles, passing them between CFGPAK methods, but not altering their values. Because all OCX “pointers” are of a generic long type, the application must not mix types, such as passing a long representing a FLCfgSess* into a method expecting a long representing a FLCfgCDB*.

Another difference is the return of string values. For example, consider retrieving the value of a configuration database field. With the C library function flCfgFld_get_value(), the application passed a target character buffer that was to be filled in by the CFGPAK function. The related OCX method FldGetValue() returns a string instead.

The handling of constants differs between the OCX and the C library. Since there is no header file for a control in which to define constants such as how #define FLCFG_E_GOOD is defined in C header file flcfg.h, OCX method GetDefineValue() is added to the control. It takes the definition's name as a parameter and returns its numeric value. The returned value can then be used by the OCX application just as the #define could be used in the C program.

flCfgFld_get_name FldGetName

flCfgFld_get_size FldGetSize

flCfgFld_get_title FldGetTitle

flCfgFld_get_value FldGetValue

flCfgFld_set_value FldSetValue

flCfgObj_add ObjAdd

flCfgObj_get_cdb ObjGetCdb

flCfgObj_select_begin ObjSelectBegin

flCfgObj_select_current ObjSelectCurrent

flCfgObj_select_delete ObjSelectDelete

flCfgObj_select_end ObjSelectEnd

flCfg_set_msgbox_handler MessageBox (event)


THE CONFIGURATION DATABASE ACTIVE-X COMPONENTThe OBJPACK Sample Project


12

Lib

rary Services

One last difference between the OCX and the C library is the message box callback for errors and warnings. The OCX exposes event MessageBox that the user overrides instead of invoking a callback function.

Other than noted above, the CFGPAK control works like the C library, so the function descriptions for the C library also apply to the OCX methods.

THE OBJPACK SAMPLE PROJECT

Included with the OCX CFGPAK control set is a sample Visual Basic project that is installed to directory {FLINK}\src\examples\objpack. This VB project creates a utility that assists users in selectively removing unused tags from their FactoryLink application.

THE CONFIGURATION DATABASE ACTIVE-X COMPONENTThe OBJPACK Sample Project


•

•

•

•


• • • •

13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

Chapter 13

Configuration PAK API Reference Library

This chapter provides the following information about each API function:



1. Type

2. Name

3. Direction (input = in; output = out; or both = in/out)

4. Description

• Returns: Description of the returned data from the function, usually a symbolic representation of the integer value returned by the function, such as ERROR or GOOD.



CONFIGURATION PAK API REFERENCE LIBRARY


•

•

•

•

FLCFG_SET_MSGBOX_HANDLER

Exception API.

Syntax #include <flcfg.h>

typedef int (*FLCFG_MBH)(char *title, char *msg, int btype);

void flCfg_set_msgbox_handler(FLCFG_MBH handler);

Remarks Function flCfg_set_msgbox_handler( ) allows you to install your own function to handle error messages, such as displaying message boxes or writing the messages to a log file.

Upon an internal exception or warning, the user-provided message box handler receives a title string, a message string, and message box type identifier. Types of message boxes requested are

The function should return the ID of the button pressed. The button IDs are:

In general, the type of message box requested is the OK box; therefore, the function should return the ID of the OK button. The one exception is the use of the message box during a tag definition modification where the OK-CANCEL functionality is requested. The OK-CANCEL functionality allows the user to make the choice as to how the activity is to proceed for cases where a trade-off is involved. For an example of this case, please see the description for function “flCfgObj_select_previous”.

If no handler is installed, then the error messages are routed to standard output.

See Also “flCfgObj_select_previous”

Arguments MBH_HANDLER handler in User-defined function to handle the message boxes of error messages.


FLCFG_MBOX_OK Single button (OK) messsage box.

FLCFG_MBOX_OKCANCEL Dual button (OK & CANCEL) message box.


FLCFG_MBID_OK Single button (OK) messsage box.

FLCFG_MBID_CANCEL Dual button (OK & CANCEL) message box.



13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

FLCFGAC_CLOSE_CDBS

Configuration Session API.


int flCfgAC_close_cdbs(flCfgSess *sess, flCfgAC *cfgacp);

Returns Success: FLCFG_E_GOOD.

Failure: FLCFG_E_{...} error code.

Remarks Function flCfgAC_close_cdbs( ) closes the databases defined by the given AC.

See Also “flCfgAC_close_cdbs”“flCfgSess_nth_ac”

FLCFGAC_GET_FILENAMEFLCFGAC_GET_TASKFLCFGAC_GET_TITLE

Attribute Catalog API.


char* flCfgAC_get_filename(flCfgAC *cfgacp);

char* flCfgAC_get_task(flCfgAC *cfgacp);

char* flCfgAC_get_title(flCfgAC *cfgacp);

Returns Success: (char*) to request string.

Failure: NULL.

Remarks Returns the name of the filename, title, or task associated with the given AC handle.

See Also “flCfgSess_nth_ac”

FLCFGAC_NTH_HDRCDB


Arguments flCfgSess* sess in Session handle.

flCfgAC* flcfgacp in Handle to the AC to close databases for.

Arguments flCfgAC* flcfgacp in AC to get attribute for.



•

•

•

•Syntax #include <flcfg.h>

int flCfgAC_nth_hdrcdb(flCfgAC *cfgacp, int n, flCfgCDB **cfgcdbp)



Remarks Function flCfgAC_nth_hdrcdb( ) returns the handle to the nth configuration database (CDB) tied to the given attribute catalog (AC). Given this handle, the CDB schema

and contents can be accessed.

This function is often called in conjunction with function flCfgAC_num_hdrcdb( ).

See Also “flCfgAC_num_hdrcdb”“flCfgSess_nth_ac”

FLCFGAC_NUM_HDRCDB



int flCfgAC_num_hdrcdb(flCfgAC *cfgacp);

Returns Success: Number of header CDBs (>= 0).


Remarks Function flCfgAC_num_hdrcdb( ) returns the number of top-level configuration databases defined within the given AC. A top-level CDB is one that has no fields whose range of legal values is dependent on the contents of another table. These are referred to as control tables in the PAK manual.

See Also “flCfgAC_nth_hdrcdb” “flCfgSess_nth_ac”

Arguments flCfgAC* cfgacp in AC handle.

int n in Index identifier for a particular CDB.

flCfgCDB** cfgcdbp out Handle to the requested CDB.

Arguments flCfgAC* cfgacp in Session handle.



13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

FLCFGAC_OPEN_CDBS



int flCfgAC_open_cdbs(flCfgSess *sess, flCfgAC *cfgacp, int create);



Remarks Function flCfgAC_open_cdbs( ) loads the configuration database schema definitions (if not loaded already) from the AC and then physically opens these files. The create flag indicates whether the function should create the databases if they do not already exist. If the create flag is off, then error code FLCFG_E_NOFILE reports that the tables have not yet been created.

See Also “flCfgAC_close_cdbs”“flCfgSess_nth_ac”“flCfgAC_get_task”“flCfgAC_num_hdrcdb”

FLCFGCDB_FIND_FLD

Configuration Database API.


int flCfgCDB_find_fld(flCfgCDB *cfgcdbp, char *name, flCfld **fldp);


Arguments flCfgSess* sess in Returns session handle.

flCfgAC* cfgacp in Handle to the AC to open databases for.

Int create in If non-zero, create the databases if they do not already exist.

Arguments flCfgCDB* cfgcdbp in Header CDB handle.

char* name in Target field name.

FlCfgFld** fldp out Handle to requested field.



•

•

•

•Failure: FLCFG_E_{...} error code.

Remarks Function flCfgCDB_find_fld( ) returns the handle to the field whose name matches the given name. Given this handle, the field properties can be accessed.

See Also “flCfgCDB_nth_fld”“flCfgCDB_num_fld”

FLCFGCDB_FIND_SELFLD



int flCfgCDB_find_selfld(flCfgCDB *cfgcdbp, char *name,

flCfgSel **selfldp);



Remarks Function flCfgCDB_find_selfld( ) returns the handle to the select field whose name matches the given name. Given this handle, the field properties can be accessed.

See Also “flCfgCDB_nth_selfld” “flCfgCDB_num_selfld”

FLCFGCDB_GET_DOMFLD



char* flCfgCDB_get_domfld(flCfgCDB *cfgcdbp, flCfgDom **cfgdomp);



char* name in Target field’s name.

FlCfgSel** selp out Handle to requested select field.

Arguments flCfgCDB* cfgcdbp in CDB handle.

flCfgDom* cfgdomp out Domain field handle.



13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary


Remarks Function flCfgCDB_get_domfld( ) returns the handle to the domain field structure for the given CDB. The value of the domain field determines the domain to which a given row belongs.

Most CDBs have a domain field. Error code FLCFG_E_NOTFOUND is returned for those that do not.

See Also “flCfgCDB_nth_selfld”“flCfgCDB_nth_fld”“flCfgCDB_get_seqfld”

FLCFGCDB_GET_NAME



char* flCfgCDB_get_name(flCfgCDB *cfgcdbp);

Returns Success: (char*) to CDB name.

Failure: NULL.

Remarks Function flCfgCDB_get_name( ) returns the table name for the given CDB.

See Also “flCfgCDB_get_title”

FLCFGCDB_GET_SEQFLD



char* flCfgCDB_get_seqfld(flCfgCDB *cfgcdbp, flCfgSeq **cfgseqp);



Arguments flCfgCDB* cfgcdbp in CDB to get attribute for.


flCfgSeq cfgseqp out Sequence field handle.



•

•

•

•Remarks Function flCfgCDB_get_seqfld( ) returns the handle to the sequence field structure

for the given CDB. The value of the sequence field determines the order that FLCM presents the rows. Sequence values are unique among all rows sharing the same selection criteria. In other words, the sequence number is unique among all rows sharing the same combination of domain and selection field values.

Most CDBs have a sequence field. For those that do not, error code FLCFG_E_NOTFOUND is returned.

See Also “flCfgCDB_get_domfld”“flCfgCDB_nth_selfld”“flCfgCDB_nth_fld”

FLCFGCDB_GET_TITLE



char* flCfgCDB_get_title(flCfgCDB *cfgcdbp);

Returns Success: (char*) to the CDB title.

Failure: NULL.

Remarks Function flCfgCDB_get_title( ) returns the title associated with the given CDB.

See Also “flCfgCDB_get_name”

FLCFGCDB_LOCK



int flCfgCDB_lock(flCfgCDB *cfgcdbp, int incl_relcdbs);



Arguments flCfgCDB* cfgcdbp in CDB to get attribute for.


int incl_relcdbs in If non-zero, lock related CDBs as well.



13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

Remarks Function flCfgCDB_lock( ) locks the entire CDB contents, preventing other processes from reading or writing its contents. Locks are useful when performing complex transactions that require others to be blocked until the operation is complete. Since complex operations often involve the CDBs related to the given CDB, the incl_relcdbs parameter allows the entire CDB tree to be locked with a single function call.

Calls to function flCfgCDB_lock( ) can be nested, but care must be taken to ensure the same number of unlock calls are made for each lock call.

See Also “flCfgCDB_unlock”

FLCFGCDB_NTH_FLD



int flCfgCDB_nth_fld(flCfgCDB *cfgcdbp, int n, flCfgFld **fldp);



Remarks Function flCfgCDB_nth_fld( ) returns the handle to the nth field tied to the given CDB. Given this handle, the field properties can be accessed.

See Also “flCfgCDB_num_fld”

FLCFGCDB_NTH_RELATECDB



int flCfgCDB_nth_relatecdb(flCfgCDB *cfgcdbp, int n, flCfgCDB **relcdbp);


int n in Index identifier for a particular field.

FlCfgFld** v out Handle to the requested field.


int n in Index identifier for a particular CDB.



•

•

•

•



Remarks Function flCfgCDB_nth_relatecdb( ) returns the handle to the nth relate CDB tied to the given CDB. Given this handle, the relate CDB schema and contents can be accessed.

A relate CDB is a table whose contents depend upon a many to one relation between itself and its header CDB. Although most relations are one level deep, a relate CDB may be itself a header CDB, providing multiple level of relations. These relations commonly bind on the basis of a domain and a table name where table name is an arbitrary string used to bind records in the relate CDB to a record in the header CDB.

This function is often called within an iteration loop in conjunction with function flCfgCDB_num_relatecdb( ).

See Also “flCfgCDB_num_relatecdb”

FLCFGCDB_NTH_SELFLD



int flCfgCDB_nth_selfld(flCfgCDB *cfgcdbp, int n, flCfgSel **selfldp);



Remarks Function flCfgCDB_nth_selfld( ) returns the handle to the nth select field tied to the given CDB. Given this handle, the field properties can be accessed.

See Also “flCfgCDB_num_selfld”

flCfgCDB** relcdbp out Handle to requested CDB.


int n in Index identifier for a particular field.

FlCfgSel** selp out Handle to requested select field.



13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

FLCFGCDB_NUM_FLDFLCFGCDB_NUM_RELATECDBFLCFGCDB_NUM_SELFLD



int flCfgCDB_num_fld(flCfgCDB *cfgcdbp);

int flCfgCDB_num_relatecdb(flCfgCDB *cfgcdbp);

int flCfgCDB_num_selfld(flCfgCDB *cfgcdbp);

Returns Success: Number of requested items (>= 0).


Remarks Function flCfgCDB_num_fld( ) returns the number of data fields defined within the given CDB.

Function flCfgCDB_num_relatecdb( ) returns the number of CDBs whose contents are primarily dependent upon the given CDB.

Function flCfgCDB_num_selfld( ) returns the number of selection fields defined within the given CDB.

See Also “flCfgCDB_nth_fld”“flCfgCDB_nth_relatecdb”“flCfgCDB_nth_selfld”

FLCFGCDB_ROW_INSERT



int flCfgCDB_row_insert(flCfgCDB *cfgcdbp, flCfgValErr *ep);





flCfgValErr* ep out Validation error details.



•

•

•

•Remarks Function flCfgCDB_row_insert( ) inserts a record into the given CDB, using the

values found within the CDB structure itself. Field level validation is performed, and any such errors abort the insert. Specifics about the validation error are returned in the flCfgValErr structure. Relations, such as whether the parent record exists, are not checked.

When a record is inserted, a sequence number is usually associated with it. If the given sequence value is zero, then the row is assigned the next largest sequence number appropriate for the row’s relations. Unless you have specific ordering needs, it is best to allow flCfgCDB_row_insert( ) to assign the next available sequence number by setting the sequence value to zero.

Function flCfgCDB_row_insert( ) updates the cross-reference (XREF) database with any tag references contained within the inserted row.

See Also “flCfgCDB_row_validate”

FLCFGCDB_ROW_VALIDATE



int flCfgCDB_row_validate(flCfgCDB *cfgcdbp, flCfgValErr *ep);



Remarks Function flCfgCDB_row_validate( ) examines the individual field values for illegal entries. Validation errors are returned in the flCfgValErr structure. Relations, such as whether the parent record exists, are not checked.

See Also “flCfgCDB_row_insert”“flCfgFld_set_value”





13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

FLCFGCDB_ROWNO



int flCfgCDB_rowno(flCfgCDB *cfgcdbp, long *rowno);



Remarks Function flCfgCDB_rowno( ) returns the physical record number of the currently selected row. The selected row retains this number until it is deleted, after which, the number is eventually reassigned to a newly inserted row.

See Also “flCfgCDB_select_rowno”“flCfgCDB_lock”“flCfgCDB_unlock”

FLCFGCDB_SELECT_BEGIN



int flCfgCDB_select_begin(flCfgCDB *cfgcdbp);



Remarks Function flCfgCDB_select_begin( ) initiates the given CDB for a selection. A read lock is placed on the CDB and the selection criteria is initialized to the values currently held by the appropriate header CDBs, if any. Once the selection has begun, the selection criteria may be tuned by altering the domain and/or select field values to create a query not controlled by the contents of the header table(s). Once the selection criteria is set, function flCfgCDB_select_first( ) is called to retrieve the first appropriate record.


long* rowno out Row number.




•

•

•

•The selection criteria equates to the field values held in the domain and select fields, as defined within the CDB schema. For selections from header CDBs, the user should subsequently update the selection criteria by setting the domain field value since no control record exists to derive the desired selection domain from.

Selections cannot be nested. If attempted, code FLCFG_E_SELBEGUN is returned. The outstanding selection must be ended prior to initiating a subsequent selection.

See Also “flCfgCDB_select_first”“flCfgCDB_select_next”“flCfgCDB_select_end”“flCfgDom_set_value”“flCfgSel_set_value”

FLCFGCDB_SELECT_CRITERIA



int flCfgCDB_select_criteria(flCfgCDB *cfgcdbp);



Remarks Function flCfgCDB_select_criteria( ) is used with relate CDBs to configure their selection criteria based upon the current selection of their header CDBs.

The most common use for this function is prior to inserting a row into a relate CDB. Assuming the header CDB(s) are positioned on the row(s) the new record is to be associated with, the values of the header’s selection are loaded into the relate CDB, after which, the data fields can be filled and the row inserted, selection and data information together.

See Also “flCfgCDB_select_first”“flCfgCDB_row_insert”




13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

FLCFGCDB_SELECT_CURRENT



int flCfgCDB_select_current(flCfgCDB *cfgcdbp);



Remarks Function flCfgCDB_select_current( ) reads the currently selected row database values into memory. A call to function flCfgCDB_select_first( ) or flCfgCDB_select_next( ) must precede this call. Error code FLCFG_E_ENDOFSEL is returned if no row is currently selected.

The most common use for this function is after deleting a row. At this time, the database is positioned on the next applicable row, but it has yet to be read into memory.

See Also “flCfgCDB_select_first”“flCfgCDB_select_next”“flCfgCDB_select_delete”

FLCFGCDB_SELECT_DELETE



int flCfgCDB_select_delete(flCfgCDB *cfgcdbp);



Remarks Function flCfgCDB_select_delete( ) removes the currently selected row from the database. Any rows in any related CDB tied to the deleted row are deleted as well. The cross-reference (XREF) database is updated with any tag references loss by the row deletion(s).





•

•

•

•Deletions will be disallowed if any one of the related CDBs to which the deletion may be propagated to is held open by an active selection.

See Also “flCfgCDB_select_begin”“flCfgCDB_select_current”

FLCFGCDB_SELECT_END



int flCfgCDB_select_end(flCfgCDB *cfgcdbp);



Remarks Function flCfgCDB_select_end( ) releases all memory and database locks held on behalf of a selection. For every selection begun, a corresponding end should be issued.

See Also “flCfgCDB_select_begin”“flCfgCDB_select_first”“flCfgCDB_select_next”

FLCFGCDB_SELECT_FIRST



int flCfgCDB_select_first(flCfgCDB *cfgcdbp);



Remarks Function flCfgCDB_select_first( ) takes the values currently set as the selection criteria and reads the first row that matches it. A call to function flCfgCDB_select_begin( ) must precede this call. If no rows match the selection criteria, then error code FLCFG_E_ENDOFSEL is returned.





13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

Once the record is read, the field values for the current record are available via functions flCfgDom_get_value( ), flCfgSel_get_value( ), and flCfgFld_get_value( ).

Once a selection against the given CDB begins, it is legal to reset the selection back to the first record by invoking this function without intermediate calls to the selection begin/end functions.

See Also “flCfgCDB_select_begin”“flCfgCDB_select_next”“flCfgCDB_select_end”“flCfgDom_get_value”“flCfgSel_get_value”“flCfgFld_get_value”

FLCFGCBD_SELECT_LAST

Object Database API


int flCfgCDB_select_last(flCfgDB *Cfgcdbp);


Returns Success:FLCFG_E_GOOD

Failure:FLCFG_E_{...} error code

Description Function flCfgCDB_select_last() takes the values currently set as the selection criteria and reads the last row that matches it. A call to function flCfgCDB_select_begin() must precede this call. If no rows match the selection criteria, then error code FLCFG_E_ENDOFSEL is returned.

Once the record is read, the field values for the current record are available via functions flCfgDom_get_value(), flCfgSel_get_value(), and flCfgFld_get_value().

Once a selection against the given CDB has been begun, it is legal to reset the selection back to the first record by invoking this function without intermediate calls to the selection begin/end functions.

See Also flCfgCDB_select_beginflCfgCDB_select_previousflCfgCDB_select_endflCfgDom_get_valueflCfgSel_get_valueflCfgFld_get_value



•

•

•

•

FLCFGCDB_SELECT_NEXT



int flCfgCDB_select_next(flCfgCDB *cfgcdbp);



Remarks Function flCfgCDB_select_next( ) reads the next record that matches the selection criteria. This function is usually invoked several times after an initial call to the function flCfgCDB_select_first( ). Error code FLCFG_E_ENDOFSEL is returned once all applicable rows have been exhausted.

After the record is read, the field values for the current record are available via functions flCfgDom_get_value( ), flCfgSel_get_value( ), and flCfgFld_get_value( ).

See Also “flCfgCDB_select_begin”“flCfgCDB_select_first”“flCfgCDB_select_end”“flCfgDom_get_value”“flCfgSel_get_value”“flCfgFld_get_value”


CONFIGURATION PAK API REFERENCE LIBRARYflCfgCDB_select_previous


13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

FLCFGCDB_SELECT_PREVIOUS



int flCfgCDB_select_previous(flCfgCDB *cfgcdbp);




Description Function flCfgCDB_select_previoust() reads the previous record that matches the selection criteria. This function is usually invoked several times after an initial call to function flCfgCDB_select_last(). Once all applicable rows have been exhausted, error code FLCFG_E_ENDOFSEL is returned.

Once the record is read, the field values for the current record are available via functions flCfgDom_get_value(), flCfgSel_get_value(), and flCfgFld_get_value().

See Also “flCfgCDB_select_begin”“flCfgCDB_select_last”“flCfgCDB_select_end”“flCfgDom_get_value”“flCfgSel_get_value”“flCfgFld_get_value”

FLCFGCDB_SELECT_ROWNO



int flCfgCDB_select_rowno(flCfgCDB *cfgcdbp, long rowno);




long rowno in Row number.



•

•

•

•Remarks Function flCfgCDB_select_rowno( ) selects and reads the row associated with the

given row number. A call to function flCfgCDB_select_begin( ) must precede this call. Error code FLCFG_E_NOTFOUND is returned if no such row exists. This function does not honor any constraints entered into the CDB selection criteria.

The most common use for this function is as part of a complex transaction where the position of many rows must be recalled and accessed directly. Since row numbers are subject to change in a multi-user environment, wrap the entire transaction in an lock and unlock code block.

See Also “flCfgCDB_rowno”“flCfgCDB_lock”“flCfgCDB_unlock”

FLCFGCDB_SELECT_UPDATE



int flCfgCDB_select_update(flCfgCDB *cfgcdbp, flCfgValErr *ep);



Remarks Function flCfgCDB_select_update( ) updates the currently selected row from the database. Any rows in the related CDBs tied to the updated row are updated as well, if the update affects the relation. The cross-reference (XREF) database is updated with any tag references added, lost, or altered by the row update(s).

Updates are disallowed if any one of the related CDBs the update would be propagated to is held open by an active selection.

Domain values can be updated but only in header CDBs. Related CDB rows are always dependent on their header CDB domain value. Updates to related rows are always validated prior to committing the update. If any of these rows fail to validate, the entire operation is aborted.

See Also “flCfgCDB_select_criteria”





13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

FLCFGCDB_UNLOCK



int flCfgCDB_unlock(flCfgCDB *cfgcdbp, int incl_relcdbs);



Remarks Function flCfgCDB_unlock( ) releases the lock held on the entire CDB contents and is called in conjunction with function flCfgCDB_lock( ).

See Also “flCfgCDB_lock”

FLCFGDOM_GET_NAME



char* flCfgDom_get_name(flCfgDom *cfgdomp);

Returns Success: (char*) to requested field name.

Failure: NULL.

Remarks Function flCfgDom_get_name( ) returns the domain field name.

See Also “flCfgCDB_get_domfld”“flCfgDom_get_size”“flCfgDom_get_value”


int incl_relcdbs in If non-zero, unlock related CDBs as well.

Arguments flCfgDom* cfgdomp in Domain field handle.



•

•

•

•

FLCFGDOM_GET_SIZE



int flCfgDom_get_size(flCfgDom *cfgdomp);

Returns Success: Field width.


Remarks Function flCfgDom_get_size( ) returns the domain field size.

See Also “flCfgCDB_get_domfld”“flCfgDom_get_name”“flCfgDom_get_value”

FLCFGDOM_GET_VALUE



int flCfgDom_get_value(flCfgDom *cfgdomp, char *domval, int maxlen);



Remarks Function flCfgDom_get_value( ) returns the domain field value as filled in from a selection operation.

See Also “flCfgCDB_get_domfld”“flCfgDom_set_value”


Arguments flCfgDOM* cfgdomp in Domain field handle.

char* domval out Return buffer for domain value.

int maxlen in Size of domval buffer.



13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

FLCFGDOM_SET_VALUE



int flCfgDom_set_value(flCfgDom *cfgdomp, char *domval);



Remarks Function flCfgDom_set_value( ) sets the domain field value in preparation for selection, insert or update operations.

Setting the domain value usually applies only to the top-most header CDB. In other cases, the domain value is inherited. For example, when inserting into a related CDB, a call to flCfgCDB_select_criteria( ) normally precedes the call to function flCfgCDB_select_first( ) so the row being inserted is related to the currently selected row(s) within header CDB(s).

See Also “flCfgCDB_get_domfld”“flCfgDom_set_value”

FLCFGFLD_GET_NAME



char* flCfgFld_get_name(flCfgFld *cfgfldp);


Failure: NULL.

Remarks Function flCfgFld_get_name( ) returns the field name.

See Also “flCfgCDB_nth_fld”“flCfgFld_get_size”“flCfgFld_get_value”


char* domval in New domain value.

Arguments flCfgFld* cfgfldp in Field handle.



•

•

•

•

FLCFGFLD_GET_SIZE



int flCfgFld_get_size(flCfgFld *cfgfldp);



Remarks Function flCfgFld_get_size( ) returns the field size.

See Also “flCfgCDB_nth_fld”“flCfgFld_get_name”“flCfgFld_get_value”

FLCFGFLD_GET_TITLE



char* flCfgFld_get_title(flCfgFld *cfgfldp);

Returns Success: (char*) to requested field title.

Failure: NULL.

Remarks Function flCfgFld_get_title( ) returns the field title as specified within the AC file.

See Also “flCfgCDB_nth_fld”“flCfgFld_get_name”





13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

FLCFGFLD_GET_VALUE



int flCfgFld_get_value(flCfgFld *cfgfldp, char *value, int maxlen);



Remarks Function flCfgFld_get_value( ) returns the field value as filled in from a selection operation.

See Also “flCfgCDB_nth_fld”“flCfgFld_get_name”“flCfgFld_get_size”

FLCFGFLD_SET_VALUE



int flCfgFld_set_value(flCfgFld *cfgfldp, char *value);



Remarks Function flCfgFld_set_value( ) sets the field value in preparation for an insert or update operation.

See Also “flCfgCDB_nth_fld”“flCfgFld_get_value”


char* value out Return buffer for field value.

int maxlen in Size of value buffer.


char* value in New field value.



•

•

•

•

FLCFGOBJ_ADD

Object Database API.


int flCfgObj_add(flCfgObj *objp, flCfgTag *tagp,flCfgValErr *valerr);



Remarks Function flCfgObj_add( ) inserts a new tag into the application. Any problems with the proposed definition are returned via the validation error structure.

At a minimum, the given tag definition must have the name, domain, and type attributes set within the given flCfgTag.

See Also “flCfgObj_select_delete”“flCfgObj_select_first”“flCfgObj_select_previous”“flCfgTag_set_attrval”

FLCFGOBJ_GET_CDB



int flCfgObj_get_cdb(flCfgSess *sess, flCfgCDB **objp);



Remarks Function flCfgObj_get_cdb( ) returns the handle to the given session object database. With this handle, tag definitions can be read from and written to the application.

Arguments flCfgCDB* objp in Object CDB handle.

flCfgTag* tagp in Tag definition to add.

flCfgValErr* valerr out Validation error details.


flCfgCDB** objp out Handle to object CDB.



13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

See Also “flCfgObj_select_begin”

“flCfgObj_add”

FLCFGOBJ_SELECT_BEGIN



int flCfgObj_select_begin(flCfgObj *objp);



Remarks Function flCfgObj_select_begin( ) initiates a selection against the object database. Selections cannot be nested.

All selections against the object database are sorted based on tag name.

See Also “flCfgObj_select_first”“flCfgObj_select_name”“flCfgObj_select_end”“flCfgTag_get_attrval”

FLCFGOBJ_SELECT_CURRENT



int flCfgObj_select_current(flCfgCDB *objp, flCfgTag *tagp);





flCfgTag* tagp out Currently selected tag definition.



•

•

•

•Remarks Function flCfgObj_select_current( ) reads the currently selected tag definition into

the given tag definition structure. A call to function flCfgObj_select_first( ) or flCfgObj_select_name( ) must proceed this call. Error code FLCFG_E_ENDOFSEL is returned if no row is currently selected.

The most common use for this function is after deleting a tag definition. At this time, the database is positioned on the next applicable row, but it has yet to be read into memory.

See Also “flCfgObj_select_first”“flCfgObj_select_name”“flCfgObj_select_delete”

FLCFGOBJ_SELECT_DELETE



int flCfgObj_select_delete(flCfgObj *objp);



Remarks Function flCfgObj_select_delete( ) removes the currently selected tag definition from the object database. Deletions are rejected where references to that tag still exist within the applications.

For structured tags, this constraint includes references to any of its member tags. If there are no references to a structured tag and its members, then the delete call removes both the currently selected tag and all of its members.

See Also “flCfgObj_add”




13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

FLCFGOBJ_SELECT_END



int flCfgObj_select_end(flCfgCDB *objp);



Remarks Function flCfgObj_select_end( ) releases all memory and database locks held on behalf of a selection. A corresponding end should be issued for every selection begun.

See Also “flCfgObj_select_begin”“flCfgObj_select_first”“flCfgObj_select_next”

FLCFGOBJ_SELECT_FIRST



int flCfgObj_select_first(flCfgObj *objp, flCfgTag *tagp);



Remarks Function flCfgObj_select_first( ) reads the first tag definition into the given tag definition structure. A call to function flCfgObj_select_begin( ) must precede this call.

If no tag definitions exist, error code FLCFG_E_ENDOFSEL is returned.

See Also “flCfgObj_select_begin”“flCfgObj_select_next”“flCfgObj_select_end”“flCfgTag_get_attrval”



flCfgTag* tagp out First tag definition.



•

•

•

•

FLCFGOBJ_SELECT_LAST

Object Database API


int flCfgObj_select_last(flCfgObj *objp, flCfgTag *tagp);





Description Function flCfgObj_select_last() reads the last tag definition into the given tag definition structure. A call to function flCfgObj_select_begin() must precede this call. If no tag definitions exist, error code FLCFG_E_ENDOFSEL is returned.

See Also “flCfgObj_select_begin”“flCfgObj_select_previous”“flCfgObj_select_end”“flCfgTag_get_attrval”

FLCFGOBJ_SELECT_NAME



int flCfgObj_select_name(flCfgObj *objp, char* name, flCfgTag *tagp);



Remarks Function flCfgObj_select_name( ) reads the tag definition for the given name into the given tag definition structure. A call to function flCfgObj_select_begin( ) must precede this call.


char* name in Name of tag to select

flCfgTag* tagp out Tag definition for given name.



13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

The definition for the tag that alphabetically falls immediately after where the requested tag would reside is read if no such tag exists. In this case, the selection returns error code FLCFG_E_NOTFOUND. Error code FLCFG_E_ENDOFSEL is returned if no such tag exists.

See Also “flCfgObj_select_begin”“flCfgObj_select_next”“flCfgObj_select_end”“flCfgTag_get_attrval”

FLCFGOBJ_SELECT_NEXT



int flCfgObj_select_next(flCfgObj *objp);



Remarks Function flCfgObj_select_next( ) reads the next object definition. This function is usually multiply invoked after an initial call to function flCfgObj_select_first( ). Error code FLCFG_E_ENDOFSEL is returned after all definitions have been exhausted.

See Also “flCfgObj_select_begin”“flCfgObj_select_first”“flCfgObj_select_end”“flCfgTag_get_attrval”





•

•

•

•

FLCFGOBJ_SELECT_PREVIOUS



int flCfgObj_select_previous(flCfgObj *objp);





Description Function flCfgObj_select_previous() reads the previous object definition. This function is usually multiply invoked after an initial call to function flCfgObj_select_last(). Once all definitions have been exhausted, error code FLCFG_E_ENDOFSEL is returned.

See Also “flCfgObj_select_begin”“flCfgObj_select_first”“flCfgObj_select_end”“flCfgTag_get_attrval”

FLCFGOBJ_SELECT_UPDATE



int flCfgObj_select_update(flCfgObj *objp,

flCfgTag *tagp,flCfgValErr *valerr);


Failure: FLCFG_E_TAGEDIT.

FLCFG_E_{...} error code.


flCfgTag* tagp in Tag definition to add.

flCfgValErr* valerr out Validation error details.



13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

Remarks Function flCfgObj_select_update( ) modifies the currently selected tag definition. Given tag definition tagp, the currently selected row attributes are compared and the differences updated accordingly. If one or more of the changed attributes are one of the core attributes (dimension, domain, name, and type), the update is propagated throughout the entire application. This includes task CDBs, Math & Logic procedure files, and drawing files.

Since changing a core attribute results in sweeping changes, many constraints are placed upon this capability in order to preserve the integrity of the application. Should the proposed definition update violate the application’s integrity, these violations are reported back to the use via the message box handler (see function “flCfg_set_msgbox_handler”for details).

See Also “flCfg_set_msgbox_handler”“flCfgObj_add”“flCfgObj_select_delete”

FLCFGSEL_GET_NAME



char* flCfgSel_get_name(flCfgSel *cfgselp);


Failure: NULL.

Remarks Function flCfgSel_get_name( ) returns the selection field name.

See Also “flCfgCDB_nth_selfld”“flCfgSel_get_size”“flCfgSel_get_value”

Arguments flCfgSel* cfgselp in Field handle.



•

•

•

•

FLCFGSEL_GET_SIZE



int flCfgSel_get_size(flCfgSel *cfgselp);



Remarks Function flCfgSel_get_size( ) returns the selection field size.

See Also “flCfgCDB_nth_selfld”“flCfgSel_get_name”“flCfgSel_get_value”

FLCFGSEL_GET_TITLE



char* flCfgSel_get_title(flCfgSel *cfgselp);

Returns Success: (char*) to requested field title.

Failure: NULL.

Remarks Function flCfgSel_get_title( ) returns the selection field title as specified within the AC file.

See Also “flCfgCDB_nth_selfld”“flCfgSel_get_name”





13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

FLCFGSEL_GET_VALUE



int flCfgSel_get_value(flCfgSel *cfgselp, char *value, int maxlen);



Remarks Function flCfgSel_get_value( ) returns the selection field value as filled in from a selection operation.

See Also “flCfgCDB_nth_selfld”“flCfgSel_get_name”“flCfgSel_get_size”

FLCFGSEL_SET_VALUE



int flCfgSel_set_value(flCfgSel *cfgselp, char *value);



Remarks Function flCfgSel_set_value( ) sets the selection field value in preparation for selection, insert, or update operations. When selecting data from a CDB, the values set within the select field are ANDed together and form the where clause.


char* value out Return buffer for selection field value.



char* value in New select field value.



•

•

•

•Normally, one does not directly set the select values. As these values are derived from another CDB (to relate the given CDB to its parent, or header) these values are implicitly managed for selections or indirectly set for insert/update operations via function flCfgCDB_select_criteria( ).

See Also “flCfgCDB_nth_selfld”“flCfgSel_get_value”

FLCFGSEQ_GET_NAME



char* flCfgSeq_get_name(flCfgSeq *cfgseqp);


Failure: NULL.

Remarks Function flCfgSeq_get_name( ) returns the sequence field name.

See Also “flCfgCDB_get_seqfld”“flCfgSeq_get_size”“flCfgSeq_get_value”

FLCFGSEQ_GET_SIZE



int flCfgSeq_get_size(flCfgSeq *cfgseqp);



Remarks Function flCfgSeq_get_size( ) returns the sequence field size.

See Also “flCfgCDB_get_seqfld”“flCfgSeq_get_name”

Arguments flCfgSeq* cfgseqp in Sequence field handle.




13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

“flCfgSeq_get_value”

FLCFGSEQ_GET_VALUE



int flCfgSeq_get_value(flCfgSeq *cfgseqp, long *value);



Remarks Function flCfgSeq_get_value( ) returns the sequence field value as filled in from a selection operation.

See Also “flCfgCDB_get_seqfld”“flCfgSeq_set_value”

FLCFGSEQ_SET_VALUE



int flCfgSeq_set_value(flCfgSeq *cfgseqp, long value);



Remarks Function flCfgSeq_set_value( ) sets the sequence field value in preparation for an insert or update operation.

For inserts, it is often best to set this value to zero. The insertion function then assigns the next available sequence number to the row.

See Also “flCfgCDB_get_seqfld”


long* value out Return buffer for sequence value.


long value in New sequence field value.



•

•

•

•“flCfgSeq_set_value”

FLCFGSESS_CLOSE



int flCfgSess_close(flCfgSess **sess);



Remarks Function flCfgSess_close( ) closes the given session. Any configuration databases held open within the session are closed at this time. Also, the call releases memory held internally for the session.

All AC, CDB, or other handles tied to the closed session become invalid.

See Also “flCfgSess_open”

FLCFGSESS_NTH_AC



int flCfgSess_nth_ac(flCfgSess *sess, int n, flCfgAC **cfgacp);



Remarks Function flCfgSess_nth_ac( ) returns the handle to the nth attribute catalog tied to the given session. Given this handle, the configuration databases defined within it can be accessed.

Arguments flCfgSess** sess in/out Address of session handle. Set to NULL upon session closure.


Int n in Index identifier for particular AC.

flCfgAC** cfgacp out Handle to requested AC.



13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

This function is often called within an iteration loop in conjunction with function flCfgSess_num_ac( ).

See Also “flCfgSess_num_ac”“flCfgSess_open”

FLCFGSESS_NUM_AC



int flCfgSess_num_ac(flCfgSess *sess);

Returns Success: Number of ACs (>= 0)


Remarks Function flCfgSess_num_ac( ) returns the number of attribute catalogs found within the given session’s {FLINK}. Attribute Catalogs are a grouping of configuration database schemas and handles associated with a particular task. You obtain a CDB handle through an AC.

The AC-to-CT map, ASCII file {FLINK}/ac/ac2ct.map is the source for this information. If the number of ACs appears to be less than it should (as if it is omitting your PAK task), it is likely the TITLES file, ASCII file {FLINK}/ac/titles, is missing the AC entry for that task. If so, add it to the TITLES file. Then, update the map file by executing “acctmgr -c -d” at the system prompt. This re-creates the map file based on AC entries in the TITLES file.

See Also “flCfgSess_num_ac”“flCfgSess_open”




•

•

•

•

FLCFGSESS_OPEN



int flCfgSess_open(char *flink, char *flapp, flCfgSess **sess);



Remarks Function flCfgSess_open( ) creates a configuration session and attaches to the system files within the target application. During the process, files within the given FactoryLink system directory are loaded and used to interpret the application files. Once all initialization activities succeed, a handle to the session is returned to the caller. Otherwise, one of the error codes is returned.

The target application must exist in order to open it.

Currently, two limitations exist on the opening of sessions. First, a configuration session can only be open for one application at a time. The API enforces this and returns error code FLCFG_E_MULTSESS.

Second, all sessions must reference the same FactoryLink directory for as many times as configuration sessions are opened and closed. System errors result from the latter case.

See Also “flCfgSess_close”

Arguments char* flink in {FLINK} directory.

char* flapp in {FLAPP} directory.

flCfgSess** sess out Returns session handle. This is set to NULL if open fails.



13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

FLCFGTAG_CLEAR_ATTRVALS



int flCfgTag_clear_attrvals(flCfgTag *tagp);



Remarks Function flCfgTag_clear_attrvals( ) sets all attributes within the given tag definition structure to a null string.

See Also “flCfgObj_add”

FLCFGTAG_CREATEFLCFGTAG_DESTROY



int flCfgTag_create(flCfgTag **tagp);

int flCfgTag_destroy(flCfgTag **tagp);



Remarks Function flCfgTag_create( ) allocates and returns a handle to a tag definition structure. These are passed into object database calls. The returned flCfgTag has all attributes initialized to a null string.

Function flCfgTag_destroy( ) releases a tag definition.

See Also “flCfgObj_add”“flCfgObj_select_delete”“flCfgObj_select_name”“flCfgObj_select_previous”

Arguments flCfgTag* tagp in Tag definition structure.

Arguments flCfgTag** tagp in/out Tag definition structure.



•

•

•

•

FLCFGTAG_GET_ATTRVALFLCFGTAG_GET_ATTRVALP


Syntax #include <flcfg.h>int flCfgTag_get_attrval(flCfgTag *tagp, int id, char *val, int maxlen);

int flCfgTag_get_attrvalp(flCfgTag *tagp, int id,char **val);

flCfgTag_get_attrval( ):

flCfgTag_get_attrvalp( ):



Remarks Functions flCfgTag_get_attrval( ) and flCfgTag_get_attrvalp( ) return the value for the requested attribute set within the given tag definition structure.

See Also “flCfgObj_select_first”“flCfgObj_select_name”“flCfgTag_set_attrval”

Arguments flCfgTag* tagp in Tag definition.

int id in Attribute ID.

char* val out Value buffer.


char** val out Pointer to attribute value (read only).



13

Co

nfig

PA

K A

PI

Referen

ce Lib

rary

FLCFGTAG_SET_ATTRVAL



int flCfgTag_set_attrval(flCfgTag *tagp, int id, char *val);



Remarks Function flCfgTag_set_attrval( ) sets the value for the requested attribute within the given tag definition structure.

See Also “flCfgObj_add”“flCfgObj_select_previous”

“flCfgTag_clear_attrvals”

“flCfgTag_get_attrval”

FLCFGVALERR_CREATEFLCFGVALERR_DESTROY

Validation Error API.


int flCfgValErr_create(flCfgValErr **valerrp);

int flCfgValErr_destroy(flCfgValErr **valerrp);



Remarks Function flCfgValErr_create( ) allocates and returns a validation error handle. These are passed into CDB insert and update calls.

Function flCfgValErr_destroy( ) releases a validation error handle.

Arguments flCfgTag* tagp in Tag definition structure.

int id in Attribute ID.

char* val in Target attribute value.

Arguments flCfgValErr** valerr in/out Validation error handle.



•

•

•

•See Also “flCfgValErr_get_ctname”

“flCfgValErr_get_fldname”

“flCfgValErr_get_fldvalue”

“flCfgValErr_get_valmsg”

FLCFGVALERR_GET_CTNAMEFLCFGVALERR_GET_FLDNAMEFLCFGVALERR_GET_FLDVALUEFLCFGVALERR_GET_VALMSG

Validation Error API.


char* flCfgValErr_get_ctname(flCfgValErr *valerrp);

char* flCfgValErr_get_fldname(flCfgValErr *valerrp);

char* flCfgValErr_get_fldvalue(flCfgValErr *valerrp);

char* flCfgValErr_get_valmsg(flCfgValErr *valerrp);

Returns Success: (char*) to requested string.

Failure: NULL.

Remarks Function flCfgValErr_get_…( ) returns the specifics associated with a validation error.

See Also “flCfgValErr_create”

Arguments flCfgValErr* valerrp in Sequence field handle.

• • • • • • • • • • • • • • • • • • • • • • • • • • • • • •

Part I

395

Part IIIRAPD PAK


• • • •

RAPD PAK at a Glance

Using RAPD PAK


1. Read what RAPD does. Chapter 14, “RAPD PAK Overview“

2. Read about IMX Architecture, including compiling with the IMX library.

Chapter 15, “RAPD Principle”

3. Read about IMX Messaging, including mailbox communications, datasets, I/O functionality, exception write function, data directions, IMX and LANS.

Chapter 16, “IMX Messaging”

4. Read about Writing a RAPD Driver. Chapter 17, “Writing a RAPD Driver”

5. Read about the IMX Reference Guide. Chapter 18, “IMX Reference Library”


•

•

•

•


• • • •

14

RA

PD

PA

K O

verview

Chapter 14

RAPD PAK Overview

The FactoryLink Rapid Application Protocol Drive technology is the basis for the RAPD Programmer’s Access Kit (RAPD PAK). This technology affords FactoryLink software developers and application designers an alternative to the existing External Device Interface (EDI) method. The new technology allows a reduction in driver software and applications development.

The RAPD PAK is based on the Intertask Mail Exchange (IMX) library. The IMX library defines a method for FactoryLink tasks to communicate via mailbox tags.

Compliant with FactoryLink open architecture, client tasks created with the RAPD PAK are fully integrated into FactoryLink development and run-time systems.

This manual assumes the reader is an experienced C programmer and is familiar with the FactoryLink Programmer’s Access Kit portion of this manual.

RAPD PAK OVERVIEWInstallation


•

•

•

•

INSTALLATION

The following files are on your system after installing the software components:

• {FLINK}\SRC\RAPD\IMX_PAK\INC\IMX3.H

• {FLINK}\SRC\RAPD\IMX_PAK\INC\FORMAT3.H

• {FLINK}\SRC\RAPD\IMX_PAK\LIB\IMX3.LIB

{FLINK} designates which FLINK environment setting or directory the FactoryLink system software has been installed in.

The current version of IMX PAK is 3.0.

You must also have the FactoryLink Programmer’s Access Kit installed. Your driver will not compile or link properly without FactoryLink PAK.


• • • •

15

RA

PD

Prin

ciple

Chapter 15

RAPD Principle

The RAPD Principle is based on FactoryLink mailbox communications. RAPD involves at least two tasks. The I/O translator (IOX) and a protocol driver task developed using the IMX library.

The two tasks communicate with one another via FactoryLink mailbox tags. The IOX task makes requests upon the driver task to send and fetch data to/from a device, such as an RTU or PLC. The driver task concerns itself only with communicating with an external device. The IOX task provides all data conversions and tag storage.

All data is based on dataset definitions. These datasets define contiguous regions of data within an external device. The IOX task and a protocol driver task pass datasets through their respective mailbox tags. Data is directly packaged and unpackaged within a dataset.

IMX specifications and APIs define the method for processing datasets.

The following figure illustrates the RAPD principle with the IOX task and protocol driver communicating via FactoryLink mailboxes.

RAPD PRINCIPLE


•

•

•

•

Aside from storage duties, the IOX task provides for data conversions (analog to float, IEEE conversions) for I/O data to/from a protocol driver.

Compiling with the IMX library

When compiling your program with the IMX library, you must define the data direction (byte ordering) on the platform you are using. This is achieved by the following compiler directive:

FLAGS =...-DHOST_LOW_2_HIGH (used in the CFLAGS environment definition)

or

#define HOST_LOW_2_HIGH (used within a C header file)

For example, if your host machine uses an INTEL processor or compatible processor, data is stored in LOW/HIGH format. You should then specify -DHOST_LOW_2_HIGH in the CFLAGS directive or use a #define HOST_LOW_2_HIGH in your header file.

At run time, the IMX library makes the appropriate data conversions when using the data format functions. Failure to define the correct data direction at compile time results in incorrect data placement.

The RAPD Principle


• • • •

16

IMX

Messag

ing

Chapter 16

IMX Messaging

This chapter discusses how the IOX task and a RAPD driver task communicate using the IMX APIs by detailing the messaging scheme. Topics include:

• Mailbox Communications

• Datasets

• I/O Functionality

• Exception Write Function

• Data Directions

• IMX and LANS

A RAPD protocol driver and the IOX task communicate via FactoryLink mailboxes using the IMX interface library. This process includes:

1 The IOX task translates I/O data bidirectionally to a protocol driver in the form of IMX messages.

2 The protocol driver translates these requests into protocol messages to an external device.

3 Then, based on the results from the external device, the protocol driver responds via an IMX message to the IOX task.

The method of creating, setting and extracting the message parameters are facilitated through the various IMX function calls.

IMX MESSAGINGMailbox Communications


•

•

•

•

MAILBOX COMMUNICATIONS

The IOX task and a RAPD protocol driver communicate through FactoryLink mailbox tags. The mailbox API functions only accept the MBXMSG data structure. This data structure contains user definable members with specific definitions. The following defines the generic FactoryLink MBXMSG data structure:

typedef struct _MBXMSG /* client mailbox message */

{

MSG mm_msg; /*actual message to be sent */

/* (refers to message data) */

TAG mm_mbx; /* source mailbox (usually owned

/by sender of this message) */

u16 mm_type; /message type (for translation */

/to and from canonical form) */

u16 mm_user1; /* reserved for sender & receiver */

/* (usually message subtype) */

u32 mm_user2; /* reserved for sender & receiver */

/* (usually sequence number) */

id_t mm_sendid; /* task id of sender */

}MBXMSG;

The structure contains the following user definable members:

mm_msg This parameter is a standard message type MSG. This parameter must always be specified with a pointer to a user buffer for sending or receiving data together with the length of the buffer.

mm_mbx This parameter contains a valid mailbox tag. A mailbox user may specify a mailbox tag when sending. The receiving task may use this mailbox tag to send a response message back to the original sender.

mm_type

mm_user1

mm_user2 These three parameters are user definable.

mm_sendid This parameter must always be set with the task ID of the owner of the mailbox, which means the sending task specifies its own task ID.



16

IMX

Messag

ing

Every task using mailbox communication under FactoryLink uses the MBXMSG structure and assigns its own meaning to the user definable members.

Caution: Do not directly access structure elements when using the IMXPAK.

The IMXPAK always accesses IMX structures via macros or functions.

The sub-sections that follow describe the members of the MBXMSG structure.

mm_msg

The mm_msg parameter of the MBXMSG structure stores a data header in front of the data to send (I/O data). The length of this header is 8 bytes. This means the programmer must always reserve the first 8 bytes of the message buffer for a header area.

Therefore, the mm_msg data member is a structure that includes a data header of structure type IMXHDR followed immediately by some I/O data. The size should be at least 8 bytes plus the size of the I/O data to pass.

The layout of the header is defined in the following structure:

typedef struct _IMXHDR {

struct { /* structure with info of dataset */

unsigned version: 4; /*version of IMX used */

unsigned handling: 1; /* encoded or normal write */

unsigned reserved0: 3; /* reserved */

unsigned bnd_dir: 1; /* direction of data */

unsigned bit_dir: 1; /* direction of data */

unsigned bnd_start: 1; /* start of boundary data */

unsigned bit_start: 1; /* start of bit data */

unsigned boundary: 4; /* boundary of basic data element */

} i;

ushort len; /* length of data */



•

•

•

•ushort start; /* start address of data */

ushort cde; /* conversion code */

}IMXHDR;

Following is a description of each member of the IMXHDR structure:

version Specifies the version of the IMX library currently used. The current version is ver 3.0 and is used for compatibility reasons.

handling Specifies the writing mode of the current data in the IMX message. The receiving task uses this information for accessing the external device. The handling can be either a normal or encoded write. Refer to “I/O Functionality” on page 415 for information about the difference between a normal and encoded write.

bnd_dir Specifies the direction of the data on an element boundary. External devices can have different directions of ordering their data in native format. Usually this depends upon what kind of CPU the device is using.

For example, on a personal computer using an INTEL processor, the ordering of the bytes within a word is from low to high (LSB first, MSB second) whereas a Siemens PLC orders its bytes within a word from high to low (MSB first, LSB second). In this case, the LSB bytes must be switched with the MSB bytes to get the right value for data coming into the PC from the device. For outgoing data from the PC, the LSB/MSB pair must be switched to meet the MSB/LSB requirement in the Siemens PLC.

bit_dir Specifies the direction of single bits of a boundary element. The principle of the direction for bits is the same as described in the bnd_dir parameter.

bnd_start Specifies the offset of addressing in the external device for boundary elements.

bit_start Specifies the offset of addressing for bits within a boundary element.

boundary Specifies the boundary of addressing in the dataset. Every external device has one or more data types that are read or written through the protocol. A specific data type has a method of addressing single elements within a dataset. This method specifies the minimal size of an element that can be addressed. This size is called the boundary of that specific data type.

For example, a data type in an external device must be addressed on the size of words. Address 1 specifies the first word, address 2 the second word. This means this data type has a word boundary, and a word is the smallest element that can be read or written.



16

IMX

Messag

ing

len Specifies the length of the data in the current command. The length of the data must be specified in the number of elements according to the boundary of the data type.

start Specifies the start address of the data in the external device.

CDE Means code extension and specifies the operation code that should be taken upon the data. An IMX data header always specifies the operation on the data that must be taken. The following CDE identifiers are a sample of the possible operational codes:

CDE_B0_15 Bit operation bit 0 - 15

CDE_B16_3 Bit operation bit 16- 31

CDE_NIBBLE Nibble operation

CDE_BYTE Signed byte operation

CDE_UBYTE Unsigned byte operation

CDE_SIGNED Signed word operation

CDE_UNSIGNED Unsigned word operation

CDE_UBCD Word BCD operation

CDE_LONG Signed long operation

CDE_ULONG Unsigned long operation

CDE_LBCD Long BCD operation

CDE_SIEMENS_FLT Siemens floating point operation

CDE_SINGLE_IEEE_FLT IEEE single precision floating point operation

CDE_DOUBLE_IEEE_FLT IEEE double precision floating point operation

CDE_BLOCK Block operation on data

CDE_STRING String operation

These codes are used primarily for exception write cases (except CDE_BLOCK). In an exception write example, a CDE_UNSIGNED code could be used to specify a write of a single unsigned word. The receiving task (driver) would then generate a command according to the specific protocol to write the single word.

The code CDE_BLOCK is used for block operations.

For example, if the mm_type data member of the MBXMSG structure indicates an IMX_READ_REQ(and the CDE is CDE_BLOCK, the driver performs a block read operation. Refer to “I/O Functionality” on page 415 for details about CDE codes.



•

•

•

•Operations Codes (Extensions (CDE) )

The CDE operation codes are used in case of an exception write (normal or encoded) to specify which action the write must take. CDE codes are built up with a base CDE code and an additional bit number to specify the exact operation.

For example, the base CDE code for bit manipulations is 0x0100. The final CDE code will be 0x0103 if an operation must be completed on bit 3.

The IMX library defines the following base CDE codes.

CDE Definition CDE Description

CDE_B0_15 0x0100 Bit manipulations bit 0-15

CDE_B16_31 0x0110 Bit manipulations bit 15 - 31

CDE_NIBBLE 0x0300 Nibble manipulations

CDE_BYTE 0x0400 Signed byte manipulations

CDE_UBYTE 0x0500 Unsigned byte manipulations

CDE_SIGNED 0x0600 Signed integer manipulations

CDE_UNSIGNED 0x0700 Unsigned integer manipulations

CDE_UBCD 0x0780 Short BCD manipulations

CDE_ULONG 0x0800 Signed long manipulations

CDE_LBCD 0x0900 Unsigned long manipulations

CDE_ULONG 0x0980 Long BCD manipulations

CDE_LBCD 0x0A00 Siemens float manipulations

CDE_SIEMENS_FLT 0x0A80 IEEE single floating point manipulations

CDE_SINGLE_IEEE_FLT 0x0B00 IEEE double floating point manipulations

CDE_BLOCK 0x0C00 Block data manipulations

CDE_STRING 0x0C80 String manipulations



16

IMX

Messag

ing

For example, the following code must be specified if an operation must be performed on the left byte of a variable of type u16:

CDE_UBYTE + 8 (bits) = 0x0508

mm_type

The definition of the mm_type member of the MBXMSG data structure is as follows:

typedef struct _IMXTYPE {

unsigned type: 4; /* type of IMX message */

unsigned ident: 1; /* use of MSG CTRL tag or address */

unsigned more: 1; /* more data to come: yes or no */

unsigned org_host_dir: 1; /* set the originating host direction */

unsigned reserved: 1; /* reserved */

unsigned station_id: 8; /* originating station id of message */

}IMXTYPE;

The type parameter specifies what kind of IMX message is being sent or received. The following types are available:

IMX_QUERY_CMD /* IMX info message */

IMX_QUERY_RSP /* IMX info message feed back */

IMX_QUERY_ERROR /*IMX info message feed back */

IMX_READ_REQ /* read request */

IMX_READ_RSP /* read feed back */

IMX_READ_ERROR /* read feed back */

IMX_WRITE_REQ /* write request */

IMX_WRITE_RSP /* write feed back */

IMX_WRITE_ERROR /* write feed back */



•

•

•

•IMX_RCV_ACT /* unsolicited receive active */

IMX_RCV_RDY /* unsolicited receive ready */

IMX_RCV_ERROR /* unsolicited receive ready */

ident Parameter in the IMXTYPE structure that specifies whether a dataset control tag is used. This element is not used anymore and is still specified for compatibility reasons with older versions of the IMX library.

more Element used for specifying consecutive messages data must be contiguous in. This element is not currently used.

org_host_dir Specifies the data direction of the originating host and is used internally by the IMX library for converting the IMX header.

station_id Element specifies the remote station in case messages are sent over a LAN.

mm_user1

The layout of the mm_user1 parameter for the IMXMSG structure is defined as follows:

u16 mm_user1 ----> job sequence number

This data member holds a job sequence number used to keep track of messages from one task to another. A programmer is not obligated to make use of this data member.

mm_user2

The layout of the mm_user2 parameter for the MBXMSG structure is defined as follows:

u32 mm_user2 ----> dataset control tag

This data member holds the dataset control tag used to identify a block of data being exchanged between two IMX tasks. This parameter must always be specified whenever sending an IMX message.

IMX MESSAGINGDatasets


16

IMX

Messag

ing

DATASETS

The previous section describes the data structure of the mailbox message. This section discusses the dataset information that goes into the mailbox message.

The concept of a dataset is key to understanding how a RAPD driver interacts with the IOX task. The following subsection discusses datasets from the perspective of an application. Refer to “I/O Functionality” on page 415 for details about the use of datasets as they pertain to specific IMX messages.

Dataset Definition

A dataset for an application is defined as a contiguous area of storage location within an external device. These locations are sometimes referred to as memory locations, registers, addresses, files, or regions. The exact terminology is dependent on the type of device. The protocol driver uses a dataset definition as the key to either read or write data from/to an external device.

Transactions between the IOX task and a driver are based on passing dataset information back and forth between the tasks. If the IOX task has a request for a protocol driver to act on a WRITE operation, it defines some dataset parameters in a message to the driver. The driver receives the message and, according to the dataset information received, carries out the directive.

Datasets Defined in an Application

A dataset is defined as a FactoryLink digital tag in a driver’s Dataset Definition panel. It is then referenced in the IOX Tag Definition panel.

A driver’s Dataset Definition panel includes the following:

• Mailbox tag identification

• Start address (first element to access for the dataset)

• Length specifier (number of contiguous elements to access)

• Associated completion tags for the operation (READ, WRITE, UNSOLICITED)

The following graphic displays an example of a dataset definition within a driver’s Dataset Definition panel (the driver used in this example is called Widget).



•

•

•

•

The following IOX Dataset Definition panel shows a reference to the same dataset defined in the driver Dataset Definition panel. The data collected on the dataset is stored in the tag defined in the Data Tag field.

In this case, it is a tag array that stores 20 consecutive elements starting with the element at address 1. Therefore, if a READ request occurs on the dataset analog_ds[0], 20 consecutive elements, residing in the external device, starting at address 1 are stored in widget_analogs[0] (element at address 1, element at address 2, element at address 3 … element at address 20).

For purposes of this illustration, the elements being collected on this dataset are all analog type data (16 bits wide). They are stored in analog tags when read. The data comes from the same analog tags when written to the external device.



16

IMX

Messag

ing

There are other fields in the same IOX panel, but they are explained in detail in the I/O Translator information on the documentation CD.

Passing and Processing a Dataset

The following steps outline passing and processing a dataset:

1. The IOX task determines a READ or WRITE trigger has occurred for a referenced dataset

• The IOX task creates a mail message and sets certain parameters in the message based on the given dataset.

• The message is mailed to the driver owning the dataset.

2. The driver detects an IMX event on the dataset and the mail message is received.

• A protocol message is built on the dataset parameters defined in the message by the IOX task.

• The driver sends the message to the external device.

• The device sends a response back to the driver.

• The driver packages a response message to the IOX task, which may or may not include data received from the device, by setting some parameters on the dataset and mails a message to the IOX task.

3. The IOX task detects a response event from the driver.

• If the response contains data from a device (a result of a READ request), depending on the conversion settings, the data may be converted or directly stored into the designated tags.



•

•

•

•The following depicts the flow of a dataset from the IOX task to the protocol driver.

I/O Translator

Protocol Driver

3

2

dataset translated intoprotocol messages

exchange ofprotocol messages

data returned inmail messagefrom the driver

1mail message containing

dataset information the drivermust know to operate on

FactoryLinkWorkstation

External Device(RTU, PLC)

The external device may have internal regions allocated fordata storage dedicated to certain data types. For example, thisexternal device may have address regions reserved for analog(16 bit words) data.

Therefore, to gain access to 100 consecutive analog addresses,starting at address 10, a dataset would be defined in theapplication with starting address of 10 and length of 100. Whenthe dataset is used in say a BLOCK READ operation, addresses10, 11, 12, 13, ..., 99, 100 will be accessed.

IMX MESSAGINGI/O Functionality


16

IMX

Messag

ing

I/O FUNCTIONALITY

You implement the following common functions for external device drivers with the IMX interface library:

• Block read function

• Block write function

• Exception write function

• Encoded write function

• Unsolicited receive function

Every task that implements IMX functionality has an IMX mailbox. Different IMX tasks that communicate with each other write IMX messages into each other’s IMX mailboxes.

For example, both the IOX task and the protocol driver have their own IMX mailbox tag. If the IOX task wants to address a command to the protocol driver, it writes a message in the protocol driver mailbox.

The following sections discuss the common functions supported by the IMX library. The examples give you an idea of how the messages are constructed so they can be decoded and a driver can respond to them.

Before discussing the various request functions, note that the IOX task performs a query of all datasets from protocol drivers at startup. The query function Imx_Ds_Query( ) (used only by IOX tasks) is automatically answered by the IMX library event check routine in a driver.

The original dataset definitions must be retrieved at startup because this IOX task completely defines the dataset parameters in an IMX message to a driver. Since tasks can span a network, this information eases the burden on a driver from having to constantly retrieve a dataset’s original definition.

The Block Read Function

A block read means the IOX task generates a request for the protocol driver to read a complete dataset (first element to last element) defined in the protocol driver.

The layout of the MBXMSG structure for a block read request is as follows:

Block Read Request

mm_msg.m_ptr = pointer to message buffer containing only an IMX data header

mm_msg.m_max = not applicable

mm_msg.m_len = length of the size of IMX data header



•

•

•

•mm_mbx = IOX mailbox (reply mailbox)

mm_type.type = IMX_READ_REQ

mm_type.ident = IMX_TAG

mm_type.more = Not applicable

mm_type.ident = local host direction

mm_type.station_id = local station id

mm_user1 = Job sequence number

mm_user2 = dataset control tag

mm_sendid = IOX FactoryLink Task ID

The layout of the data header structure for a block read request is displayed as follows (the header is the part of the message buffer pointed to by mm_msg.m_ptr in the preceding figure):

Data Header for a Block Read Request

version: = 3

handling: = not applicable

bnd_dir: = IMX_HIGH_2_LOW

bit_dir: = IMX_HIGH_2_LOW

bnd_start: = 0

bit_start: = 1

boundary: = IMX_WORD_BND

len; = 80

start; = 10

cde; = CDE_BLOCK



16

IMX

Messag

ing

After the block read request is sent to the driver, the driver creates a protocol message based on the header data and then responds to the IOX task with data collected from the device. The response looks similar to the following:

Block Read Response MBXMSG Structure

mm_msg.m_ptr = pointer to a message buffer (contains an IMX data header + data)


mm_msg.m_len = length of received data including the IMX data h

mm_mbx = not applicable

mm_type.type = IMX_READ_RSP


m_type.more = not applicable

mm_type.org_host_dir = originating host data direction

mm_type.station_id = remote station id




Block Read Response Data Header (IMXHDR)

version: = 3


bnd_dir: = IMX_HIGH_2_LOW


bnd_start: = 0

bit_start: = 1


len; = 80

start; = 10

cde; = CDE_BLOCK



•

•

•

•Data Retrieved

data

.

.

.

.

.

data

data

The IOX task reads this message from its own mailbox and analyzes the received data. The length of the received data is located in the mm_msg.m_len member of the MBXMSG structure. This member contains the total number of characters received, including the data header.

In this example, the block read was successful. If the protocol driver encounters an error while gathering the data, it sends an error to the IOX task. The function Imx_Send_Error( ) can be used with Imx_Read_Error( ) as the error code parameter. The IOX task displays the error on the run manager screen.

When both the IOX task and a driver exist on the same machine, a block read request is expedited through a direct trigger of the targeted dataset with no mail exchanged.

Over a LAN, the IOX task sends a mail message containing a block read request. For a driver, the IMX library hides the method the request is delivered in. In either case, the block read request is handled by the driver in a common manner.

Block Write Function

You can write a contiguous block of data with one command to the external device with the block write function. The IOX task generates a block write request for the protocol driver by gathering and formatting the data and generating an IMX message. The data gathered is from tags from the FactoryLink real-time database. The following IMX message is an example of a block write request from the IOX task:

Block Write MBXMSG Structure

mm_msg.m_ptr = pointer to a message buffer (contains an IMX data header + data)


m_msg.m_len = length of data to send inc. IMX data header



16

IMX

Messag

ing

mm_mbx = IOX mailbox tag

mm_type.type = IMX_WRITE_REQ


mm_type.more = not applicable

mm_type.org_host_dir = local host data direction





Block Write Response Data Header (IMXHDR)

version: = 3

handling: = IMX_NORMAL_WRITE

bnd_dir: = IMX_LOW_2_HIGH


bnd_start: = 0

bit_start: = 0


len; = 80

start; = 10

cde; = CDE_BLOCK

Tag Data To Output

data

.

.

.

.

.



•

•

•

•data

data

The driver extracts the information from the header area as well as the accompanying tag data to create a protocol message to send to the device.

The response from the driver to the block write request from the IOX task is in the following form:

Block Write Response MBXMSG Structure

mm_msg.m_ptr = pointer to a message buffer (contains only an IMXHDR structure)


mm_msg.m_len = length of the IMX data header

mm_mbx = not applicable

mm_type.type = IMX_WRITE_RSP



mm_type.org_host_dir = originating host direction

mm_type.station_id = remote station id




Block Write Response Data Header (IMXHDR)

version: = 1




bnd_start: = 0



16

IMX

Messag

ing

bit_start: = 0


len; = 80

start; = 10

cde; = CDE_BLOCK

Use Imx_Write_Error( ) as a parameter on a call to Imx_Send_Error( ) if an error occurs on the write operation. The IOX task displays the error on the run-time manager screen.

IMX MESSAGINGException Write Function


•

•

•

•

EXCEPTION WRITE FUNCTION

There are two types of exception writes:

• Normal exception writes

• Encoded exception writes

Normal Exception Write

Single elements of different types within a dataset can be written directly to the external device using a normal exception write. The IOX task generates an IMX message with the single element specified. The message from the IOX task is displayed looking similar to the following:

Exception Write Request MBXMSG Structure

mm_msg.m_ptr = pointer to a message buffer (contains a data header (IMXHDR) + data)


mm_msg.m_len = length of data to send inc. IMX data header

mm_mbx = IOX mailbox tag

mm_type.type = IMX_WRITE_REQ








Exception Write Request Data Header (IMXHDR)

version: = 3





16

IMX

Messag

ing


bnd_start: = 0

bit_start: = 0


len; = not applicable

start; = 27

cde; = CDE_BYTE

The exception write IMX message differs from the block write message in that the operation code CDE specifies what kind of write should be performed. The length of the data is not specified because an exception write always implies only one element is to be sent. The CDE code implies the data size of the element itself. In the preceding example, a byte of data is written to a word area.

Sometimes writing out the data cannot be accomplished in one operation. In the case of writing a data element that is a byte (8 bits) to an area in a device that has a word boundary (16 bits), it may take two operations. The device protocol may not support direct byte operations, so the solution is:

• Read the word area

• Patch in the byte value

• Write out the word to the device

After the driver has carried out the write operation, it responds to the IOX task in the same manner as in a response to a block write. You can test for an exception write request to see if it can be transformed into a normal block write. Being able to transform an exception write (read-before-write) to a block write reduces message traffic. This is determined by a call to Imx_ Ds_Evaluate_Write( ). The results of this function determine if the exception write can be converted into a block write.

Encoded Exception Write

The encoded exception write function is the same as the exception write function but differs in that it does not directly write to the element in the external device. The definition of the IMX message is exactly the same as described with the exception write function except the following member differs:

handling: = IMX_ENCODED_WRITE

The encoded write (also called coded) causes the driver to perform a block write. The block write is to an area in the device (PLC) that causes the device to perform an internal logic procedure to make a direct change of a desired data item. This function has been introduced because the exception write can be very slow for operations on data smaller than the boundary



•

•

•

•of the dataset. In the method for normal exception writes described previously, the element to manipulate must be read first, patched, and then written back. This is time consuming and results in an increase in message transactions.

The encoded write request is used if the C option is chosen in the IOX task under the Exception Write column. How one implements the encoded write feature in a driver depends on the protocol. The driver receives a message that would normally be sent as an exception write except the CDE code is different. The driver must extract the information and then create a block write message based on the extracted data.

With the encoded write, it is not necessary to first read and then write back the exception element. The operation on the element is written only once. The performance of exception write requests can be optimized using this method. For this function, the driver must be able to address a block of registers.

The information taken from the exception write request from the IOX task is written into the block of registers. When the block is sent out to the external device, the external device ladder logic performs the required operation based on data contained in the block write.

After the protocol driver has performed the exception write, it generates an IMX response message and sends it back to the IOX task. This is accomplished in the same manner as the block write function. An Imx_Write_Error( ) can be set in an Imx_Send_Error( ) function call in case an error occurs.

Unsolicited Receive Function

The requests discussed previously are activated by the IOX task. It is also possible for external devices to spontaneously send data to a FactoryLink station. This method of communication is the unsolicited receive function. The protocol driver receives the unsolicited data from a device and then sends the unsolicited data to the IOX task. The protocol driver generates the following message to the IOX task:

Unsolicited Receive Ready MBXMSG Structure

mm_msg.m_ptr = pointer to message buffer (contains a data header (IMXHDR) + data)


mm_msg.m_len = length of data to send inc. IMX data header

mm_mbx = protocol driver mailbox tag

mm_type.type = IMX_RCV_RDY


mm_type.more = Yes or No



16

IMX

Messag

ing


mm_type.station_id = local station id*



mm_sendid = protocol driver FactoryLink Task ID

Unsolicited Receive Ready Request Header (IMXHDR)

version: = 1




bnd_start: = 0

bit_start: = 0


len; = 20

start; = 27

cde; = CDE_BLOCK

Unsolicited Data

data

.

.

.

.

.

data

data

The IOX task receives this message, identifies the data with the dataset control tag, and processes the data.

A driver must qualify an incoming message by matching it against a defined dataset. It is inconsequential for a driver to send a message to the IOX task if no dataset is defined for it. If the incoming message has no dataset match, the message is rejected.



•

•

•

•If the protocol driver encounters an error while receiving unsolicited data, it sends an Imx_Rcv_Error( ) code in an Imx_Send_Error ( ) function to the IOX task. The IOX task displays the error on the run manager screen.

IMX MESSAGINGData Directions


16

IMX

Messag

ing

DATA DIRECTIONS

A very important issue with external devices and host machines is the direction of data. Problems occur whenever the direction of data of the host machine (where the driver is running) differs from the data direction of the external device.

For example, the data direction on the host can be from high to low and the external device direction from low to high. If a word (2 bytes) is being read from the device, the bytes of this word must be swapped. When a long data type is being read, then the bytes of this long data type must be reversed in order to get a readable value. The following figure illustrates this principle.

In IMXPAK, a group of defined data direction dependent functions are used to retrieve elements of variable size from a dataset. The following example shows how to use some of these functions:

#define HOST_HIGH_2_LOW

char buffer[ 256];

void *data = buffer;

if( Imx_Get_Bnd_Dir( &ds) == IMX_HIGH_2_LOW)

analog = Imx_Get_Word_H2L( data); /* device stores data in high to low format and the host machine uses high/low also no conversion is done*/

else

analog = Imx_Get_Word_L2H( data); /* device stores data in low to high format but the host uses high/low, bytes are swapped*/

I/O Translator Data Directions



•

•

•

•You must decide in the code which function to use at run time depending on the data direction of the external device data. At compile time, the source code also requires a decision on the data direction of the host. You determine this when making a program definition (PDEF) of HOST_HIGH_2_LOW or HOST_LOW_2_HIGH. This definition forces the compiler to insert different macros in the source code depending on the host data direction. These macros are listed in the file format3.h.

Combinations of CDE Code

The IMX specification defines the direction of data in all cases of communication (LAN and non-LAN). The direction definition can differ because of the combination of the CDE code and data boundary in an IMX message.

Data Header Direction

The data header is a special part of the message buffer and is always placed in front of the I/O data. The direction of the header is always in the data direction of the host platform where the software is running. This means if the IOX task and the protocol driver are running on the same system, no conversion is needed for the header structure. In the MBXMSG structure of an IMX message, Org_Host_Dir( ) is defined to specify the data direction of the originating host. If this data direction differs from the local host data direction, the header part must be converted. IMXPAK handles this automatically using the IMX library.

Block Data Commands

The block read and write functions operate with contiguous blocks of data. The CDE operation of the IMX message is always set to Cde_Block( ). In this case, the data direction always corresponds to the direction set in the IMX message and applies to the set boundary. The IOX task (sender of the IMX message) is responsible for ensuring the data is valid and corresponds to the direction set in the message.

Exception Data Commands

The CDE code influences the exception data operations.

For example, in an IMX message from the IOX task, the CDE code is set to Cde_Byte( ) (size is byte) and the boundary for the dataset is a word.

Two situations are possible for exception data messages:

• Size of the data the CDE code operates on is equal to or greater than the data boundary

• Size of the data the CDE code operates on is smaller than the data boundary

In the first case, the single exception element is either the same size or greater than the destination area. If the element is the same size as the destination area, the element can be



16

IMX

Messag

ing

written out as a simple block write operation (the IOX task automatically determines this for a driver).

If the element is greater than the destination area, as in the following figure, it is still considered a block write operation. This figure illustrates a byte ordering situation. The IOX task takes care of switching the data correctly for the driver. The driver assumes the data is adjusted correctly and does not have to make any conversions before writing it to the device.

In the second case, the CDE code defines a data element smaller than the destination area in the device.

For example, if a byte is to be written to a word area (16 bits) in a device, what byte (left or right) must the data be written to? The CDE code specifies the proper byte. If the left byte is the desired byte and it is unsigned, the CDE code is set to 0x0508 (CDE_UBYTE+8(bits)). The 8 signifies to start at bit 8 that gives bits 8 to 15, which is the left byte.

Converting IMX Messages

A protocol driver can receive an IMX message from an IOX task that differs from the defined dataset in data direction or boundary. The IMX message must be converted to meet the characteristics of the dataset. This is only done in the case of a send request from the IOX task to the driver because all datasets received from a driver to the IOX task can be forwarded as they are. The IOX task handles different data directions and determines the required conversions.

I/O Translator Exception Data Commands



•

•

•

•A driver should never convert the IMX message block data functions. For block operations, the protocol driver has no information about the data types (actual I/O data) the IOX task stores in the IMX message. Types can be greater than the dataset boundary, such as a long being written to a word area, and need more conversion. But the driver cannot correctly do the switching. Therefore, block write message requests received from the IOX task must match the corresponding dataset exactly; otherwise, the write message request cannot be sent to the external device. The IOX task takes care of this for the driver. In the case of response data resulting from a block read request, it is forwarded as is to the IOX task, and the IOX task performs the necessary conversions.

The exception write commands can usually be transformed in size. This is dependent on where the data has to be written or destination boundary in the external device as defined by the dataset.

The problem with exception writes is the dataset has to be read first (read-patch-write) because it may only be necessary to manipulate a portion of the dataset.

For example, after a read when a byte must be changed in a word, the byte value can be manipulated in the word then written back out to the device. Failure to perform a read operation as the first step may cause the other byte in the word to inadvertently get changed. Subsequently, read-before-writes result in an increase in message traffic.

The IMX library includes a function called Imx_Ds_Evaluate_Write ( ) to reduce read-before-write operations. This function determines whether a dataset can be written out in one message or if it requires a read-before-write. The function essentially checks the size of the data to write out against the data boundary of the area in the external device. If the CDE type is smaller than the data boundary, as in a CDE_BYTE operation for a dataset with a word boundary, then the word (u16) is cast down to a byte size. The result is the data now changes from a u16 to u8, essentially breaking down the word into a byte. The dataset can now be written out in one operation. It depends on the external device whether or not data can be reduced because reducing the data effectively or casting a word down to a byte causes a loss of data.

IMX MESSAGINGIMX and LANS


16

IMX

Messag

ing

IMX AND LANS

Two IMX tasks (the IOX task and a protocol driver) can run on different computers communicating with one another. Because the two computers can differ in data direction (different platforms), IMX supplies information specifying where the dataset came from and what kind of data orientation it has. The following elements of mm_type in the MBXMSG structure are used in case a message is sent over a LAN:



The org_host_dir element specifies the data direction of the originating host. Because the IMX header is always in the host format, this element is checked against the local host data direction. If they do not match, the IMX header must be converted to the local host data direction. The IMX library takes care of this conversion automatically; therefore, no code is required to be implemented in a protocol driver to handle this.

The station identification is a unique number of the host station on the LAN. The user must assign this number and keep it unique over the LAN. The station identification can be passed to the driver task as a program argument. You can use the station id number for checking if a message did or did not originate over a LAN.

If tasks are to support communications over a LAN, some information must be exchanged between the tasks before they can begin communications. The tasks are probably running on separate nodes in two different FactoryLink applications, which means all tag ids are most likely not consistent. IMX uses the dataset control tag for identification of the dataset. But, if a problem prevails, the dataset control tags cannot be exchanged as they exist because the remote application does not recognize the dataset control tag.

To resolve the problem, dataset information must first be exchanged between the tasks by the IOX task using the Imx_Query_Cmd( ) function. This function is used to retrieve all information about a dataset. The receiving task, usually a protocol driver, responds to the request. The IMX library handles this automatically for a driver, so you need not implement code to do this.

Once the information about the dataset control tags have been exchanged, further communications between the tasks is possible. You must perform a dataset registration in order to link the local and remote datasets. The IMX library does this automatically for the developer. The only requirement for developing a task for use with the FactoryLink LAN is to execute a query command at start-up for every dataset used (the IOX task automatically does this). The IMX library transparently handles all further requirements needed for LAN communication.

IMX MESSAGINGIMX and LANS


•

•

•

•


• • • •

17

Writin

g a R

AP

D D

river

Chapter 17

Writing a RAPD Driver

This chapter discusses the road map to designing a protocol driver using the IMX libraries. The following outlines the basic flow of code for any driver:

1. Initialize the driver task as a FactoryLink task.

2. Make system setup calls to the IMX library.

3. Make an initialization call to the IMX library.

4. Define the characteristics of each data set and register them one at a time.

5. Go into the main loop of the program and check for IMX events. The loop terminates when it detects the task is to terminate.

6. Make a call to exit the IMX library services after the loop terminates.

Sample code listing is as follows:/* This program details example source code of a protocol driver that will setup a (one) dataset, register the dataset and then wait for IMX events on the dataset.

*/

char buf[ 256]; /* global receive buffer */

int process_ds(IMXDS *); /* prototype of user event function for dataset */

int main(){

IMXDS ds, /* IMX temporary dataset for passing information */

*reg_ds; /* pointer to the final registered dataset */

MORE_INFO more_info; /* additional information associated with the dataset */

IMXSYSTEM sys; /* IMX system information structure */

TAG iox_mbx, /* IOX task’s IMX mailbox */

protocol_mbx, /* protocol driver task’s IMX mailbox */

ds_ctrl; /* dataset control tag */

MSG b; /* buffer parameters */

/*set this task up as a FactoryLink task */

task_id = ...............etc

/* set the specific system parameters required by IMX of this task */

WRITING A RAPD DRIVER


•

•

•

•Imx_Sys_Set_Task_Id(&sys, task_id);

Imx_Sys_Set_Station_Id(&sys, 0); /* use if using the LAN feature */

Imx_Sys_Set_Mbx(&sys, protocol_mbx);

Imx_Sys_Set_Functions(&sys, IMX_ALL_FNC);

/* initailize the IMX */

if(Imx_Init(&sys) != GOOD) exit(1);

/*only one dataset will be defined in this example, of course you may have many more datasets in your task */

/* set all characteristics of the dataset before registering */

b.m_ptr = buf;

b.m_max = 256;

Imx_Set_R_Buffer (&ds,b); /* create the default buffer */

Imx_Set_T_Buffer (&ds,b); /* create a temporary buffer */

Imx_Set_Ds_Ctrl (&ds,&ds_ctrl); /* set the dataset control tag /

Imx_Set_Name (&ds, “Control_Tag”); /* set the tag name as listed in the FL RTDB */

mx_Set_Snd_Mbx ( &ds, iox_mbx); /* IOX driver mailbox to send cmd /

mx_Set_Boundary ( &ds, IMX_WORD_BND); /* this dataset pertains to data that exists on a word boundary (i.e. 16 bit word) */

Imx_Set_Bnd_Dir ( &ds, IMX_HIGH_2_LOW); /* every word is stored in the device in HIGH to LOW format*/

Imx_Set_Bit_Dir ( &ds, IMX_HIGH_2_LOW); /* bits in a word in the device are stored in HIGH to LOW format */

Imx_Set_Bnd_Offset ( &ds, 0); /* boundary offset starts at 0 */

x_Set_Bit_Offset ( &ds, 0); /* bit offset starts at 0 */

Imx_Set_Start ( &ds, 10); /* first element in this dataset resides at address 10 in the device */

Imx_Set_Len ( &ds, 20); /* there are 20 contiguous elements for this dataset, address 10, 11, 12,..., 29 */

Imx_Set_Udata ( &ds, ( void *)&more_info); /* attach the more information structure to this dataset more_info would have been set with some supplemental information that

may be used with this dataset (i.e. device station id, port, etc.... this is up to the developer to assign any supplemental information.*/

Imx_Set_Ufnc ( &ds, process_ds); /* call back function that will be invoked whenever an event occurs on this dataset. */

/* register this information to the IMX and receive a pointer to the registered dataset */

if( ( reg_ds = Imx_Ds_Register ( ds)) != GOOD) exit( 0);



17

Writin

g a R

AP

D D

river

/* go into the main task loop */

while ( fl_test_term_flag( ..... ) /* continue to loop until the task has been terminated */

{

/* call the check event function of IMX on a polling basis */

if( Imx_Event_Check() == GOOD) {

/* do additional processing and other tasks here (i.e. check for unsolicited messages coming in) */

.............................

}

fl_sleep(1000); /* let other tasks have a chance to run */

}

Imx_Exit();

exit( 0);

end program */

The function Imx_Set_R_Buffer( ) is called to establish a default message buffer. This message buffer is used for defining the IMXHDR and I/O data parameters in a message. This message buffer is used over and over. In order to call up the use of the default buffer later, call the function Imx_Ds_Prepare( ).

You define a temporary message buffer other than the default buffer by making a call to Imx_Set_T_Buffer( ). In the example, a temporary buffer is used because, although the default buffer was previously defined, it was not set as the current message buffer. The subsequent IMX calls (Imx_Set_( )) require a message buffer to be defined. If this is not done, the program attempts to write to an unallocated memory block.

Setting the dataset tag name has to be extracted from the CT record of the dataset. The example included here has the name hard coded as Control_Tag.

The polling method (Imx_Event_Check( )) is used in a driver because the driver may have to perform other duties, such as check its communications port for incoming or unsolicited data.

Arriving events are always per single dataset. They do not come in groups or as lists; therefore, every event is processed in a first-come-first-served order. Every event that occurs corresponds to a single dataset. When a dataset event occurs, the procedure you defined is invoked. That procedure operates on the dataset accordingly.

The sample code shows a single dataset. A typical driver has to support more than one dataset, so each must be setup according to each dataset CT record and then registered with the IMX library one at a time. The dataset information in the sample code does not show that it came from a CT record. In an actual driver, the dataset CT records are used as the source for characteristics of a dataset.



•

•

•

•The following sample illustrates the function you designed to call for a block read event for the dataset:.

./** Example of user event function. This is automatically called by the IMX library when a dataset this function is defined for has an event active for the dataset.

*/

int process_ds( IMXDS *ds); /* user event function for dataset */

MORE_INFO more_info; /* supplemental information for a dataset */

char cmd[256], respdata[256];

int len;

/* check what kind of message has been received */

switch( Imx_Get_Type( ds) ) {

case IMX_WRITE_REQ: ...........

break;

.

.

case IMX_READ_REQ: /* block read operation */

/* retrieve the pointer to supplemental dataset information, this could be information such as CT data associated with the dataset or any other info you like.*/

more_info = Imx_Get_Udata_Ptr( ds);

/* read the request from the mail queue */

if( Imx_Recv( ds) != GOOD) ......../* handle the error */

/* initiate the read command for this dataset on the external device */

build_cmd(ds, &cmd); /* build the protocol cmd msg to perform the block read */

query_device(&cmd, &respdata, &len); /* query the device (send the message) */

bld_IOX_resp(ds, respdata); /* build response to IO translator */

Imx_Send(ds); /* send response to block read request to the IOX*/

break;



17

Writin

g a R

AP

D D

river

default:

..........

break;

}

return GOOD;

}

Typically, for every dataset, a single user defined procedure is defined. The procedure should handle any kind of event possible on a single dataset.

IOX - Driver Communications

Once the IOX task sends a request to a driver, the driver must respond positively or negatively. The IOX task does not keep track of outstanding requests to a protocol driver. If an error carrying out an IOX request occurs, such as while sending a command to a device, I/O errors occur, Imx_Send_Error( ) notifies the IOX task of this error.

The IOX task does not have to prompt (block and exception requests) drivers for data. Drivers may also send unsolicited messages (messages sent by an external device on its own) to the IOX task.

WRITING A RAPD DRIVERError codes


•

•

•

•

ERROR CODES

The IMX library returns error codes in the range as listed in the following tables. The first table is exactly the same as the standard FactoryLink error codes.

Standard FactoryLink Errors

Error Number Description

1 Internal error.

2 Out of memory.

3 Operating system error.

4 Initialization not successful.

5 Initialization not successful.

6 Incorrect function.

7 Incorrect argument.

8 Incorrect data.

9 Bad data.

10 Null pointer assignment.

11 Change flag not set.

12 Procedure table full.

13 Bad procedure name.

14 Bad user name.

15 Bad option.

16 Incorrect check sum.

17 No options.

18 No key.

19 Bad key.



17

Writin

g a R

AP

D D

river

20 No port available.

21 Port busy.

22 FL already active.

23 No lock.

24 Lock failed.

25 Lock expired.

26 Wait failed.

27 Termination flag set.

28 Q-size too big.

29 Q-size changed.

30 No tag list.

31 Tag list changed.

32 Wake up failed.

33 No signals.

34 Signaled.

35 Not a mailbox.

36 No messages.

37 Access denied.

38 Attribute failure.

39 Invalid attribute.

40 Attribute not defined.

41 Application exists.

42 RTDB does not exist.




•

•

•

•

43 No task bit.

44 Not a lite task.




17

Writin

g a R

AP

D D

river

Intertask Mail Exchange Errors


50 Bad message type.

51 Message with dataset control tag not found in queue.

52 No messages available to query.

53 Bad receive mailbox tag.

54 Bad mailbox send tag.

55 Bad dataset control tag.

56 Message cannot be adjusted.

57 Operation too big for variable.

58 Unknown boundary.

59 Function not supported.

60 No message for this index present.

61 Received remote dataset was not defined on this system.

62 Received dataset was not registered.

63 WARNING: message is not queued.

64 Message is rejected because of problems in the remote IMX.

65 Illegal method of addressing bits on bit boundary.

66 Element cannot be written at once; read before writing.



•

•

•

•


• • • •

18

IMX

Referen

ce Gu

ide

Chapter 18

IMX Reference Library

The functions in IMX are divided into different categories depending on the operation to be performed. This chapter lists all IMX functions in these categories.

Caution: Functions listed with an asterisk (*) should not be used directly in a RAPD task because the IMX library uses them internally.

General IMX Functions

Global FunctionalityImx_Init Initializes the IMX.

Imx_Exit Exits the IMX.

Imx_Recv Receives a IMX message from the IMX mailbox.

Imx_Send Sends an IMX message to a IMX mailbox.

Imx_Send_Error Sends an error response depending on type of message.

Imx_Mirror Reverses data.

Imx_Place_Data Places data on the exact spot within an element.Imx_Get_CDE_Size Gets the size in byte of a CDE type.

Imx_Buffer_Alloc Allocates a buffer for use with IMX.

Dataset FunctionalityImx_Ds_Register Registers a dataset to the IMX.Imx_Ds_Prepare Loads the default parameters of a dataset.

Imx_Ds_Query Sends a query command of the dataset to the remote task.Imx_Ds_Remove Removes all datasets with same id from the mailbox queue.Imx_Ds_Trigger Triggers a dataset for reading by the protocol driver.

Imx_Ds_Evaluate_Write Checks and converts the dataset for exception writing.

Event FunctionalityImx_Event_Retrieve Gets the event arrays for true event driven processing.

Imx_Event_Check Checks for IMX events on a polled basis.

IMX REFERENCE LIBRARY


•

•

•

•Queue Functionality

*Imx_Q_Init Initializes the queue at start up of IMX.Imx_Q_Num Determines the number of messages in the queue.

Imx_Q_Query Queries a message with index x in the mailbox queue.Imx_Q_Ds_Srch Searches for the dataset in the mailbox queue.

IMX Header Functions (IMXHDR)Imx_Get_Version Gets the version of the IMX.

*Imx_Set_Version Sets the version of the IMX.Imx_Get_Handling Gets the writing mode of this dataset.Imx_Set_Handling Sets the writing mode of this dataset.Imx_Set_Bnd_Dir Sets the data direction of boundary data.Imx_Get_Bnd_Dir Gets the data direction of boundary data.

Imx_Set_Bit_Dir Sets the data direction of bit data.

Imx_Get_Bit_Dir Gets the data direction of bit data.Imx_Set_Bnd_Offset Sets the data offset addressing of boundary data.

Imx_Get_Bnd_Offset Gets the data offset addressing of boundary data.Imx_Set_Bit_Offset Sets the bit offset addressing of bit data.

Imx_Get_Bit_Offset Gets the bit offset addressing of bit data.Imx_Set_Boundary Sets the boundary of the data.Imx_Get_Boundary Gets the boundary of the data.

Imx_Set_Start Sets the start address of the data.Imx_Get_Start Gets the start address of the data.

Imx_Set_Len Sets the length of the data in boundary elements.

Imx_Get_Len Gets the length of the data in boundary elements.Imx_Set_CDE Sets the operation code of the write function.Imx_Get_CDE Gets the operation code of the write function.

IMX System Functions (IMXSYS)Imx_Sys_Get_Task_Id Gets the FactoryLink task id set on IMX.

Imx_Sys_Set_Task_Id Sets the current task FactoryLink task id.

Imx_Sys_Get_Station_Id

Gets the local station id number.

Imx_Sys_Set_Station_Id

Sets local station id number.

Imx_Sys_Get_Mbx Gets the task IMX mailbox tag.

Imx_Sys_Set_Mbx Sets the task IMX mailbox tag.



18

IMX

Referen

ce Gu

ide

Imx_Sys_Get_Functions

Gets the supported function of the current IMX task.

Imx_Sys_Set_Functions Sets the IMX functions supported by the current task.

IMX Message Functions (IMXMSG)Imx_Get_Type Gets the type of the IMX message.Imx_Set_Type Sets the type of the IMX message.

Imx_Get_Org_Host_Dir Gets the data direction of the originating host.

Imx_Set_Org_Host_Dir Sets the data direction of the originating host.

Imx_Get_Station_Id Gets the station id where the message came from.

Imx_Set_Station_Id Sets the station id on the message.Imx_Get_Job_

SequenceGets the job sequence number of the message.

Imx_Set_Job_Sequence

Sets the job sequence number of the message.

Imx_Get_Ds_Ctrl Sets the dataset control tag.Imx_Set_Ds_Ctrl Gets the dataset control tag.

Imx_Get_U_Buffer Gets the pointer to the IMX data.Imx_Get_Org_Buffer Gets the pointer to the original buffer (inclusive of the IMX header).

Imx_Get_R_Buffer Gets the default msg buffer defined at registration time.Imx_Set_R_Buffer Sets the default msg buffer for the dataset.Imx_Reset_Buffer Clears the msg buffer.

Imx_Get_Snd_Mbx Gets the send IMX mailbox tag.Imx_Set_Snd_Mbx Sets the send IMX mailbox tag.

Imx_Get_Index Gets the index of the message in the mailbox queue at the moment.Imx_Set_Index Gets the index of the message in the mailbox queue.

IMX Dataset Functions (IMXDS)Imx_Get_Name Gets the name of the dataset control tag.Imx_Set_Name Sets the name of the dataset control tag.

Imx_Get_Udata_Ptr Gets the pointer to the user defined buffer.Imx_Set_Udata_Ptr Sets the pointer to the user defined buffer.Imx_Get_Ufnc_Ptr Gets the pointer to the user function.Imx_Set_Ufnc_Ptr Sets the pointer to the user function.



•

•

•

•IMX Data Manipulation Functions

The data manipulation functions are used to set and retrieve data on datasets. The functions depend on the direction of the data in the dataset and the host direction defined in the IMX task at compile time.

Imx_Get_Byte_Bit_H2L Gets bit out of byte with data direction high to low.

Imx_Set_Byte_Bit_H2L Sets bit on byte with data direction high to low.

Imx_Get_Byte_Bit_L2H Gets bit out of byte with data direction low to high.

Imx_Set_Byte_Bit_L2H Sets bit on byte with data direction low to high.Imx_Get_Word_Bit_

H2LGets bit out of word with data direction high to low.

Imx_Set_Word_Bit_H2L

Sets bit on word with data direction high to low.

Imx_Get_Word_Bit_L2H

Gets bit out of word with data direction low to high.

Imx_Set_Word_Bit_L2H Sets bit on word with data direction low to high.Imx_Get_Long_Bit_H2L Gets bit out of long with data direction high to low.Imx_Set_Long_Bit_H2L Sets bit on long with data direction high to low.Imx_Get_Long_Bit_L2H Gets bit out of long with data direction low to high.Imx_Set_Long_Bit_L2H Sets bit on long with data direction low to high.

Imx_Get_Byte_Left_H2L

Gets the left byte out of word wit data direction high to low.

Imx_Set_Byte_Left_H2L

Sets the left byte on word with data direction high to low.

Imx_Get_Byte_Left_L2H

Gets the left byte out of word with data direction low to high.

Imx_Set_Byte_Left_L2H

Sets the left byte on word with data direction low to high.

Imx_Get_Byte_Right_H2L

Gets the right byte out of word with data direction high to low.

Imx_Set_Byte_Right_H2L

Sets the right byte on word with data direction high to low.

Imx_Get_Byte_Right_L2H

Gets the right byte out of word with data direction low to high.

Imx_Set_Byte_Right_L2H

Sets the right byte on word with data direction low to high.

Imx_Get_Word_H2L Gets a word with data direction high to low.Imx_Set_Word_H2L Sets a word with data direction high to low.Imx_Get_Word_L2H Gets a word with data direction low to high.

Imx_Set_Word_L2H Sets a word with data direction low to high.Imx_Get_Long_H2L Gets a long with data direction high to low.Imx_Set_Long_H2L Sets a long with data direction high to low.

Imx_Get_Long_L2H Gets a long with data direction low to high.Imx_Set_Long_L2H Sets a long with data direction low to high.

IMX REFERENCE LIBRARYIMX APIs


18

IMX

Referen

ce Gu

ide

Imx_Get_RLong_H2L Gets a reversed long with data direction high to low.Imx_Set_RLong_H2L Sets a reversed long with data direction high to low.Imx_Get_RLong_L2H Gets a reversed long with data direction low to high.Imx_Set_RLong_L2H Sets a reversed long with data direction low to high.

Imx_Get_Double_H2L Gets a double with data direction high to low.

Imx_Set_Double_H2L Sets a double with data direction high to low.

Imx_Get_Double_L2H Gets a double with data direction low to high.

Imx_Set_Double_L2H Sets a double with data direction low to high.

IMX APIS

This chapter provides the following information about each IMX API function:



• Type

• Name

• Description

• Returns: Description of the returned data from the function, usually a symbolic representation of the integer value returned by the function, such as ERROR or GOOD.



Caution: Some functions listed warn the programmer not to incorporate them into a driver. They are listed here only for documentation purposes.



•

•

•

•

IMX_BUFFER_ALLOC

Allocates a buffer for transferring data using the IMX.

Syntax int Imx_Buffer_Alloc( MSG *msg)

Returns GOOD.

Error: FLE_OUT_OF_MEMORY.

Remarks This function allocates an IMX buffer and sets the pointer directly to the message. The application must first set the length of the buffer using the m_max parameter.

This function can be used for setting allocating buffers for use with IMX but is not strictly necessary. In case the application wants to allocate its own buffers, it should also allocate space for the IMXHDR part, which is always in front of the data. The buffer can be set by either using the Imx_Set_R_Buffer( ) or Imx_Set_T_Buffer( ).

The pointer to the first element in the buffer must be retrieved using Imx_Get_U_Buffer( ). The pointer to the original allocated buffer can be retrieved using Imx_Get_Org_Buffer( ).

IMX_DS_EVALUATE_WRITE

Evaluates the IMX dataset to see if it is possible to write this dataset in one operation. A write operation is treated as an exception write (reading before writing) or a block write.

Syntax intImx_Ds_Evaluate_Write( IMXDS *dataset)

Returns GOOD: Element can be written at once.

IMX_X_WRITE( ): Element cannot be written at once. Read, patch and write back.

Remarks This function is used by protocol drivers for evaluating if a received exception write command can be written at once to the external device. The function checks the received dataset parameters against the registered parameters and tries to convert it so it can be written with one command. If it cannot be written with one command and cannot be converted, the element must be read first from the external device, patched with the new value and written back.

The criteria used for evaluation is if the size of the element to write is smaller than the data boundary of the external device, it cannot be written at one time because data in the external device will be overwritten.

Arguments MSG* msg Pointer to FactoryLink message structure.

Arguments IMXDS* dataset Pointer to IMX dataset structure.



18

IMX

Referen

ce Gu

ide

This function speeds up communication because, in most cases, one write command is needed against a read before a write.

This function can alter the received dataset parameters and data in order to convert it.

IMX_DS_PREPARE

Loads the default values set at registering time on the dataset.

Syntax int Imx_Ds_Prepare( IMXDS *dataset, MSG *buffer)

Returns GOOD.

Remarks The prepare function can be used before sending an IMX message to a remote task. After preparing the dataset, the type of the IMX command must be set and all elements of the dataset can be redefined to meet the characteristics of the command.

IMX_DS_QUERY

Sends a query request for information of the dataset to the remote task where the dataset has been defined.

Syntax int Imx_Ds_Query( IMXDS *dataset)

Returns GOOD.

Errors:

IMX_BAD_CTRL.

IMX_BAD_SNDMBX.

FLE_NULL_POINTER.

FLE_BAD_TAG.

FLE_NOT_MAILBOX.

FLE_NO_MESSAGES.

FLE_ACCESS_DENIED.

FLE_OUT_OF_MEMORY.


MSG* buffer Pointer to buffer information.




•

•

•

•FLE_LOCK_FAILED.

FLE_LOCK_EXPIRED.

Remarks Usually I/O translator tasks use this function at initialization time in order to retrieve all the information on a dataset.

Protocol drivers do not use this function.

IMX_DS_REGISTER

Registers a dataset for use with the IMX library.

Syntax IMXDS *Imx_Ds_Register(IMXDS *dataset)

Returns Success: Pointer to internal registered dataset.

Error: NULL pointer is returned.

Remarks Every dataset for use with the IMX must be registered first at initialization time. Before registering, all relevant information of the dataset must be set first using IMX functions. The IMX library will return a pointer to the final registered dataset that the application can use for referencing.

IMX_DS_REMOVE

Removes all datasets from the task IMX mailbox queue that have the same IMX functionality and dataset control tag.

Syntax intImx_Ds_Remove(IMXMSG *dataset)

Returns GOOD.

Errors:

IMX_WRONG_INDEX.

IMX_NOT_FOUND.

FLE_OUT_OF_MEMORY.

FLE_NULL_POINTER.

FLE_BAD_TAG.

FLE_NOT_MAILBOX.





18

IMX

Referen

ce Gu

ide

FLE_NO_MESSAGES.

FLE_ACCESS_DENIED.

FLE_LOCK_FAILED.

FLE_LOCK_EXPIRED.

IMX_BAD_CTRL.

Remarks This function scans all active messages in the IMX mailbox queues and removes those messages that have the same IMX functionality and dataset control tag.

The IMX has four command capabilities: QUERY, READ, WRITE and RECEIVE. For every message removed and representing an active command from the queue, an error message with error IMX_MSG_REJECTED( ) is sent to the originating task.

IMX_DS_TRIGGER

Triggers a dataset for reading by the remote IMX task.

Syntax intImx_Ds_Trigger(IMXDS *dataset)

Returns GOOD.

Errors:

IMX_BAD_CTRL.

IMX_BAD_SNDMBX.

FLE_NULL_POINTER.

FLE_BAD_TAG.

FLE_NOT_MAILBOX.

FLE_NO_MESSAGES.

FLE_ACCESS_DENIED.

FLE_OUT_OF_MEMORY.

FLE_LOCK_FAILED.

FLE_LOCK_EXPIRED.




•

•

•

•Remarks The I/O translator tasks uses this function to read a complete dataset. The function

sends an IMX read command to the remote task, which is usually a protocol driver. If the protocol driver remains in the same application, the dataset control tag is triggered. If the communication is over a LAN, a mailbox message is generated. Triggering only the dataset control tag is a faster way of communication.

IMX_EVENT_CHECK

Calls every program cycle if the IMX events are handled on polling basis and not on events.

Syntax intImx_Event_Check(void)

Arguments None.

Returns GOOD: No errors occurred while processing events.

Errors:

FLE_NULL_POINTER.

FLE_BAD_ARGUMENT.

FLE_NO_CHANGE.

FLE_LOCK_FAILED.

FLE_BAD_TAG.

Remarks This function must be called every program cycle if IMX events are to be handled on a polling basis. Tasks that cannot start a FactoryLink fl_wait( ) function because other events outside FactoryLink can occur complete this.

The handling of an IMX event is exactly the same as with the event driven mode of IMX.

IMX_EVENT_RETRIEVE

Gets the event arrays for true event driven processing.

Syntax int Imx_Event_Retrieve( TAG **tags, void **datasets, u32 *num,

int (__cdecl **e_fnc)( void *ds, VAL val))

Arguments TAG **tags Pointer to hold internal IMX array of event tags.

void **datasets Pointer to hold internal IMX array of datasets.

u32 *num Pointer to total number of IMX events.

--- **e_fnc Pointer to hold internal IMX array of function pointers.



18

IMX

Referen

ce Gu

ide

Returns GOOD: All parameters are filled with the internal IMX pointer values.

Remarks If a task wants to operate in an event driven mode, this function retrieves the events of the IMX. The following arrays are returned:

Tags: return a list of all tags that can generate an IMX event. This tag list can be added to the applications tag list and passed to the fl_wait_.. functions of FactoryLink.

FactoryLink Datasets: return a list of pointers to all registered datasets of the IMX. This pointer must be used as first parameter of the user function in case of event.

e_fnc: return a list of event function pointers that must be called in case of an IMX event.

The data of every index of the three arrays correspond to each other. If an IMX event occurs, the event function with the event index and corresponding data must be called. For example:

e_fnc[ index]( dataset[ index], val);

The value val can be retrieved from the FactoryLink fl_wait... functions. The application must call the event function supplied by the IMX, and then the event function automatically calls the user function registered with the dataset.

IMX_EXIT

Exits the Inter-Task Mail Exchange library for use.

Syntax intImx_Exit( void)

Arguments None.

Returns GOOD.

Remarks This function frees all internal resources of the IMX library and should be called just before exiting the application.

IMX_GET_BIT_DIR

Gets the direction of bit information within the boundary elements.

Syntax ucharImx_Get_Bit_Dir( IMXDS *dataset

Returns Returns the direction of bit data, either

Imx_High_2_Low.

Arguments IMXDS *dataset Pointer to IMX dataset structure.



•

•

•

•Imx_Low_2_High.

IMX_GET_BIT_OFFSET

Gets the bit addressing offset determined by the external device.

Syntax uchar Imx_Get_Bit_Offset( IMXDS *dataset)

Returns Returns the bit addressing offset, either 0 or 1.

IMX_GET_BND_DIR

Gets the boundary of normal data in the dataset IMX message.

Syntax ucharImx_Get_Bnd_Dir( IMXDS *dataset)

Returns Direction of data, either

Imx_High_2_Low.

Imx_Low_2_High.

IMX_GET_BND_OFFSET

Gets the boundary addressing offset determined by the external device.

Syntax ucharImx_Get_Bnd_Offset( IMXDS *dataset)

Returns Returns the addressing offset, either 0 or 1.

IMX_GET_BOUNDARY

Gets the boundary of data for this dataset.

Syntax ucharImx_Get_Boundary( IMXDS *dataset)







18

IMX

Referen

ce Gu

ide

Returns Returns the data boundary, which can be one of the following:

IMX_GET_CDEGets the operation code CDE that indicates the operation on the data in case of an exception write.

Syntax u16Imx_Get_CDE( IMXDS *dataset)

Returns Returns the CDE code.

IMX_GET_CDE_SIZE

Returns the size of the data according to the operation (CDE) specified.

Syntax intImx_Get_CDE_Size( ushort cde)

Returns Size of the element according to CDE code, which can be one of the following

Errors:

IMX_BIT_BND Boundaries on bit basis.

IMX_BYTE_BND Boundaries on character basis (1 char).

IMX_WORD_BND Boundaries on word basis (2 char).

IMX_LONG_BND Boundaries on long basis (4 char).

IMX_DBL_BND Boundaries on double basis (8 char).


Arguments ushort cde Operation code.

0 IMX_BIT_BND Boundaries on bit basis (1 char 1 bit).

1 IMX_BYTE_BND Boundaries on character basis (1 char).

2 IMX_WORD_BND Boundaries on word basis (2 char).

4 IMX_LONG_BND Boundaries on long basis (4 char).

8 IMX_DBL_BND Boundaries on double basis (8 char).



•

•

•

•ERROR CDE code does not exist.

Remarks The size of the element returned also corresponds to the boundary of the element.

IMX_GET_DS_CTRL

Gets the dataset control tag of this received dataset message.

Syntax TAG Imx_Get_Ds_Ctrl( IMXDS *dataset)

Returns The dataset control tag.

Remarks The application does not usually use this function because the IMX always returns with the correct dataset.

IMX_GET_HANDLING

Gets the handling of a write command on the dataset message.

Syntax uchar Imx_Get_Handling( IMXDS *dataset)

Returns None.

Remarks The mode of writing, either

IMX_NORMAL_WRITE.

IMX_ENCODED_WRITE.

IMX_GET_INDEX

Gets the index of the dataset message in the mailbox queue.

Syntax uint Imx_Get_Index( IMXDS *dataset)

Returns The index into the mailbox queue.






18

IMX

Referen

ce Gu

ide

Remarks The index into the mailbox queue must not be saved for later use because the indices in the queue can change. If an IMX event occurs, the IMX library always returns datasets with the index set. If the application wants to read the dataset later, it must first search the dataset in the queue and not use a saved index.

IMX_GET_JOB_SEQUENCE

Gets the job sequence number of the received dataset message.

Syntax u16 Imx_Get_Job_Sequence( IMXDS *dataset)

Returns The job sequence number of the received message.

IMX_GET_LEN

Gets the length of the data in the dataset message in elements according to the boundary size.

Syntax u16 Imx_Get_Len( IMXDS *dataset)

Returns The length of the data in the message.

IMX_GET_NAME

Gets the name of the dataset control tag as specified in the FactoryLink real-time database.

Syntax char *Imx_Get_Name( IMXDS *dataset)

Returns Pointer to character string containing the dataset control name.

Remarks The name set during registration is returned.

IMX_GET_ORG_HOST_DIR

Gets the originating host data direction.






•

•

•

•Syntax ucharImx_Get_Org_Host_Dir( IMXDS *dataset)

Returns The data direction of the originating host, either

IMX_HIGH_2_LOW.

IMX_LOW_2_HIGH.

IMX_GET_R_BUFFER

Gets the registered buffer parameters of this dataset.

Syntax MSG*Imx_Get_R_Buffer( IMXDS *dataset)

Returns Pointer to a FactoryLink MSG structure that contains the parameters of the buffer.

Remarks This function retrieves the buffer parameters which were set during registration of this dataset. The dataset uses this buffer if it is not overruled by using the functions Imx_Ds_Prepare( ) or Imx_Set_T_Buffer( ).

IMX_GET_SND_MBX

Gets the IMX mailbox tag of this dataset used for sending messages.

Syntax TAGImx_Get_Snd_Mbx( IMXDS *dataset)

Returns The tag of the IMX send mailbox for this dataset.

Remarks This tag must be set during dataset registration.

IMX_GET_START

Gets the start address of the data in the dataset message.

Syntax u16 Imx_Get_Start( IMXDS *dataset)







18

IMX

Referen

ce Gu

ide

Returns The start address of the data.

IMX_GET_STATION_IDGets the remote station id received from on the dataset message.

Syntax uchar Imx_Get_Station_Id( IMXDS *dataset)

Return The unique remote station identification number.

IMX_GET_T_BUFFER

Gets the buffer parameters currently set on this dataset.

Syntax MSG* Imx_Get_T_Buffer( IMXDS *dataset)

Returns Pointer to a FactoryLink MSG structure that contains the parameters of the buffer.

Remarks This function retrieves the buffer parameters currently set on the dataset. This can be the default parameters (at registration) or a buffer that overruled the default.

IMX_GET_TYPE

Gets the type of the IMX message.

Syntax uchar Imx_Get_Type( IMXDS *dataset)

Returns The type of the message, which can be one of the following:




IMX_QUERY_CMD IMX information message.

IMX_QUERY_RSP IMX information message feed back.

IMX_QUERY_ERROR IMX information message feed back.

IMX_READ_REQ Read request.



•

•

•

•

IMX_GET_U_BUFFER

Gets the pointer to the first element of the dataset data buffer currently set.

Syntax char * Imx_Get_U_Buffer( IMXDS *dataset)

Returns Character to the first data element.

Remarks The buffer set on a dataset for holding data contains an IMXHDR and data. The application cannot use the original pointer but must retrieve the pointer to the user function using this function. The original buffer pointer and the data pointer differ from each other.

IMX_GET_UDATA_PTR

Gets the pointer to the additional user dataset information buffer.

Syntax char * Imx_Get_Udata_Ptr( IMXDS *dataset)

Returns Pointer to the user buffer.

IMX_READ_RSP Read feed back.

IMX_READ_ERROR Read feed back.

IMX_WRITE_REQ Write request

IMX_WRITE_RSP Write feed back.

IMX_WRITE_ERROR Write feed back.

IMX_RCV_ACT Unsolicited receive active.

IMX_RCV_RDY Unsolicited receive ready.

IMX_RCV_ERROR Unsolicited receive ready.

IMX_QUERY_CMD IMX information message.





18

IMX

Referen

ce Gu

ide

IMX_GET_UFNC_PTR

Gets the user function pointer called when an IMX event occurs.

Syntax int (*)( IMXDS *)Imx_Get_Ufnc_Ptr( IMXDS *dataset)

Returns Pointer to the user function that takes a pointer to a dataset as parameter.

IMX_GET_VERSION

Gets the version of the IMX which generated this dataset message.

Syntax uchar Imx_Get_Version( IMXDS *dataset)

Returns The version number of the IMX that generated this dataset message.

IMX_INIT

Initializes the IMX library for use.

Syntax int Imx_Init( IMXSYSTEM *sys)

Returns GOOD.

FLE_OUT_OF_MEMORY.

FLE_NULL_POINTER.

FLE_BAD_TAG.

FLE_NOT_MAILBOX.

FLE_NO_MESSAGES.

FLE_LOCK_FAILED.

FLE_LOCK_EXPIRED.

Remarks This function must be called before any other function of the IMX library.



Arguments IMXSYSTEM sys Imx system information.



•

•

•

•

IMX_MIRROR

Reverses a character buffer of specified length.

Syntax void Imx_Mirror( char *buf, ushort length)

Returns None.

Remarks Reverses a character buffer of specified length. This function is used internally in the IMX library for converting data elements of host machines with different data directions.

IMX_PLACE_DATA

Places data in the correct position within an element depending on the direction of the data.

Syntax void Imx_Place_Data( IMXMSG *dataset, char bnd_dir)

Returns None.

Remarks This function gets the first element of the message buffer (I/O data area), checks the operation code (CDE) and places the data in the correct position in the element, and converts the element to the final boundary.

This function is usually used for exception write commands that require only one element and, for the most part, is only used internally in the IMX library.

For example, when a message has the CDE code CDE_B0_15 with a specific bit number set, the bit value is placed on the position of the bit number. The data direction of the data element changes to the direction specified.

IMX_Q_DS_SRCH

Searches the task IMX mailbox queue for a certain dataset.

Arguments char *buf Source buffer for reversing.

ushort length Length of buffer in characters.


char bnd_dir Final boundary of data.



18

IMX

Referen

ce Gu

ide

Syntax int Imx_Q_Ds_Srchl( IMXDS *dataset)

Returns GOOD: Dataset has been found.

Errors:

IMX_NOT_FOUND.

FLE_NULL_POINTER.

FLE_BAD_TAG.

FLE_NOT_MAILBOX.

FLE_NO_MESSAGES.

FLE_LOCK_FAILED.

FLE_LOCK_EXPIRED.

Remarks This function searches the active IMX messages for a message with the same dataset control tag. If a message is found, the index of the message in the queue is set on the dataset.

Indices in the queue should not be saved for later use because they can change.

*IMX_Q_INIT

Initializes the task IMX mailbox queue.

Syntax int Imx_Q_Init( void)

Arguments None.

Returns GOOD.

Errors:

FLE_OUT_OF_MEMORY.

FLE_NULL_POINTER.

FLE_BAD_TAG.

FLE_NOT_MAILBOX.

FLE_NO_MESSAGES.

FLE_LOCK_FAILED.

FLE_LOCK_EXPIRED.




•

•

•

•Remarks This function initializes the mailbox queue by deleting every message in the queue

except for query messages. It is not advisable for an application to use this function. This function is called by the IMX library at start up.

IMX_Q_NUM

Determines the number of active IMX messages in the task mailbox queue.

Syntax int Imx_Q_Num( uint *num)

Returns GOOD.

Errors:

FLE_NULL_POINTER.

FLE_BAD_TAG.

FLE_NOT_MAILBOX.

FLE_LOCK_FAILED.

FLE_LOCK_EXPIRED.

Remarks Returns the number of active IMX messages in the IMX mailbox queue of the task. This number can differ from the total number of messages in the queue.

IMX_Q_QUERY

Queries a dataset in the queue but does not remove the dataset.

Syntax int Imx_Q_Query( IMXDS *dataset)

Returns GOOD.

Errors:

FLE_NULL_POINTER.

FLE_BAD_TAG.

FLE_NOT_MAILBOX.

FLE_NO_MESSAGES.

FLE_LOCK_FAILED.

Arguments uint *num Number of messages in the IMX.




18

IMX

Referen

ce Gu

ide

FLE_LOCK_EXPIRED.

Remarks Before querying the dataset, the index in the queue must be valid. This is accomplished by using the Imx_Set_Index( ) function. The query function only returns data of the IMX section, IMXMSG. This means only a limited number of IMX functions can be used (no functions that operate on the IMXHDR section). Usually the application does not have to use this function because the IMX library queries the new message (before calling the user function) with every event.

IMX_RECV

Retrieves an IMX message from the task mailbox.

Syntax int Imx_Recv( IMXDS *dataset)

Returns GOOD.Errors:

IMX_WRONG_INDEX.

FLE_NULL_POINTER.

FLE_BAD_TAG.

FLE_NOT_MAILBOX.

FLE_NO_MESSAGES.

FLE_ACCESS_DENIED.

FLE_LOCK_FAILED.

FLE_LOCK_EXPIRED.

IMX_BAD_CTRL.

Remarks This function reads an IMX message from the task IMX mailbox using the parameters set on the dataset, such as the index in the mailbox queue. The function removes the message from the mailbox queue. Prior to calling this function, the task sets a different message buffer to store the message when it is pulled from the mailbox. If this is not done, the message buffer defined at registration time for the dataset is used. The message buffer is contained inside the dataset structure.




•

•

•

•

IMX_RESET_BUFFER

Resets the buffer parameters on the dataset message.

Syntax void Imx_Reset_Buffer( IMXDS *dataset)

Returns None.

Remarks Resets the buffer parameters on the dataset currently used. If no other buffer is set, the default buffer set during registration is used in subsequent IMX calls.

IMX_SEND

Sends a dataset to a remote task through the designated send IMX mailbox of the dataset.

Syntax int Imx_Send( IMXDS *dataset)

Returns GOOD.

Errors:

IMX_BAD_CTRL.

IMX_BAD_SNDMBX.

FLE_NULL_POINTER.

FLE_BAD_TAG.

FLE_NOT_MAILBOX.

FLE_NO_MESSAGES.

FLE_ACCESS_DENIED.

FLE_OUT_OF_MEMORY.

FLE_LOCK_FAILED.

FLE_LOCK_EXPIRED.

Remarks This function sends the dataset to the remote task using the send (remote task mailbox) mailbox which was set at registration time. All parameters must be defined for the dataset before calling this function. Default parameters, which were set at





18

IMX

Referen

ce Gu

ide

registration time, can be set by using the Imx_Ds_Prepare( ) function. After retrieving default values, specific value can then be set on the same dataset, such as the command type (which must be set).

IMX_SEND_ERROR

Sends an IMX error message to the remote task depending on the type of the dataset.

Syntax int Imx_Send_Error( IMXDS *dataset, u16 error)

Returns GOOD.

Errors:

IMX_BAD_TYPE.

IMX_BAD_CTRL.

IMX_BAD_SNDMBX.

FLE_NULL_POINTER.

FLE_BAD_TAG.

FLE_NOT_MAILBOX.

FLE_NO_MESSAGES.

FLE_ACCESS_DENIED.

FLE_OUT_OF_MEMORY.

FLE_LOCK_FAILED.

FLE_LOCK_EXPIRED.

Remarks This function generates an IMX error message depending on the dataset type and sends it to the remote task. This function is usually used after an IMX event, which means all relevant parameters are already set on the dataset. No preparation is required other than the call to the function. The function uses an independent internal message buffer for sending the message. It returns with the IMX message buffer parameters reset to NULL.

See Also “Imx_Set_Type”


u16 error Error number.



•

•

•

•

IMX_SET_BIT_DIR

Gets the direction of bit information within the boundary elements.

Syntax void Imx_Set_Bit_Dir( IMXDS *dataset, uchar dir)

Returns None.

Remarks The direction of bit data, either

Imx_High_2_Low.

Imx_Low_2_High.

IMX_SET_BIT_OFFSET

Sets the bit addressing offset determined by the external device.

Syntax void Imx_Set_Bit_Offset( IMXDS *dataset, uchar offset)

Returns None.

Remarks The bit addressing offset can be either 0 or 1.

IMX_SET_BND_DIR

Sets the boundary of normal data in the dataset IMX message.

Syntax void Imx_Set_Bnd_Dir( IMXDS *dataset, uchar dir)

Returns None.

Remarks The direction of data, either

Imx_High_2_Low.


uchar dir Bit data direction.


uchar offset Bit addressing offset of ds.


uchar dir Data direction.



18

IMX

Referen

ce Gu

ide

Imx_Low_2_High.

IMX_SET_BND_OFFSET

Sets the boundary addressing offset determined by the external device.

Syntax void Imx_Set_Bnd_Offset( IMXDS *dataset, uchar offset)

Returns None.

Remarks The boundary addressing offset can be either 0 or 1.

IMX_SET_BOUNDARY

Sets the boundary of data of this dataset message.

Syntax void Imx_Set_Boundary( IMXDS *, uchar bnd)

Returns None.

See Also Imx_Get_Boundary( )

IMX_SET_CDEGets the operation code CDE that indicates the operation on the data in case of an exception write.

Syntax void Imx_Set_CDE( IMXDS *dataset, u16 cde)

Returns None.


uchar offset Boundary addressing offset of ds.


uchar bnd Boundary to set.


u16 cde Operation code.



•

•

•

•

IMX_SET_DS_CTRL

Sets the dataset control tag on this dataset.

Syntax void Imx_Set_Ds_Ctrl( IMXDS *dataset, TAG ctrl)

Returns None.

Remarks The application will probably use this function once: just before registering the dataset. After the dataset has been registered, the application does not have to call this function.

IMX_SET_HANDLING

Sets the handling of a write command on the dataset message.

Syntax void Imx_Set_Handling( IMXMSG *, uchar mode)

Returns None.

Remarks The mode of writing, either

IMX_NORMAL_WRITE.

IMX_ENCODED_WRITE.

IMX_SET_INDEX

Sets the index of the dataset message in the mailbox queue.

Syntax void Imx_Set_Index( IMXDS *dataset, uint index)

Returns None.


TAG ctrl Dataset control tag.


uchar mode Mode for writing.


uint index Index in the queue.



18

IMX

Referen

ce Gu

ide

Remarks This function should not be used by the application directly because the search function of the IMX library automatically sets the index of the dataset in the queue.

IMX_SET_JOB_SEQUENCE

Sets the job sequence number on the dataset message.

Syntax void Imx_Set_Job_Sequence( IMXDS *dataset, u16 num)

Returns None.

Remarks This function is used to set a sequence number on command for keeping track of the command. The responding task returns the same job number as received.

IMX_SET_LEN

Sets the length of the data in the dataset message in elements according to the boundary size.

Syntax void Imx_Set_Len( IMXDS *dataset, u16 len)

Returns None.

IMX_SET_NAME

Sets the name of the dataset control tag on the dataset for registering.

Syntax void Imx_Set_Name( IMXDS *dataset, char *name)

Returns None.

Remarks The dataset control tag name must be set before registering. The tag name must correspond to the tag id.


u16 num Sequence number to set.


u16 len Length of data.


char *name Dataset control tag name.



•

•

•

•

IMX_SET_ORG_HOST_DIR

Sets the originating host data direction.

Syntax void Imx_Get_Set_Org_Host_Dir( IMXDS *dataset, uchar dir)

Returns None.

Remarks The application should not use this function because the IMX library sets this parameter.

IMX_SET_R_BUFFER

Sets the registered buffer parameters of this dataset.

Syntax void Imx_Set_R_Buffer( IMXDS *dataset, MSG *buf)

Returns None.

Remarks This function must be called before registering a dataset. The function sets the default buffer the IMX library uses if it is not overruled.

IMX_SET_SND_MBX

Sets the IMX mailbox tag of this dataset used for sending messages.

Syntax void Imx_Set_Snd_Mbx( IMXDS *dataset, TAG send)

Returns None.

Remarks This function must be called before registering the dataset. Afterwards, the function is not used.


uchar dir Originating data direction.


MSG *buf Buffer parameters.


TAG send IMX send mailbox tag.



18

IMX

Referen

ce Gu

ide

IMX_SET_START

Sets the start address of the data in the dataset message.

Syntax void Imx_Set_Start( IMXDS *dataset, u16 start)

Returns None.

IMX_SET_STATION_IDSets the remote station id received from the dataset message.

Syntax void Imx_Set_Station_Id( IMXDS *dataset, uchar station)

Returns None.

Remarks This function can be used to set the local station identification number but is not to be used by the application because this is completed internally by the IMX library. The station id set during initialization is used.

IMX_SET_T_BUFFER

Sets the temporary buffer parameters of this dataset. The default parameters are overruled.

Syntax void Imx_Set_T_Buffer( IMXDS *dataset, MSG *buf)

Returns None.

Remarks This function sets the buffer parameters on the dataset. This overrules the default buffer parameters, but they are preserved. If the default parameters must be used, reset the buffer parameters with Imx_Reset_Buffer( ) before executing other functions.


u16 start Start address.


uchar station Unique station identification.


MSG *buf Buffer parameters.



•

•

•

•

IMX_SET_TYPE

Sets the type of the IMX message.

Syntax void Imx_Set_Type( IMXDS *dataset, uchar type)

Returns None.

See Also “Imx_Get_Type”

IMX_SET_UDATA_PTR

Sets the pointer to the additional user dataset information buffer.

Syntax void Imx_Set_Udata_Ptr( IMXDS *dataset, char *buf)

Returns None.

Remarks The application sets a pointer to a user defined buffer of a dataset. This buffer is used for specifying additional dataset information. This data can be retrieved when IMX events occur. This function must be called before registering the dataset.

IMX_SET_UFNC_PTR

Sets the pointer to the user function.

Syntax void Imx_Set_Ufnc_Ptr( IMXDS *dataset, int (*u_fnc)( IMXDS *))

Returns None.

Remarks The user function pointer must be set and is called if an IMX event occurs on this dataset. The user function must accept a pointer to the dataset as parameter and return an integer.


uchar type Type of message.


char *buf Additional dataset information.


--- *ufnc User function pointer.



18

IMX

Referen

ce Gu

ide

*IMX_SET_VERSION

Sets the version of the IMX library on the dataset message.

Syntax void Imx_Set_Version( IMXDS *dataset, uchar version)

Returns None.

Remarks The application should not use this function because the version is set internally by the IMX library.

IMX_SYS_GET_FUNCTIONSGets the IMX functions supported by this task as registered at initialization.

Syntax ushort Imx_Sys_Get_Functions( IMXSYSTEM *sys)

Returns The supported functionality.

IMX_SYS_GET_MBX

Gets the IMX mailbox tag as registered for this task.

Syntax TAG Imx_Sys_Get_Mbx( IMXSYSTEM *sys)

Returns Returns the tag value of the IMX systems mailbox tag of this task.

IMX_SYS_GET_STATION_IDGets the station id of this host machine as registered in the IMX library.

Syntax uchar Imx_Sys_Get_Station_Id( IMXSYSTEM *sys)

Returns The station id number of the host machine.


uchar version Version to set.

Arguments IMXSYSTEM *sys Imx system information.





•

•

•

•Remarks The station id number must be unique over the LAN.

IMX_SYS_GET_TASK_IDGets the FactoryLink task id currently registered in the IMX library.

Syntax u16 Imx_Sys_Get_Task_Id( IMXSYSTEM *sys)

Returns The FactoryLink task id number.

Remarks This id should match the task id of the current FactoryLink task.

IMX_SYS_SET_MBX

Sets the IMX mailbox tag for registering for this task.

Syntax void Imx_Sys_Set_Mbx( IMXSYSTEM *sys, TAG mbx)

Returns None.

Remarks This task should be called before the Imx_Init( ) function with the mailbox tag used for IMX communication.

IMX_SYS_SET_STATION_IDSets the station id of this host machine for registering in the IMX library.

Syntax void Imx_Sys_Set_Station_Id( IMXSYSTEM *sys, uchar station)

Returns None.

Remarks This function must be called before the Imx_Init( ) function with an unique station number on the LAN.



TAG mbx IMX systems mailbox tag.


uchar station Unique station number.



18

IMX

Referen

ce Gu

ide

IMX_SYS_SET_TASK_IDSets the FactoryLink task id for registering in the IMX library.

Syntax void Imx_Sys_Set_Task_Id( IMXDS *dataset, u16 id)

Returns None.

Remarks The id number the fl_init_app( ) returns must be passed with this function. This function must be called before the Imx_Init( ) function.


u16 id FactoryLink task id number.



•

•

•

•


• • • •

Ap

pen

dix

AppendixPAK Conversion Considerations

This appendix contains information on converting from earlier versions of FactoryLink to the present version 7.0. Some of this information was presented in previous Release Notes, which should be used only if it still applies to your situation.

CONVERTING PRE-FACTORYLINK 7.0 PAK TASK

Two changes have been made to the PAK/EDI-PAK Libraries that affect custom tasks and EDI drivers. There are also significant modifications to the EDI task and EDI libraries to support EDI and EDI drivers on multi-processor machines. For FactoryLink versions 6.5.0 and 6.6.0, this requires all third-party EDI drivers be recompiled with the new EDI-PAK libraries. In addition, a change to the "fl_get_proc()" function in the PAK Libraries requires that any custom task making these calls be updated.

While these are the only two changes that are known to require custom tasks and custom EDI Drivers to be rebuilt, USDATA recommends that all custom tasks be rebuilt with each new release of FactoryLink.

ADDING MULTILINGUAL SUPPORT

Several changes in the international version of FactoryLink affect third-party drivers and PAK tasks created with pre-6.0.4 versions of FactoryLink. Review the changes and follow the instructions below to set up FLINK and convert your third-party driver or custom PAK tasks to run with the international FLINK.

PAK CONVERSION CONSIDERATIONSAdding Multilingual Support


•

•

•

•The following table shows the changes from previous FactoryLink versions to the current version. Directories for the supported languages, English, French, and German display as \EN, \FR, and \DE, respectively.

Old Directory New Directory Comments

n/a (new dir) \dll\xx\

(xx represents the languages, EN, FR, or DE)

Contains language-specific DLL files. May contain files other than DLLs. Only a directory that matches the installed languages displays as a subdirectory

\msg\english \help\xx\

(xx represents the languages, EN, FR, or DE)

Contains *.HLP files.Only a directory that matches the installed languages displays as a subdirectory.

n/a (new subdir) \key\ Contains directories for each language installed.

n/a (new subdirs) \key\en\

\key\fr\

\key\de\

Contain *.KEY files for each language installed.

n/a (new dir) \mps\ Contains directories for each language installed.

n/a (new subdirs) \mps\en\

\mps\fr\

\mps\de\

Contain *.MPS files for each language installed.

\msg\ \msg\en\

\msg\fr\

\msg\de\

Contain *.TXT files. Only a directory that matches the installed languages displays as a subdirectory.

PAK CONVERSION CONSIDERATIONSAutomated Conversion of Pre-6.0.4 Driver or PAK Task


Ap

pen

dix

AUTOMATED CONVERSION OF PRE-6.0.4 DRIVER OR PAK TASK

Complete the following procedure to convert third-party drivers or PAK tasks:

1 USDATA recommends you install FactoryLink 6.6.0 to a clean directory structure. Do not install over an existing FLINK for versions prior to 6.0.3. Complete the installation following the FactoryLink installation instructions.

2 Install your third-party driver task or PAK task according to vendor instructions. After installation, make any associated changes per the task installation instructions.

Note: For conversion from FactoryLink 6.0.4 or earlier, it is possible that the installation will fail if the previous FLINK directory structure is expected. This directory would be in the form {FLINK}\msg\<language> as in {FLINK}\msg\english. If the installation fails, create this directory manually and reinstall.

3 Run the FactoryLink mv_pak utility. The mv_pak utility copies your driver and/or PAK files in the correct directory structure and renames the initial *.txt files to *.bkt, *.hlp files to *.bkh, and *.key files to *.bkk.

4 If an English subdirectory was created in Step 2, delete it now.

PAK CONVERSION CONSIDERATIONSAutomated Conversion of Pre-6.0.4 Driver or PAK Task


•

•

•

•

Index I-483

Index

AAC files 311

comments in 74created 67, 73described 45, 67, 73example 95example (external editor program) 99format 74format (external editor program) 98with CONFIG PAK 301

accessing CDBs 311acctmgr -c -d utility 309adding tag definitions 335analog data type 37, 61Application Editor 301archive (CT) 118arrayed elements

described 55examples 56

arrays 54attribute catalog

See AC filesattribute catalogs

with CONFIG PAK 309

Bbinary CT generation utility 125block read function 415block write function 418

Ccalling and return conventions 146CDB (configuration database) 309CDBLIST utility 102, 103CDE codes 428

block data commands 428data header direction 428exception data commands 428

CDE operation codes 408, 423CFGPAK (Configuration PAK) 297change-read call 40change-status bits 38, 142change-wait call 40changing name of tag definition 337common functions in interface library 415compiling

BASIC PAK 25RAPD 402

compiling and executing Skeleton Task 29CONFIG PAK

error messages 342message box type requests 342return codes/error messages 340storage entities 300validation error reporting 343

configuration architectureBASIC PAK 51CONFIG PAK 299

configuration database (CDB) 309configuration database API 313

I-484 FactoryLink 7.0

configuration database tables 59configuration environment 67

design database tables 67setting up 71, 117testing 69, 102

Configuration Managerdescribed 46new tasks 23

configuration managertask configuration 297

Configuration PAK (CFGPAK) 297configuration panels 52configuration sessions 301constructing a task 65control panels 53, 72conversion process

debugging 126conversion script

described 118format 118sample 124

converting IMX messages 429cross-reference (XREF) database table 61CT access 151CT archive 118

header 118index 119record 118

CT filesconverting database tables 69created 125described 45

CTG filescreated 118described 118example 123

tag constant fields 123CTG script

format 118CTGEN utility 69, 118, 125CTLIST utility 125

Ddata directions 427data structure hierarchy with CONFIG PAK 303data transfer

examples 42data types 61database access services 140database table

configured 59contents 67converting to CTs 69defined 75design 67, 72format 61task-specific 62, 72

Dataset Definition panel 411, 413dataset registration 431datasets 411

passing and processing 413dBASE

compatible database library 86compatible database manager 102

deleting a tag definition 338designing panels 72designing task-specific database tables 72digital data type 37, 61direct tag processing 156

actionsloading 160processing 162

Index I-485

records 160removing 163

data structures 157exit codes 164instance 158instantiating 157library services 156

directions of data 427domain

and task-specific tables 72driver communication 437

Eeditor program execution from CM 98element names 54elements

described 59name storage 59predefined 59structure 38

environment variables 24error code 418, 421, 426error numbers 147exception processing 40exception writes 422

encoded 423normal 422testing 423

exit the calling process 133external configuration 300

FFactoryLink

API 32Kernel 33operation 31

failure scenarios with CONFIG PAK 302field handles 314FL_LOCK

relationship to FL_UNLOCK 236FLAPP

directory files 62, 64with CONFIG PAK 301

FLINKdirectory 400directory files 48with CONFIG PAK 301

floating point data type 37, 61flow of code 433forced-write call 39, 46functions

block read 415block write 418exception writes 422unsolicited receive 424

II/O functionality 415IMX

interface library 403LANS communication 431library functions 443messages

converting 429specifications 403

information panels 53, 72informing FactoryLink about new task 101initialize

calling process 129installation

BASIC PAK 25CONFIG PAK 298


RAPD 400interface library

common functions 415inter-process communication (IPC) 139, 145IOX driver communications 437

KKernel 33Kernel and library services

database access 135KEY files

created 45, 68, 99described 68, 99example 101missing 102

LLANS communication and IMX 431layout of panels 72library functions

BASIC PAKCT Access 151Direct Tag Processing 156Kernel Interface 136Message Translation 176Normalized Tag Reference 165Object CT Access 153Path Manipulation 170

CONFIG PAK 305Domain Field API 314Exception Handling API 340Field (configuration data) API 315Object Configuration Database API 331Select Field API 314Sequence Field API 315Tag Definition API 332

data manipulation functions 446IMX dataset functions 445IMX system functions 444RAPD

API functions 447general IMX functions 443IMX header functions 444IMX message functions 445

library servicesconfiguration session API 306interface services 136

locking the database 142long analog (longana) data type 37, 61

Mmailbox communications 404mailbox data type 37, 61mailbox message data structure (MBXMSG) 404mailbox message datasets 411mailbox services 139message data type 37, 61message translation services 176

loading files 177managing multiple trees 178translating files 178

mm_msg parameter 405mm_type parameter 409mm_user1 parameter 410mm_user2 parameter 410multi-user access to CDB 329

Nnormalized tag reference services 165

Index I-487

OObject CT access 153OBJECT database table 61

and task-specific tables 72open architecture 23operation codes

CDE 408

Ppanels

control 53, 72designing 72information 53, 72layout 72

parameterserror code 418mm_msg 405mm_type 409mm_user1 410mm_user2 410

passing a dataset 413path manipulation 170

allocating/destroying path 172building and representation 170converting to/from 172environment variables 171files

creating/deleting 173getting information 174searching for 173

modifying 172path names

components 170predefined data types 37predefined elements. See tag nameprimary key 300

printing tag definitions 333processing a dataset 413Programmer’s Access Kit (PAK)

described 23hardware requirements 24installation 25software requirements 24

protocol driver default message buffer 435protocol driver design example 433protocol message 417

RRAPD

principle with IOX 401RAPD principle illustrated 401read calls 39reading configuration from CDB 318reading tag definitions 333Real-Time Database

described 37locking 142structure of elements 38

Run-Time Manager 32, 127, 133and CT files 45interaction with other tasks 32

run-time requirements 127run-time task

writing 69

Sselection criteria 318setting up configuration environment 71, 117setup script 25Skeleton Task

compiling and executing 29CONFIG PAK 305


converting script 28described 27integrating 28makefile 30procedure 28verifying 28, 29, 30

software design modelflowchart 66

station identification number 431steps in reading configuration data in CDB 318structure of elements 38structure of tag names 54syntax samples 55System Configuration Table 32

Ttag definitions

adding 335changing name 337deleting 338printing 333reading 333updating 336writing 334

tag modification routines 301tag name

assignment 54structure 54

tag number 142task

constructing 65task construction flowchart 71task/Kernel session management 136

attaching/detaching from Kernel 136database access 140error reporting 146

mailbox 145miscellaneous session services 140obtaining environment access 138Real-Time Database access 142signals 139VAL union structure 143

tasksdata transfer methods

examples 42described 31, 41

task-specific database tables 62design 72

task-specific tablesand domain 72and OBJECT tables 72

termination flagcheck status 132

testingconfiguration environment 69, 102

TITLES file 69, 101with CONFIG PAK 301

triggers 46and forced writing 46

TYPE database table 61

Uunlocking the database 142unsolicited receive function 424updating a tag definition 336utilities

acctmgr -c -d 309CDBLIST 102, 103CTGEN 69, 118, 125CTLIST 125

Index I-489

VVAL union structure 143

Wwait bits 40, 142write calls 39writing a RAPD driver 433writing configuration to CDB 321

deleting row from CDB 327inserting row 321updating row in CDB 324

writing tag definitions 334writing the run-time task 69

XXREF database table 61

Date post:	04-Aug-2020
Category:	Documents
Upload:	others
View:	14 times
Download:	0 times

electroautomatica.ru · FactoryLink 7.0 / Programmer’s Access Kit / 3 Table of Contents...

Documents