Sie sind auf Seite 1von 48

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