BAAN IV
Application Function Server (DRAFT)
Developer Guide
Template
2
Edition Control Chart
Editi Date Status
on
0.1
1999/0
3/18
0.2
2000/0
1/21
Changes
Affected
pages
NOTE added for 11
handsubprog
Document Authorization
Prepared
Checked
Name/Signat Lester Jacobs
ure
Date
March 18, 1999
Name/Signat
ure
Date
Name/Signat
ure
Date
Name/Signat
ure
Date
Name/Signat
ure
Date
Approved
Template
3
Document information
Document
Document code
Document group
Document title
Edition
:0.1
Month modified
:
: Development Documents
:Application Function Server User Guide
: 99/03
Check the BaanDoc database to see if this document is still a
valid edition.
Template
4
Table of contents
1.
1.1
1.2
1.3
1.4
1.5
1.6
Introduction
Purpose
Scope
Definitions, acronyms and abbreviations
References
Overview
Revision information
1
1
1
1
1
1
1
2.
2.1
2.2
2.3
Application Function Server
Introduction
Architecture
Structure of the AFS
2
2
2
3
3.
3.1
3.2
3.3
3.4
3.5
3.6
3.7
3.8
3.9
3.10
3.11
3.12
3.13
3.14
3.15
3.16
3.17
3.18
3.19
3.20
3.21
4GL Engine Primitives
Introduction
Get Field Value from Session
Set Field Value in Session
Insert Record in Session
Update Record in Session
Delete Record from Session
Commit Session Updates to Database
Abort Session Updates
Set Current Record for Session
Browse Session Records
Set Current View for Session
Browse Session Views
Send Start processing Command to Session
Set Session Report Parameters
Send Print Command to Session
End Session
Execute Session User Option
Execute Session Zoom Option
Specify Actions for Subsessions
Get Last Error Message from Session
Set Answers to Questions in Session
4
4
4
4
5
5
5
6
6
7
7
7
8
8
9
9
9
10
10
10
11
11
4.
Appendix A AFS Example
13
Copyright 1999 Baan Development B.V. All rights
reserved
The information in this document is subject to change without
Template
notice. No part of this document may be reproduced, stored
or i
transmitted in any form or by any means, electronic or
mechanical, for any purpose, without the express written
permission of Baan Development B.V.
Baan Development B.V. assumes no liability for any damages
Appendix A AFS Example
1.1
Purpose
1.Introduction
This document is designed to serve as a reference guide for the
Baan Application Function Server (AFS). It covers both architecture
of and programming with the AFS. Upon completion of this
document the reader will have the necessary knowledge to modify
existing AFS code and also to create new AFS code.
1.2
Scope
The intended audience for this document is experienced Baan
programmers only. No attempt is made to explain Baan 4GL
programming or Baan architecture outside of what is required for the
AFS.
1.3
Definitions, acronyms and abbreviations
Term
AFS
API
BOI
1.4
Description
Application Function Server
Application Program Interface
Business Object Interface
References
[BOIDEV]
Bagade
BOI Development Guide (Draft), Version 1.0, Milind
[BOIBUILD] BOI Builder Developers Guide, Version 1.0
1.5
Overview
Chapter 2 describes the architecture and structure of the Application
Function Server. Chapter 3 contains a detailed discussion of the 4GL
Engine primitives used by the AFS. Finally, Chapter 4 contains an
example of an AFS.
1.6
Revision information
None.
Template
1
Appendix A AFS Example
1.7
Introduction
The preferred method of integration between Baan (version 4c or
greater) and third party products is by means of Business Object
2.Application Function Server
2.1
Interfaces or BOIs. BOIs provide an Application Program Interface
(API) for the Baan business logic. The high level interfaces provided
by the BOIs cannot be used directly against the Baan business logic
due to the Baan architecture. The business logic is implemented by
means of sessions which are primarily user interface based.
Programmatic access to sessions is provided by means of a low level
message protocol. This message protocol is encapsulated into a set
of function primitives called the Application Function Server (AFS).
The BOI code accesses the session business logic by means of the
AFS. The public, high level interfaces exposed by the BOIs are
internally translated to the low level primitives understood by the
AFS which then communicates with the session logic by means of
the message protocol.
It is not usually necessary to create BOIs and AFSs from scratch.
BOIs can be generated using the BOI generator (ccboi0102m000)
and AFSs can be created by using the AFS generator (ttstpcreatdll).
The use of both of these generators is described in [BOIBUILD]. The
BOIs and AFSs created by the generators can be used directly to
solve straightforward integration problems where only one BOI and
one AFS is involved to implement a particular interface function set.
Complex integration scenarios where multiple BOIs and AFSs are
involved (eg. Sales Orders) require that extra development be done
in the generated BOI and AFS code. This extra development cannot
be accomplished without detailed knowledge of the architecture and
programming constructs involved in both the BOI and AFS code.
The BOI programming constructs are explained adequately in
[BOIDEV] thus we will only explain the details of the AFS.
Template
2
Appendix A AFS Example
1.8
Architecture
The following diagram shows the role of the AFS in the BOI
architecture. The diagram clearly illustrates that the BOI talks to
BOI
AFS DLL
Session
the underlying Baan session by means of the AFS.
1.9
Structure of the AFS
The structure of the AFS can best be described by looking at an
example of one. Appendix A shows the AFS for the session
tcmcs0145m000. The AFS is realized as a Baan library named
tcmcsf0145m000. Note the f in the AFS library name. The
standard naming convention for an AFS is to use the name of the
parent session and insert an f after the module code.
The AFS contains functions for setting and retrieving values for fields
in the underlying session. It also contains functions to add, update
and delete records from the session. Functions for browsing are also
provided. In addition miscellaneous functions for setting answers to
questions, handling subsessions and retrieving error messages are
provided.
There are a few important features to be noted. Firstly, all of the
functions follow a naming convention that is obvious when the
example code is perused. The naming convention should be
followed when making changes to the AFS since the BOI relies on
this (if it is generated). Secondly, all of the AFS functions are merely
a thin shell on the low-level primitives exposed by the 4GL Engine
(these primitives in turn encapsulate the message protocol
described earlier). Further discussion of the AFS functions will not be
done since the chapter following contains an in depth explanation of
the function primitives. An explanation of the function primitives
should suffice to also explain the AFS functions.
Template
3
Appendix A AFS Example
1.10
Introduction
In all AFS functions where a session is mentioned as a parameter,
the session will be automatically started if it is not already running.
3.4GL Engine Primitives
3.1
1.11
Get Field Value from Session
SYNTAX
void stpapi.get.field(string session, string field, ref string value, [long
element])
ARGUMENTS
session
on.
Name of the session this command is executed
field
Name of the field whose value is desired.
value
Upon return, this parameter contains the string
representation of the current value of the field
specified in field. For fields containing enum or
set values, the string representation of the
numeric value is returned, not the text description
of this value.
element
Array element whose value is to be returned in the
case of arrays or repeating fields.
DESCRIPTION
This returns the current value of a particular field from a specified
running Baan session.
RETURN VALUES
None
1.12
Set Field Value in Session
SYNTAX
void stpapi.put.field(string session, string field, string value, [long
element])
ARGUMENTS
Template
4
Appendix A AFS Example
session
on.
Name of the session this command is executed
field
Name of the field whose value is desired.
value
The value of the field specified in field is set to the
contents of this parameter. Any necessary type
conversion is performed
element
Array element whose value is to set returned in
the case of arrays or repeating fields.
DESCRIPTION
This sets the current value of a particular field in a specified running
Baan session.
RETURN VALUES
None
1.13
Insert Record in Session
SYNTAX
void stpapi.insert(string session, long do.update, ref string err.mesg)
ARGUMENTS
session
on.
Name of the session this command is executed
do.update
Flag specifying whether a database commit should
take place within this function. If do.update is set
to 1 then the update.db choice section of the
session will be executed before this function
returns. If do.update is set to 0 then update.db
is not executed.
err.mesg
This parameter will contain the text of the
error message if the function cannot complete
normally.
DESCRIPTION
This inserts the current record of the specified session into the
database. The values of the fields in the session must be set prior to
calling this function. If err.mesg is filled then stpapi.recover() must
be called before any other stpapi.* commands are issued to this
session.
RETURN VALUES
None
1.14
Update Record in Session
SYNTAX
void stpapi.update(string session, long do.update, ref string
err.mesg)
Template
5
Appendix A AFS Example
ARGUMENTS
session
on.
Name of the session this command is executed
do.update
Flag specifying whether a database commit should
take place within this function. If do.update is set
to 1 then the update.db choice section of the
session will be executed before this function
returns. If do.update is set to 0 then update.db
is not executed.
err.mesg
This parameter will contain the text of the
error message if the function cannot complete
normally.
DESCRIPTION
This updates the current record of the specified session in the
database. The values of the fields in the session must be set prior to
calling this function. If err.mesg is filled then stpapi.recover() must
be called before any other stpapi.* commands are issued to this
session.
RETURN VALUES
None
1.15
Delete Record from Session
SYNTAX
void stpapi.delete(string session, long do.update, ref string err.mesg)
ARGUMENTS
session
on.
Name of the session this command is executed
do.update
Flag specifying whether a database commit should
take place within this function. If do.update is set
to 1 then the update.db choice section of the
session will be executed before this function
returns. If do.update is set to 0 then update.db
is not executed.
err.mesg
This parameter will contain the text of the
error message if the function cannot complete
normally.
DESCRIPTION
This deletes the current record of the specified session in the
database. The values of the fields in the session must be set prior to
calling this function. If err.mesg is filled then stpapi.recover() must
be called before any other stpapi.* commands are issued to this
session.
RETURN VALUES
Template
6
Appendix A AFS Example
None
1.16
Commit Session Updates to Database
SYNTAX
void stpapi.save(string session, ref string err.mesg)
ARGUMENTS
session
on.
Name of the session this command is executed
err.mesg
This parameter will contain the text of the
error message if the function cannot complete
normally.
DESCRIPTION
This executes the choice section update.db of the specified
session. Note that the same effect can be achieved by issuing any
of the functions stpapi.insert(), stpapi.update() or stpapi.delete()
with the do.update parameter set to 1. If err.mesg is filled then
stpapi.recover() must be called before any other stpapi.* commands
are issued to this session.
RETURN VALUES
None
1.17
Abort Session Updates
SYNTAX
void stpapi.recover(string session, ref string err.mesg)
ARGUMENTS
session
on.
Name of the session this command is executed
err.mesg
This parameter will contain the text of the
error message if the function cannot complete
normally.
DESCRIPTION
This executes the choice section recover.set in the specified
session. If err.mesg is filled then stpapi.end() should be called
before issuing any other commands to this session.
RETURN VALUES
None
1.18
Set Current Record for Session
SYNTAX
long stpapi.find(string session)
Template
7
Appendix A AFS Example
ARGUMENTS
session
on.
Name of the session this command is executed
DESCRIPTION
This finds the record in the session corresponding the current values
of the sessions key fields and makes it current. The key field values
must be set prior to calling this function. Note that this function
uses the start index as defined for the session.
RETURN VALUES
0 No record found
1 Record found
2 a record different to the one requested was found
1.19
Browse Session Records
SYNTAX
long stpapi.browse.set(string session, string option)
ARGUMENTS
session
on.
Name of the session this command is executed
option
This parameter indicates what type of browse
action is required. The possible values are
first.set, next.set, prev.set and last.set
corresponding to the browse actions first record,
next record, previous record and last record
respectively.
DESCRIPTION
This executes the specified browse action against the indicated
session. The resulting record is set as current.
RETURN VALUES
0 No record found
1 Record found
1.20
Set Current View for Session
SYNTAX
long stpapi.change.view(string session)
ARGUMENTS
session
on.
DESCRIPTION
Template
8
Name of the session this command is executed
Appendix A AFS Example
This sets the current view for sessions using forms of type 3
(multiple occurrence plus view). The field values of the view fields
must be set prior to calling this function.
RETURN VALUES
0 No view found
1 View found
2 Another view found
1.21
Browse Session Views
SYNTAX
long stpapi.browse.view(string session, string option)
ARGUMENTS
session
on.
Name of the session this command is executed
option
This parameter indicates what type of browse
action is required. The possible values are
first.view, next.view, prev.view and last.view
corresponding to the browse actions first view,
next view, previous view and last view
respectively.
DESCRIPTION
This executes the specified browse action against the indicated
session. The resulting record is set as current.
RETURN VALUES
0 No view found
1 View found
1.22
Send Start processing Command to Session
SYNTAX
void stpapi.continue.process(string session, ref string err.mesg)
ARGUMENTS
session
on.
Name of the session this command is executed
err.mesg
This parameter will contain the text of the
error message if the function cannot complete
normally.
DESCRIPTION
This causes the choice option cont.process to be executed in the
specified session
RETURN VALUES
Template
9
Appendix A AFS Example
None
1.23
Set Session Report Parameters
SYNTAX
void stpapi.set.report(string session, string reportname, string
device, string err.mesg)
ARGUMENTS
session
on.
Name of the session this command is executed
reportname
Valid Baan report code for desired report
device
err.mesg
Valid Baan device code for desired device.
This parameter will contain the text of the
error message if the function cannot complete
normally.
DESCRIPTION
This selects the report to be printed and the device to be printed to
when the stpapi.print.report() is called.
RETURN VALUES
None
1.24
Send Print Command to Session
SYNTAX
void stpapi.print.report(string session, ref string err.mesg)
ARGUMENTS
session
on.
Name of the session this command is executed
err.mesg
This parameter will contain the text of the
error message if the function cannot complete
normally.
DESCRIPTION
This causes the choice option print.data to be executed in the
specified session. The function stpapi.set.report() must be called
prior to this to configure the report printing.
RETURN VALUES
None
1.25
End Session
SYNTAX
void stpapi.end.session(string session)
Template
10
Appendix A AFS Example
ARGUMENTS
session
on.
Name of the session this command is executed
DESCRIPTION
This ends the specified session
RETURN VALUES
None
1.26
Execute Session User Option
SYNTAX
void stpapi.application.option(string session, long form, long option,
ref string err.mesg)
ARGUMENTS
session
on.
Name of the session this command is executed
form
Form number on which user option should be
executed. User options (the choices under the
Special menu) are defined per form.
option
The option number to be executed. User options
appear as choice.user.x options in the Baan 4GL
code where x is a number between 0 and 9
inclusive. The value of x which corresponds to the
option that you want to activate is provided as the
value of this parameter.
err.mesg
This parameter will contain the text of the error
message if the function cannot complete normally.
DESCRIPTION
This executes the specified user option in the session.
RETURN VALUES
None
1.27
Execute Session Zoom Option
SYNTAX
void stpapi.zoom.option(string session, long form, string zoom.prog,
ref string err.mesg)
ARGUMENTS
session
on.
Name of the session this command is executed
form
Form number on which zoom should be executed.
This needs to be specified since some sessions
Template
11
Appendix A AFS Example
depend on a particular form being active when the
zoom is executed.
zoom.prog
Baan session for the zoom. This should be the
same as the zoom session specified for the choice
field of form. In the case that the choice specifies
a zoom to a menu, then this session should be one
of those mentioned in the menu.
err.mesg
This parameter will contain the text of the error
message if the function cannot complete normally.
DESCRIPTION
This executes a zoom in the specified session to the program given
in zoom.prog.
RETURN VALUES
None
1.28
Specify Actions for Subsessions
SYNTAX
void stpapi.handle.subproc(string session, string sub.prog, string
action)
ARGUMENTS
session
on.
Name of the session this command is executed
sub.prog
Baan session code to which the action
specified applies. This must be the session code
of a valid subsession of the specified session.
action
The action to be taken when the subsession starts.
This may be one of:
kill - Child process is killed as soon as it starts
ignore - The child process is ignored except for the
fact that the parent will wait until the child ends.
send - All future stpapi.*() function calls will act on
the child instead of the parent.
add The child is added to the list of sessions
currently under control. The child can thus be
independently controlled by issuing stpapi.*()
function directly against its session name
err.mesg
This parameter will contain the text of the error
message if the function cannot complete normally.
DESCRIPTION
This set the action that is taken when the specified subsession is
invoked from the specified session.
Template
12
Appendix A AFS Example
RETURN VALUES
None
COMMENT
When the sub processes is a dummy session without form then it is
not possible to communicate with the session via the function
server. In such cases it is also not possible to define the action for
the sub sessions of this dummy process.
For this situation you can define the action for the sub processes of
the dummy session in the group session (session where the pid is
the same as the gid of this subsession in the processlist). And the
dummy session should be defined with action ignore.
1.29
Get Last Error Message from Session
SYNTAX
string stpapi.get.mess.code(string session)
ARGUMENTS
session
on.
Name of the session this command is executed
DESCRIPTION
This retrieves the last error message generated by the indicated
session as a result of an stpapi.* function call.
RETURN VALUES
String containing text of error message or the empty string if no
error message found.
1.30
Set Answers to Questions in Session
SYNTAX
void stpapi.enum.answer(string session, string question, bset
answer)
ARGUMENTS
session
on.
Name of the session this command is executed
question
Baan question code. This question code
must be valid within the session i.e. the session
must ask this question when the user interface is
used.
answer
The enum or set answer to be supplied as answer
to the question. This has to be expressed as the
enum value as opposed to the numeric equivalent
e.g. tcyesno.yes vs 1.
DESCRIPTION
Template
13
Appendix A AFS Example
This sets the answers to questions that occur while the session is
executing.
RETURN VALUES
4.Appendix A AFS Example
None.
The following is the AFS for the Maintain Areas (tcmcs0145m000)
session in Baan.
|-----------------------------------------------------------------------------| File created by ttstpcreatdll, Date: 17/02/99
| Created for session: tcmcs0145m000
|-----------------------------------------------------------------------------#pragma used dll ottstpapihand
function extern void f0145m000.put.Area( const domain tccreg value
)
{
DLLUSAGE
Function to set Area ( tcmcs045.creg ) in session tcmcs0145m000
arg: - value to put in Area
ENDDLLUSAGE
stpapi.put.field( "tcmcs0145m000", "tcmcs045.creg", value )
}
function extern domain tccreg f0145m000.get.Area( )
{
DLLUSAGE
Template
14
Appendix A AFS Example
Function to get Area ( tcmcs045.creg ) from session
tcmcs0145m000
return: - value of Area
ENDDLLUSAGE
string value(3)
stpapi.get.field( "tcmcs0145m000", "tcmcs045.creg", value )
return( value )
}
function extern void f0145m000.put.tcmcs045.dsca( const domain
tcdsca value )
{
DLLUSAGE
Function to set tcmcs045.dsca ( tcmcs045.dsca ) in session
tcmcs0145m000
arg: - value to put in tcmcs045.dsca
ENDDLLUSAGE
stpapi.put.field( "tcmcs0145m000", "tcmcs045.dsca", value )
}
function extern domain tcdsca f0145m000.get.tcmcs045.dsca( )
{
DLLUSAGE
Function to get tcmcs045.dsca ( tcmcs045.dsca ) from session
tcmcs0145m000
return: - value of tcmcs045.dsca
ENDDLLUSAGE
string value(30)
mb
stpapi.get.field( "tcmcs0145m000", "tcmcs045.dsca", value )
return( value )
}
function extern void f0145m000.end( )
{
Template
15
Appendix A AFS Example
DLLUSAGE
Function to end connection to session tcmcs0145m000
ENDDLLUSAGE
stpapi.end.session( "tcmcs0145m000" )
}
function extern void f0145m000.insert( long do.update, ref string
error )
{
DLLUSAGE
Function to insert a record in session tcmcs0145m000
Fields must be put before calling this function
ENDDLLUSAGE
stpapi.insert( "tcmcs0145m000", do.update, error )
}
function extern void f0145m000.update( long do.update, ref string
error )
{
DLLUSAGE
Function to update a record in session tcmcs0145m000
Record must be made current and fields to be changed before
calling
this function
ENDDLLUSAGE
stpapi.update( "tcmcs0145m000", do.update, error )
}
function extern void f0145m000.delete( long do.update, ref string
error )
{
DLLUSAGE
Function to delete a record in session tcmcs0145m000
Record must be made current before calling this function
Template
16
Appendix A AFS Example
ENDDLLUSAGE
stpapi.delete( "tcmcs0145m000", do.update, error )
}
function extern void f0145m000.save( ref string error )
{
DLLUSAGE
Function to save an update/insert/delete in session
tcmcs0145m000
ENDDLLUSAGE
stpapi.save( "tcmcs0145m000", error )
}
function extern long f0145m000.find( )
{
DLLUSAGE
Function to find a record in session tcmcs0145m000
Search fields must be put before calling this function
ENDDLLUSAGE
return( stpapi.find( "tcmcs0145m000" ) )
}
function extern long f0145m000.first( )
{
DLLUSAGE
Function to find the first record in session tcmcs0145m000
ENDDLLUSAGE
return( stpapi.browse.set( "tcmcs0145m000", "first.set" ) )
}
function extern long f0145m000.next( )
{
DLLUSAGE
Template
17
Appendix A AFS Example
Function to find the next record in session tcmcs0145m000
ENDDLLUSAGE
return( stpapi.browse.set( "tcmcs0145m000", "next.set" ) )
}
function extern long f0145m000.previous( )
{
DLLUSAGE
Function to find the previous record in session tcmcs0145m000
ENDDLLUSAGE
return( stpapi.browse.set( "tcmcs0145m000", "prev.set" ) )
}
function extern long f0145m000.last( )
{
DLLUSAGE
Function to find the last record in session tcmcs0145m000
ENDDLLUSAGE
return( stpapi.browse.set( "tcmcs0145m000", "last.set" ) )
}
function extern void f0145m000.recover( ref string error )
{
DLLUSAGE
Function to undo an update/insert/delete in session
tcmcs0145m000
ENDDLLUSAGE
stpapi.recover( "tcmcs0145m000", error )
}
function extern string f0145m000.get.last.message.code( )
{
DLLUSAGE
Template
18
Appendix A AFS Example
Function to get the code of the message which occurred on
the last insert/update/delete/save/recover action in session
tcmcs0145m000
ENDDLLUSAGE
return( stpapi.get.mess.code( "tcmcs0145m000" ) )
}
function extern void f0145m000.handle.sub.process( const string
sub.process, const string action )
{
DLLUSAGE
Function to define an action when a sub process is started.
Possible actions are: add/send/ignore/kill
add
- add child session to internal structure,
session dll of child can be used
send
- send all api calls to child instead of parent
ignore - child process is ignored, parent will wait
until child exits (for background processes)
kill
- child process is killed immediately
ENDDLLUSAGE
stpapi.handle.subproc( "tcmcs0145m000", sub.process, action )
}
function extern void f0145m000.define.enum.answer( const string
question, bset answer )
{
DLLUSAGE
Function to define an answer on a question, when the default
answer should not be taken.
ENDDLLUSAGE
stpapi.enum.answer( "tcmcs0145m000", question, answer )
}
Template
19
