04_UsingAPI

ModulesModule 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. All Rights Reserved. and database manipulation routines • Standard C/C++ programming environment (other languages possible) • Synchronous or asynchronous triggers ©2009 AspenTech.21 database • Current or historical values • Many read. Slide 5 .21 API • If appropriately linked. write. 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. All Rights Reserved. for example: • Manually run utilities • One-time only programs (for example. Aspen InfoPlus. Slide 6 .21 database • This kind of program is called an “External Task” • External Tasks can only run on server ©2009 AspenTech.21 API Principles Two kinds of programs can be written: – Programs scheduled by user. initializer) • Programs scheduled by operating system – This kind of program can run on server or remote – Programs triggered by Aspen InfoPlus. Slide 7 .21 include files • Must call routines – INISETC.21 libraries • Should not run continuously (especially if “tight loops”) ©2009 AspenTech. All Rights Reserved. Requirements for User-Scheduled Process • Should include one or more of Aspen InfoPlus. ENDSETC • Must link to one or more Aspen InfoPlus. accessing one or many servers • Local programs – Link to setcim. All Rights Reserved.lib – Most database access routines require record ID • Remote programs – Link to InfoPlus21_api.lib – Reference configuration file (setcimrpc. Run on Server or Remote • User programs can run locally on server or on remote node. Slide 8 .cfg) for list of servers – Most access routines require Node ID in addition to record ID ©2009 AspenTech. Structure Overview • Include InfoPlus21_api. Slide 9 . not names – “Tag” here means number associated with field name and occurrence ©2009 AspenTech.h file or setcim. All Rights Reserved. not names – Field “Tags” must be used.h • Link to InfoPlus21_api.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.lib or setcim. 21 databases remotely • Calls on several other include files (for example.h Include File • Provided for “C/C++” language • Declares special structures for entities required to access Aspen InfoPlus. and functions needed for remote access ©2009 AspenTech. InfoPlus21_api. data types.h) depending on compilation options • Declares #DEFINES. setcim. Slide 10 . All Rights Reserved. All Rights Reserved.h Include File • Provided for “C/C++” language • Declares special structures for entities like: – ERRBLOCK – IDANDFT – XTSBLOCK ©2009 AspenTech. Setcim. 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. Slide 12 . All Rights Reserved. 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.21 access routines are called: – Local Programs: • Maps process into memory • Initializes exception handlers • Returns 1 if local database running. Slide 13 . what to do if a connection to a node fails. logging behavior) ©2009 AspenTech. else 0 – Remote Programs: • Tries to read configuration file SETCIMRPC. Initialization • Routine INISETC() performs initialization • Must be called before any Aspen InfoPlus. All Rights Reserved. performs as above ©2009 AspenTech. Slide 15 .lib: • Searches local server only • Returns only Record ID • DECODRAF converts name and field tag pair – Otherwise.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. All Rights Reserved. Identifying Database Items • Most database access routines locate Aspen InfoPlus. decomposes as follows: 1005 0001 Field number from Occurrence Number Field name record (0000 if field in fixed area) ©2009 AspenTech. Slide 17 . What Is A Field Tag? • Identifies a field within a record • Always expressed in Hex – Example 0x10050001. All Rights Reserved. Database Access Routines • Routines exist to: – Read and write from/to database – Provide information about database – Synchronize application elements • For example. All Rights Reserved. Slide 18 . 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. Activate. 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 . All Rights Reserved.longdata.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. Calling a Typical Aspen InfoPlus.ft. Slide 20 .&err) • Function name MUST be uppercase ©2009 AspenTech. All Rights Reserved. What Functions are Available? Database API Manual documents at two levels: Overview.g. e. Slide 21 .. 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. Slide 22 . 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 23 . memory) • No program should call ENDSETC() except when exiting ©2009 AspenTech. All Rights Reserved. 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. All Rights Reserved.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. 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. Slide 24 . can include in Aspen InfoPlus. Running and Stopping User Scheduled Tasks • To start tasks that run on local server node automatically. Slide 25 .21 run the command via SQLplus or CommandDef record ©2009 AspenTech. All Rights Reserved.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. as a minimum requirement. Slide 27 . The method of triggering influences the way it is coded • User-triggered programs can run on local 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. Review • User programs can access Aspen InfoPlus. All Rights Reserved.21 server. call INISETC and ENDSETC functions • All API functions must be in uppercase • Most API functions access Aspen InfoPlus. or remotely • User-triggered programs must. care should be taken to pass arguments in the correct way ©2009 AspenTech.21.21 information by record ID and field tag “handles” • If using the API from a language other than “C/C++”. Slide 28 . 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. Module Overview Writing Aspen InfoPlus. Slide 31 . All Rights Reserved.21 (External Tasks) ©2009 AspenTech.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 data record is “activated”. 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. Introduction to External Tasks • When Aspen InfoPlus. Slide 32 . it exhibits some processing behavior • This behavior is actually implemented by means of a process associated with the record. taking up no processing resource until record is “activated” • External Tasks can only run on a local Aspen InfoPlus. All Rights Reserved.21 system ©2009 AspenTech. g... TSK_IQ1 Definition Record Wake up! e. e. External Task Trigger Mechanism Using SQLplus query records as an example External External Task (sometimes) Task Record e. Record Perform Processing..g.g. Query1 Then Back to sleep.. Data I’ll read SQL from record.g. All Rights Reserved. TSK_IQ1 e. Slide 33 . QueryDef And here’s a message “Activation” OK. ©2009 AspenTech. record with higher priority number is processed first ©2009 AspenTech. 4096 highest possible • If two records activated at same time for external task. 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. Slide 34 . All Rights Reserved. All Rights Reserved. Code Structure for External Task • Include setcim.Else: • Call additional functions • End loop. EXTSKWAI .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. write error report message • ENDSETC ©2009 AspenTech. Slide 35 . Starting External Tasks • External Tasks should be started from Aspen InfoPlus. Slide 37 . All Rights Reserved.21 Manager GUI • Add new task to Task list • Remember to check External Task Box ©2009 AspenTech. Slide 38 . All Rights Reserved. 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. c • Aspen InfoPlus. Slide 40 . Using the API: Lab 2 – Snoop. All Rights Reserved.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. integer last_update timestamp tanklevel real ptfts ptdtypes ptdatas field tag list data type list list to receive data ©2009 AspenTech. Typical Routine: Using RDBVals • RDBVALS(recid. ptdatas. ptfts. numvalues. numok. ptdtypes. Slide 43 . All Rights Reserved. error) message sw. 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. error) • mode – Type of request – Interpolated values (three algorithms) or actual values • step – TRUE or FALSE: if true. ft. recid. step. keytimes. numfts. 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. timeold. maxoccs. outsiders. ptoccsok. datatypes. ftsok. timenew. Slide 45 . keylevels. fts. All Rights Reserved. ptdatas. keytimes. ftsok. ptoccsok. recid. ptdatas. maxoccs. Slide 46 . 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. timeold. timenew. numfts. outsiders. 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. fts. datatypes. All Rights Reserved. keylevels. step. ft. RHIS21DATA Arrays RHIS21DATA (mode.. error) trend value real numfts trendtime timestamp trendquality integer Fts – field Datatypes – Ptdatas – pointers to .. outsiders. ptdatas. ftsok. ft. recid. fts. datatypes. All Rights Reserved. maxoccs. ptoccsok. keytimes. timenew. timeold... numfts. step. tag array data type array arrays to receive data ©2009 AspenTech. Slide 47 . keylevels. fts. ft. timenew. recid. keytimes. 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. step. ptdatas. timeold. datatypes. keylevels. numfts. outsiders. RHIS21DATA keylevels/keytimes RHIS21DATA (mode. Slide 48 . ftsok. maxoccs. ptoccsok. All Rights Reserved. and can retrieve interpolated or actual values ©2009 AspenTech. All Rights Reserved. Slide 49 .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. Review • Programs triggered by Aspen InfoPlus. 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. Slide 50 . All Rights Reserved. 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. calculating the natural volume of the tank. All Rights Reserved. Slide 54 . 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. when triggered by data records defined against definition records created in the course • Definition record will also require adjustment ©2009 AspenTech. 21 using the RHIS21DATA function • RHIS21DATA is used by any client application that retrieves actual history values.21 Administrator – Aspen SQLplus or any ODBC application – Aspen Process Explorer and Excel Add-Ins – Aspen Web. Slide 56 .21 BCU – Aspen Calc • The instructor will perform a code walk-through ©2009 AspenTech. RHIS21DATA Example • This example runs in a console window and returns history values from Aspen InfoPlus. All Rights Reserved. This would include: – Aspen InfoPlus.21 – Aspen Batch. RHIS21DATATEST. All Rights Reserved. Slide 57 .EXE Run the program passing record name as input parameter Results ©2009 AspenTech. ©2009 AspenTech. All Rights Reserved. This slide is Hidden so that additional Note space is available. Slide 59 . All Rights Reserved. Slide 60 .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. Using the API: Lab 4 – RHIS21DATATEST. setcim.lib and Infoplus21_api. Slide 61 . Polling Questions • What is the difference between the 2 Library files.lib? • What is a Field Tag? • Describe some the parameters used by EXTASKCHK ©2009 AspenTech. All Rights Reserved. Questions? ©2009 AspenTech. All Rights Reserved. Slide 62 .