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)

©2009 AspenTech. All Rights Reserved. Slide 3

 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

©2009 AspenTech. All Rights Reserved. Slide 4

 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
©2009 AspenTech. All Rights Reserved. Slide 5
 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

©2009 AspenTech. All Rights Reserved. Slide 6

 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”)

©2009 AspenTech. All Rights Reserved. Slide 7

 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

©2009 AspenTech. All Rights Reserved. Slide 8

 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
©2009 AspenTech. All Rights Reserved. Slide 9
 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

©2009 AspenTech. All Rights Reserved. Slide 10

 Setcim.h Include File

• Provided for “C/C++” language

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

©2009 AspenTech. All Rights Reserved. Slide 11

 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)

©2009 AspenTech. All Rights Reserved. Slide 12

 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)

©2009 AspenTech. All Rights Reserved. Slide 13

 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
©2009 AspenTech. All Rights Reserved. Slide 15
 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)

©2009 AspenTech. All Rights Reserved. Slide 17

 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

©2009 AspenTech. All Rights Reserved. Slide 18

 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

©2009 AspenTech. All Rights Reserved. Slide 19

 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

©2009 AspenTech. All Rights Reserved. Slide 20

 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

©2009 AspenTech. All Rights Reserved. Slide 21

 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”

©2009 AspenTech. All Rights Reserved. Slide 22

 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

©2009 AspenTech. All Rights Reserved. Slide 23

 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
©2009 AspenTech. All Rights Reserved. Slide 24
 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

©2009 AspenTech. All Rights Reserved. Slide 25

 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
©2009 AspenTech. All Rights Reserved. Slide 27
 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

©2009 AspenTech. All Rights Reserved. Slide 28

 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)

©2009 AspenTech. All Rights Reserved. Slide 31

 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
©2009 AspenTech. All Rights Reserved. Slide 32
 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.
©2009 AspenTech. All Rights Reserved. Slide 33
 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
©2009 AspenTech. All Rights Reserved. Slide 34
 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
©2009 AspenTech. All Rights Reserved. Slide 35
 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

©2009 AspenTech. All Rights Reserved. Slide 37

 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

©2009 AspenTech. All Rights Reserved. Slide 38

 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

©2009 AspenTech. All Rights Reserved. Slide 40

 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
©2009 AspenTech. All Rights Reserved. Slide 43
 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

©2009 AspenTech. All Rights Reserved. Slide 44

 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

©2009 AspenTech. All Rights Reserved. Slide 45

 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)

©2009 AspenTech. All Rights Reserved. Slide 46

 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
©2009 AspenTech. All Rights Reserved. Slide 47
 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
©2009 AspenTech. All Rights Reserved. Slide 48
 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
©2009 AspenTech. All Rights Reserved. Slide 49
 The Tank Program

• On the following pages is the full code for the tank

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

©2009 AspenTech. All Rights Reserved. Slide 50

 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

©2009 AspenTech. All Rights Reserved. Slide 54

 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

©2009 AspenTech. All Rights Reserved. Slide 56

 RHIS21DATATEST.EXE

Run the program passing record name as input parameter

Results

©2009 AspenTech. All Rights Reserved. Slide 57

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

©2009 AspenTech. All Rights Reserved. Slide 59

 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

©2009 AspenTech. All Rights Reserved. Slide 60

 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

©2009 AspenTech. All Rights Reserved. Slide 61

 Questions?

©2009 AspenTech. All Rights Reserved. Slide 62