Вы находитесь на странице: 1из 24

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

Вам также может понравиться