04 UsingAPI

Modules
Module 1 Introduction
Module 2 Overview and Context
Module 3 Custom Definition Records
Module 4 Using the API
Module 5 Server Based Processing
Module 6 Summaries and Logs
Module 7 Dot.NET Applications
©2009 AspenTech. All Rights Reserved.

Objectives
Use the Aspen InfoPlus.21 API to write programs which

execute:
– Independently from events within the Aspen InfoPlus.21
database
• On the host computer
• On a remote computer
– Upon a schedule or events within the Aspen InfoPlus.21
database (External Task)
©2009 AspenTech. All Rights Reserved. Slide 2

Module Overview
Writing Aspen InfoPlus.21 Server Applications using C or

C++
– General Programming Principles
– Writing Programs which run remotely from server
– Writing Programs running on server triggered by Aspen
InfoPlus.21 (External Tasks)

Aspen InfoPlus.21 API
• API – Application Programming Interface

• Allows application developers to write programs which
may:
– Read and/or write information to Aspen InfoPlus.21
– Trigger other application modules such as:
• User processes
• SQLplus queries
• Plant Application records

Features of Aspen InfoPlus.21 API
• If appropriately linked, can operate remotely from

another computer
• Available on multiple hardware/operating system
platforms (only Windows is described in this module)
• Can read any data in Aspen InfoPlus.21 database
• Current or historical values
• Many read, write, and database
manipulation routines
• Standard C/C++ programming environment
(other languages possible)
• Synchronous or asynchronous triggers
Aspen InfoPlus.21 API Principles
Two kinds of programs can be written:

– Programs scheduled by user, for example:
• Manually run utilities
• One-time only programs (for example, initializer)
• Programs scheduled by operating system
– This kind of program can run on server or remote
– Programs triggered by Aspen InfoPlus.21 database
• This kind of program is called an “External Task”
• External Tasks can only run on server

Requirements for User-Scheduled
Process
• Should include one or more of Aspen InfoPlus.21 include

files
• Must call routines
– INISETC, ENDSETC
• Must link to one or more Aspen InfoPlus.21 libraries

• Should not run continuously (especially if “tight loops”)

Run on Server or Remote
• User programs can run locally on server or on remote

node, accessing one or many servers
• Local programs
– Link to setcim.lib
– Most database access routines require record ID
• Remote programs
– Link to InfoPlus21_api.lib
– Reference configuration file (setcimrpc.cfg) for list of servers
– Most access routines require Node ID in addition to record ID

Structure Overview
• Include InfoPlus21_api.h file or setcim.h

• Link to InfoPlus21_api.lib or setcim.lib
• INISETC() initialization function is called first
• Main code – use documented API functions (read or
write)
• ENDSETC() function called on termination of program
• Notes:
– Function names are uppercase
– Record IDs must be used, not names
– Field “Tags” must be used, not names
– “Tag” here means number associated with field name and
occurrence
InfoPlus21_api.h Include File
• Provided for “C/C++” language

• Declares special structures for entities required to
access Aspen InfoPlus.21 databases remotely
• Calls on several other include files (for example,
setcim.h) depending on compilation options
• Declares #DEFINES, data types, and functions needed
for remote access

Setcim.h Include File
• Provided for “C/C++” language

• Declares special structures for entities like:
– ERRBLOCK
– IDANDFT
– XTSBLOCK

Main Code: Typical Elements
Identify all Call Database

Initialize/Connect
Database items access routines
(INISETC)
to get “handles” using “handles”
Process the data
De-initialize
(ENDSETC)

Initialization
• Routine INISETC() performs initialization

• Must be called before any Aspen InfoPlus.21 access
routines are called:
– Local Programs:
• Maps process into memory
• Initializes exception handlers
• Returns 1 if local database running, else 0
– Remote Programs:
• Tries to read configuration file SETCIMRPC.CFG
• If no such file tries to connect to local database
• Connections are made to all database nodes listed in file
• Additional parameters in file define other connection parameters (for
example, what to do if a connection to a node fails, logging behavior)

Identifying Database Items
• Most database access routines locate Aspen InfoPlus.21

data using “handles” based on Record ID, and often an
identifier for a field called a Field Tag
• DECODNAM converts Record Name to Record ID
“handle”
– If linked to InfoPlus21_api.lib:
• Searches all connected servers for record ID
• Returns Node ID in 16 most significant bits
• Returns Record ID in least significant 16 bits
– If linked to setcim.lib:
• Searches local server only
• Returns only Record ID
• DECODRAF converts name and field tag pair

– Otherwise, performs as above
What Is A Field Tag?
• Identifies a field within a record

• Always expressed in Hex
– Example 0x10050001- decomposes as follows:
1005 0001
Field number from Occurrence Number
Field name record (0000 if field in fixed area)

Database Access Routines
• Routines exist to:

– Read and write from/to database
– Provide information about database
– Synchronize application elements
• For example, Activate, write schedule times
– Perform system administrative functionality
• Routines which access database items do so using a

record ID “handle”, and sometimes also a field tag
– Remote applications use a Node name/Record ID combined
handle

Flavors of Read/Write
Read/Write routines can access:

– A single field in a record
• DB2LONG
– Multiple fields in a record
• RDBVALS
– Multiple occurrences of one field
• RDBOCCS
– Multiple occurrences of multiple fields
• MRDBOCCS

Calling a Typical Aspen InfoPlus.21
Function
• Arguments are expected to be passed either:

– By value
– By address (by reference)
• Important to pass arguments in the correct way

• “C/C++” Example
– LONG2DB(recid,ft,longdata,&err)
• Function name MUST be uppercase

What Functions are Available?
Database API Manual documents at two levels: Overview, e.g.,

Summary of Routines
Database Read Routines
D2ASCIIDB Converts a real value to ASCII in the format of a database field
DATA2ASCII Converts a value to ASCII in the format of the specified format
Database Write Routines
CHBF2DB Writes a character data buffer to the database
IDFT2DB Writes a record ID and field tag to the database (data type =
DTYPIDFT)
LONG2DB Writes a long integer to the database (data type = DTYPLONG)
Repeat Area Management
DELOCCS Deletes multiple occurrences from a repeat area
INSOCCS Inserts new occurrences in a repeat area
Record Manipulation
ACTRECS Activates multiple records
COPYREC Copies an existing record to a record with a new record name and

Using the API Documentation
• Once a function has been chosen, a detailed description is available

• Name and Description
• Format of typical call
• Each argument is
described
– Data Type
– Input/Output
– Value/reference
– Purpose
• Short program
example in “C”

De-Initialization
• Function ENDSETC
– Local Application Mode
• Unmaps program from shared memory
– Remote Application Mode
• Disconnects all Server Nodes
• Destroys the Server List Functions
• Releases resources (for example, memory)
• No program should call ENDSETC() except when exiting

Compilation and Linking
source
• Use Visual Studio to write source code in “C++”
compile
• Visual Studio is used to convert to binary object
• Binary object is LINKED to Aspen InfoPlus.21 object
libraries to produce executable program
• Supplied Visual Studio solution file link
– AspenTech\InfoPlus.21\shared\samples\infoplus21_api\Test_Decodnam
– Compiles and links example program executable

test_decodnam.cpp
• Executable program can be RUN run
process
Running and Stopping User
Scheduled Tasks
• To start tasks that run on local
server node automatically, can
include in Aspen InfoPlus.21
Manager
– Remember not to
check “External Task” or “Auto
restart” box if program will
complete!
• Alternatives:
– Make a Windows service
to start tasks automatically
– Provide a Command file to
start task
• Run command manually
• Have Aspen InfoPlus.21 run the
command via SQLplus or
CommandDef record

Review
• User programs can access Aspen InfoPlus.21 using an API

which is distributed with the core product
• User programs can be triggered by the user or by Aspen
InfoPlus.21. The method of triggering influences the way it is
coded
• User-triggered programs can run on local Aspen InfoPlus.21
server, or remotely
• User-triggered programs must, as a minimum requirement,
call INISETC and ENDSETC functions
• All API functions must be in uppercase
• Most API functions access Aspen InfoPlus.21 information by
record ID and field tag “handles”
• If using the API from a language other than “C/C++”, care
should be taken to pass arguments in the correct way
Using the API: Lab 1 –
WriteReal2DB.cpp
• “One Shot” Program Using the API

• In this lab you will:
– Write a “one shot” program which writes a value to the tank
level field of your tank record

Module Overview
Writing Aspen InfoPlus.21 Server Applications using

C/C++
– General Programming Principles
– Writing Programs which run remotely from server
– Writing Programs running on server triggered by Aspen
InfoPlus.21 (External Tasks)

Introduction to External Tasks
• When Aspen InfoPlus.21 data record is “activated”, it

exhibits some processing behavior
• This behavior is actually implemented by means of a
process associated with the record, which is triggered
when record is “activated”
• Such a process is known as “External Task”
• External task is written and run in a special way so that it
hibernates, taking up no processing resource until record
is “activated”
• External Tasks can only run on a local Aspen InfoPlus.21
system
External Task Trigger Mechanism
Using SQLplus query records as an example
External External
Task (sometimes) Task
Record e.g., TSK_IQ1
e.g., TSK_IQ1 Definition
Record Wake up!
e.g., QueryDef And here’s
a message
“Activation”
OK,
Data I’ll read SQL from record.
Record Perform Processing.
e.g., Query1 Then Back to sleep.
Record Activation
• A data record can be activated:

– On change-of-state of a field elsewhere in the database by a
COSActDef record
– Regularly on a schedule by a ScheduledActDef record
– By a PlantApDef record under its logic rules
– When a field inside the record
that has “activation properties” changes
– By an SQLplus query
– By another External Task
• Occurs at a Priority: 1 is low, 4096 highest possible

• If two records activated at same time for external task,
record with higher priority number is processed first
Code Structure for External Task
• Include setcim.h file

• INISETC
• EXTSKINI
– Check if external task record exists
• Loop until Error or Stop signal

• EXTASKCHK
• Get message packet from activated record or 0
• If no activations, EXTSKWAI
- Else:
• Call additional functions
• End loop, write error report message

• ENDSETC
Starting External Tasks
• External Tasks should

be started from Aspen
InfoPlus.21 Manager
GUI
• Add new task to
Task list
• Remember to check
External Task Box

Example Program SNOOP
• Please refer to the example “C” program shown on the

notes page
• This simple program is an external task which wakes up
when activated and displays the contents of the
activation message packet
• It illustrates the typical structure of an external task
• The instructor will perform a code walk-through

Using the API: Lab 2 – Snoop.c
• Aspen InfoPlus.21 Triggered Program using the API

• In this lab:
– Compile and link the program SNOOP
– Use it interactively to examine the activation behavior of the
custom definition record which featured built-in activation
mechanisms

Typical Routine: Using RDBVals
• RDBVALS(recid, numvalues, ptfts, ptdtypes, ptdatas,

numok, error)
message sw. integer
last_update timestamp
tanklevel real
ptfts ptdtypes ptdatas

field tag list data type list list to receive data
Introducing History Routine
RHIS21DATA
• Reads multiple occurrences of multiple history fields

• Reads occurrences in “reverse” order (older occurrences
first)
• Stores values read into multiple data arrays
• Accepts microsecond timestamp as start or end time

History Routine RHIS21DATA
Explained (1)
• RHIS21DATA (mode, step, outsiders, recid, ft, timeold, timenew,
numfts, fts, datatypes, maxoccs, keylevels, keytimes, ptdatas,
ptoccsok, ftsok, error)
• mode
– Type of request
– Interpolated values (three algorithms) or actual values
• step
– TRUE or FALSE: if true, returns extra values for use in step plots
• outsiders
– Reserved for future enhancements – set it to 0
• recid
– Record ID of the record that contains the history repeat area

History Routine RHIS21DATA
Explained (2)
• ft
– Field tag of any field in the history repeat area
– Or tag of repeat area sizing field for the area
• RHIS21DATA (mode, step, outsiders, recid, ft, timeold, timenew,
numfts, fts, datatypes, maxoccs, keylevels, keytimes, ptdatas,
ptoccsok, ftsok, error)
• timeold
– Start time for occurrences to read from history
– Timestamp of oldest occurrence required (microseconds)
• timenew
– End time for reading occurrences from history
– Timestamp of most recent occurrence required (microseconds)

RHIS21DATA Arrays
RHIS21DATA (mode, step, outsiders, recid, ft, timeold,

timenew, numfts, fts, datatypes, maxoccs, keylevels,
keytimes, ptdatas, ptoccsok, ftsok, error)
trend value real

numfts
trendtime timestamp
trendquality integer
Fts – field Datatypes – Ptdatas – pointers to .....

tag array data type array arrays to receive data
RHIS21DATA keylevels/keytimes
RHIS21DATA (mode, step, outsiders, recid, ft, timeold,

timenew, numfts, fts, datatypes, maxoccs, keylevels,
keytimes, ptdatas, ptoccsok, ftsok, error)
trend value real
trendtime timestamp
trendquality integer
datatypes ptdatas pointers Keylevels Keytimes

fts
data type to arrays to pointers to pointers to arrays
field tag
array receive data arrays to to receive key
array
receive quality timestamp data
level data
Review
• Programs triggered by Aspen InfoPlus.21 are known as

external Tasks
• External tasks require certain pre-requisites in order to
function correctly
• External tasks require to be coded with a particular
structure, and must call functions EXTSKINI and
EXTASKCHK
• Multiple value Functions like RDBVALS require matching
arrays to be configured as arguments
• History routines require multiple matching arrays to be
configured, and can retrieve interpolated or actual values
The Tank Program
• On the following pages is the full code for the tank

program
• The instructor will
perform a code
“walk-through”

Using the API: Lab 3 – The Tank
Program
• Tank Volume Program using the API

• Adjust the code in the Tank program so that it will run
satisfactorily, calculating the natural volume of the tank,
when triggered by data records defined against definition
records created in the course
• Definition record will also require adjustment

RHIS21DATA Example
• This example runs in a console window and returns

history values from Aspen InfoPlus.21 using the
RHIS21DATA function
• RHIS21DATA is used by any client application that
retrieves actual history values. This would include:
– Aspen InfoPlus.21 Administrator
– Aspen SQLplus or any ODBC application
– Aspen Process Explorer and Excel Add-Ins
– Aspen Web.21
– Aspen Batch.21 BCU
– Aspen Calc
• The instructor will perform a code walk-through

RHIS21DATATEST.EXE
Run the program passing record name as input parameter
Results

This slide is Hidden so that
additional Note space is available.

Using the API: Lab 4 –
RHIS21DATATEST.c
• Console program returns history values

• In this lab:
– Build the program RHIS21DATATEST.EXE
– Run it from a console window and return history values for
several tags
– Modify the application so that it reads TankDef records

Polling Questions
• What is the difference between the 2 Library files,

setcim.lib and Infoplus21_api.lib?
• What is a Field Tag?
• Describe some the parameters used by

EXTASKCHK

Questions?

04 UsingAPI

Загружено:

Сведения о документе

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

04 UsingAPI

Загружено:

Авторское право:

Доступные форматы

Modules

©2009 AspenTech. All Rights Reserved.

Use the Aspen InfoPlus.21 API to write programs which

©2009 AspenTech. All Rights Reserved. Slide 2

Writing Aspen InfoPlus.21 Server Applications using C or

©2009 AspenTech. All Rights Reserved. Slide 3

• API – Application Programming Interface

©2009 AspenTech. All Rights Reserved. Slide 4

• If appropriately linked, can operate remotely from

Two kinds of programs can be written:

©2009 AspenTech. All Rights Reserved. Slide 6

• Should include one or more of Aspen InfoPlus.21 include

• Must link to one or more Aspen InfoPlus.21 libraries

©2009 AspenTech. All Rights Reserved. Slide 7

• User programs can run locally on server or on remote

©2009 AspenTech. All Rights Reserved. Slide 8

• Include InfoPlus21_api.h file or setcim.h

• Provided for “C/C++” language

©2009 AspenTech. All Rights Reserved. Slide 10

• Provided for “C/C++” language

©2009 AspenTech. All Rights Reserved. Slide 11

Identify all Call Database

Process the data

©2009 AspenTech. All Rights Reserved. Slide 12

• Routine INISETC() performs initialization

©2009 AspenTech. All Rights Reserved. Slide 13

• Most database access routines locate Aspen InfoPlus.21

• DECODRAF converts name and field tag pair

• Identifies a field within a record

©2009 AspenTech. All Rights Reserved. Slide 17

• Routines exist to:

• Routines which access database items do so using a

©2009 AspenTech. All Rights Reserved. Slide 18

Read/Write routines can access:

©2009 AspenTech. All Rights Reserved. Slide 19

• Arguments are expected to be passed either:

• Important to pass arguments in the correct way

• Function name MUST be uppercase

©2009 AspenTech. All Rights Reserved. Slide 20

Database API Manual documents at two levels: Overview, e.g.,

©2009 AspenTech. All Rights Reserved. Slide 21

• Once a function has been chosen, a detailed description is available

©2009 AspenTech. All Rights Reserved. Slide 22

• No program should call ENDSETC() except when exiting

©2009 AspenTech. All Rights Reserved. Slide 23

– Compiles and links example program executable

• Executable program can be RUN run

©2009 AspenTech. All Rights Reserved. Slide 25

• User programs can access Aspen InfoPlus.21 using an API

• “One Shot” Program Using the API

©2009 AspenTech. All Rights Reserved. Slide 28

Writing Aspen InfoPlus.21 Server Applications using

©2009 AspenTech. All Rights Reserved. Slide 31

• When Aspen InfoPlus.21 data record is “activated”, it

Using SQLplus query records as an example

• A data record can be activated:

• Occurs at a Priority: 1 is low, 4096 highest possible

• Include setcim.h file

• Loop until Error or Stop signal

• End loop, write error report message

• External Tasks should

©2009 AspenTech. All Rights Reserved. Slide 37

• Please refer to the example “C” program shown on the