digging existing Forté code

what can be done of all that?

first stop ... 

using the previous thingies you may now be able to have a look at what is in $FORTE_ROOT/userapp/forte/cl0/forte.btd

a set of instruction is available here

an export of the Forté distributed apps is there

once imported have look at the plan named ‘ide’

enjoy browsing the Forté 4GL Workshop into the Forté 4GL Workshop ... mind boggling what the lads at Forté inc. managed to do. init?

 

internals of distributed apps

when an Object (eg mySO based on DistObj) is made remotely available Forté creates behind the scenes a class DistObjproxy that inherits from qqlo_Proxy and DistObj, it aplies to ANCHORED objects too.

there is only one class DistObjproxy created no matter how many SOs are based on that class, the multiple instanciation happens at runtime (the DistObjproxy is a class, the SO is an Object instanced using ImmobileInstanceAlloc as opposed to InstanceAlloc called on the ClassType when the ‘= new()’ statement is executed)

at runtime a method call on a SO translate into
GETGLOBALVAR 0
PUSHOBJECT 0 Rank of the SO in the list (looks like it's equal to SO_id - 1)
METHOD 3, 2


everything about GUIs and IRblock applies to distributed applications like forte.btd
but there are a couple of things that are not available directly in the runtime repository (at least I don’t know where)

when an application is distributed Forté creates 2 files suffixed .ace & .adf

the .ace file contains a serialised qqem_DistributionCatalogEntry used when econsole / escript lists the available, loadable distributions

the .adf is a qqem_StandardApp and contains the layout of SOs and their attributes (visibility, dialog duration)

so reading the .ace file makes you aware of the distributed layout.

internal Code storage __ qqrt_IRBlock

qqrt_IRBlock : how to get access to its attributes.

qqrt_IRBlock shows many attributes defined as pointers the good old $TOOCOMPLEX type.
unfortunately Forté as a 4GL does not allow you to set the pointee of a pointer, so just set pointer to the qqrt_IRBlock you want to inspect and load it in a BinaryData ... read at the requested offset something like

to get the list of pointer attributes

ptrIRB : pointer to char;
ptrIRB = (pointer to char)((pointer)(my_qqrtIRBlock));
myMemStream : MemoryStream;
myMemStream = new();
myMemStream.Open(SP_AM_READ_WRITE, TRUE);
myMemStream.UseData(ptrIRB, ClassType(qqrt_IRBlock).Size);


an Object is a pointer but the MemoryStream to be set requires a pointer to char ... so be it!


extracting the value of lets say qqrt_IRBlock. DoubleArray


linkedArray : BinaryData = new();
if my_qqrtIRBlock.DoubleCount > 0 then
voidBinaryData : BinaryData = new();
myMemStream.OffSet = 0x48;
myMemStream.ReadBinary(voidBinaryData, 4);
linkedArray.SetValue((pointer)(*(pointer to pointer)(voidBinaryData.Value)), my_qqrtIRBlock.DoubleCount * 8);
end;
BinaryData.Value is a pointer but we need to be able to read what is pointed as a pointer hence the silly recast (pointer to pointer) and the de-referencing and again the recast as (pointer)

migrating Forté 4GL TOOL source code

source code

... the easy not part ...

a method’s original source code is available in a ‘meta’ instance of internal Forté class called qqc4_Method

always better than parsing the Workspace export, it is possible to traverse the user’s plans in the workspace and generating txt files for every class traversed.

and the source in the watches

but still tedious since the source code has to be parsed by hand.

there might be a way out of this, a qqc4_Method when parsed & “compiled” using ‘Shift + Ctrl + C’ gives birth to a qqrt_IRBlock that can be seen in the log window when the flag trc:c4:3-5:10 is turned on and ‘Shift+Ctrl+C’ pressed on a compilable entity.

it spews
a bunch of object types & IDs
a bunch of Vars, Strings
a stream of assembly like commands

how to work out IDs? IDs are (a, b) ‘a’ being the plan ID and ‘b’ the class ID in that plan
see MS Access DB ForteIDs
this table also contains the Method, Attribute ... IDs for a given class.

the header can be read with that table here

the IR instructions are listed here next to the “mnemonic” code is the instruction name and the list of parameters. going down there is a mention made of a future ‘R4’ ... this day may never come.

at that point there is a way to generate a bunch of instructions based on that.

scanning Forté 4GL UDS GUIs

... the easy part ...

the Forté GUIs are not compiled at all, even in a C++ produced Forté applications the GUIs are still displayed through the VM interpreter. as a token you may have noticed the way Forté exports GUIs in a .wex, .pex or .cex file a blob of Hex, the produced C++ bears the same value in an binary array var.

now as the GUIs code is not compiled it is preserved in a way that makes things easy to crawl through all the items that constitute a _Window object.

as per the screen copy supra, opening the workspace and crawling the plans, classes ...

with the following snippet

aVoidObj now references an Array that contains the class definition of the example window

having a look at the local variables

the tree like structure describes all the items that the window is made of.

it is now only a matter of carefully matching the Forté ‘FieldWidget’ or ‘MenuWidget’ to the ones available to the target platform. all the attributes as bound objects, size, placement, visibility, behaviour and more are available through the Widget (or child classes) attributes and methods.

time consuming but not rocket science.

producing Forte 4GL (UDS) GUIs

... the easy part ...

the Forté GUIs are not compiled at all, even in a C++ produced Forté applications the GUIs are still displayed through the VM interpreter. as a token you may have noticed the way Forté exports GUIs in a .wex, .pex or .cex file a blob of Hex, the produced C++ bears the same value in an binary array var.

now as the GUIs code is not compiled it is preserved in a way that makes things easy to crawl through all the items that constitute a _Window object.

as per the screen copy supra, opening the workspace and crawling the plans, classes ...

with the following snippet

aVoidObj now references an Array that contains the class definition of the example window

having a look at the local variables

the tree like structure describes all the items that the window is made of.

it is now only a matter of carefully matching the Forté ‘FieldWidget’ or ‘MenuWidget’ to the ones available to the target platform. all the attributes as bound objects, size, placement, visibility, behaviour and more are available through the Widget (or child classes) attributes and methods.

time consuming but not rocket science.

migration from Forté 4GL (UDS) to Java, C#, Obj-C ...

UDS formerly Forté 4GL has been EOL’d.

amazingly enough UDS 5.2.4 is still the core part of Sun ONE Integration Server EAI 3.2 that has not been EOL’d as yet.

apparently Sun is still committed to fixing defects but not making any architectural changes to Integration Server EAI.

anyway time to migrate ... where to start from & to where ???

before being merged with/into Sun, Forté was shipping a Java version of Framework classes. according to the Forté documentation

The IIOP-Java mode is different from the IIOP-IDL mode in the following ways:

(a) No IDL file is required because Forte generates all the Java client and server stubs/skeletons classes. This also means, without the intermediate IDL representation, there is little or no lost of datatype mappings between TOOL/Java. The generated classes are dependent on the Forte Java library, $FORTE_ROOT/install/lib/java/forte.zip at both development time and runtime.

(b) Support for object passing-by-value. In the IDL mode, an object cannot be passed - only its reference is passed. Note that object references are still being
used in IIOP-Java mode.

(c) Support for Forte Framework datavalue subclasses. In the IDL mode, the Framework datavalue subclasses were flattened into structs (method-less Java classes). In the Java mode, these datavalue subclasses can be passed by value, appearing as true objects over at the Java end.

(d) Support for TOOL input parameter mode on Forte Framework datavalue subclasses. A Java client passing an input parameter to a TOOL server can expect any changes to be reflected at the client's end.

(e) Support for Unicode strings. In the IDL mode, the vendor's marshalling code truncates Unicode strings (16-bit character-width) into ISO-88591 strings (8-bit character-width). In the Java mode, Forte handles the marshalling with full Unicode support (i.e. no
truncations).

which means some of the Java classes needed to accommodate the transposed Forté code are already available.

but how to get the code transposed ...

hidden plans in Forte 4GL (UDS)

starting the IDE in a standard and supported manner keeps many plans hidden. but opening the empty development repository that is btseed.btd with vi or notepad reveals a couple of intriguing names ... TOOLCompiler, TOOLInterpreter, Configuration & BTree mixed with others like Framework & Display.

fortunately fscript allows us to drag in qqAllForteProjects that in turn drags all the previous named plans but AppModel & BTreeRepository.

once all the plans are there and we can freely search them, there are a couple of classes prefixed with qqxx_ that look interesting

the next thing is run the ftexec -fi bt:$FORTE_ROOT/yadihadiha through the debugger to see where are the qq classes are being used. in this the luck is with us ; the dev version of the runtime has been compiled with the (-g or /Zi) so all the method names, even not exported are readable, plus the assembly code is piece of cake to read since there is not any optimisation so all the parameters are pushed on the stack (x86) (UltraSPARC all but the first 5 that are registers)


and soon enough a workspace can be opened using the IDE ... and browsed.

same thing for the application’s btd.

Forte 4GL (UDS) basics - agents

Forte 4GL (UDS) basics - code containers

Forté uses a proprietary format to store and manage code.

the format brings powerful features as code control, versioning & consistency, the drawback being it's not a set of text files. but since Forté is writing to and reading from those files as well as exporting/importing to/from text files using the IDE, there is some hope that it's possible to write our own specific 'FortéPad'.

btree & other code containers
in the latest Forté versions the container is a file with a .btd extension, along is a .btx file that contains an index for faster access and a .rop that is used in case the .btd file becomes corrupt.

interpreted applications and development repositories both reside in .btd files.

the .btd known as BTreeRepository was not always the norm. Forté used other formats like
CtreeRepository
GemstoneRepository
ObjectivityRepository
SQLRepository revealing that Forté Software Inc may have tried to use SQL Stores as development container.

Forte 4GL (UDS) basics - main binaries

nodemgr:
flags
-fns IPv4:port starts
name service

-e envName
environment manager

-fnd nodeName
node manager

ftexec:
interprets anyApp.btd files

rpstart rpstop rpserver:
to start development repositories.

personal: never use the automated install on Windows and get used to starting environment, repositories & application using batch files. this avoids env var contention and keeps the environment clean. this was supposed to help but it does not if you run several different versions of Forté or connect to different environments ... and as a developer it prevents sysadmin shuting down your forté executor bringing to a halt your IDE ... I confess I did it many times.

viva -fi, -fm, -fns, -fnd, -e, -n ...

Forte 4GL (UDS) basics - agents

one of the unmatched strength of Forté: System Agents.

a system agent manages an object in a deployed application, that is at run time it is possible to execute some commands and inspect some instruments on the managed object.

usually those commands have to do with monitoring and tuning an application but they may interfere with the business logic e.g. the possibility to bump up the queue a batch file to be processed asap even though there is no dedicated interface to do so.

these agents are visible using the provided tools eConsole or escript or any in-house tool.

the console






the partition agent & sub agents




the available instruments and values.

Forté 4GL (UDS) basics - runtime

to run an application across different heterogeneous sets of servers and clients Forté makes use two alternatives available, use the platform specific C/C++ compiler and use a virtual machine.

virtual machine
Forté relies on a “layer” to level off the differences among platforms: ftexec (+ libraries) this is the Forté virtual machine that runs anything (compiled or interpreted) developed with the Forté IDE.

compiled vs. interpreted
interpreted: ftexec takPublish Postes a .btd file as input
compiled: the produced executable is linked with ftexec.o

the way Forté manages to mix interpreted & compiled code is utterly clever, in the IDE most of the plans are 3GL objects made available to 4GL code, but some of the plans (AppModel, HTTPSupp, IIOP, LDAP, OLE, XMLSvr & XSLT) are 4GL TOOL interpreted projects.

the IDE itself is an interpreted bit of code (that has some interesting implications ... later) that can be ran with the following command :

ftexec -fi bt:$FORTE_ROOT/userapp/forte/cl0/forte -fr myRep -fw myWKS -fns myEnvNode:port

Forté 4GL (UDS) basics - transaction

one very nice feature of Forté is the integrated transaction monitor. when a transaction fails it takes a little bit of work to figure out what are the objects to rollback, that requires a snapshot of these object prior starting the transaction process.

with Forté mark the objects taking part to the transaction as "transactional" set the transaction boudaries and do the job, if anything causes the transaction to abort the objects are rolled back. the end.

a nice beahaviour that may be tricky to achieve when porting the code to a different platform.

Forté 4GL (UDS) basics - distribution

to make a application run on several different servers, Forté uses a specific object called Service Object.

basically a standard class (DummyMgr) is marked as distributed.
then a service object (by convention named DummyMgrSO) based on DummyMgr is defined in the Workshop. behind the scenes Forté creates a proxy that exports all attributes and methods of DummyMgr thus making them remotely available to clients.

the application is partitioned, the first time Forté defines a default partitioning that can be amended, and installed in a given environment on a given server.

the application is registered with the environment manager, once started the DummyMgrSO is registered with the name service so any client with a TCP/IP connectivity to the environment can get a reference to the DummyMgrSO and call methods or set/get values or variables on it. (accessing attributes may be arguable it is possible).

Forté 4GL (UDS) basics - workshop

Forté 4GL is an IDE, it all happens in one place. the Design, the Development, the Versioning, the Deployment & the Monitoring.

a development team has a Forté environment and a shared development Repository, each member has a Workspace in this repository that they access using the Forté Workshop.

from the Workshop (usually called Studio outside Forté Software Inc.) the team member can create, check in, check out classes, synchronise his Workspace with others, define a logical partitioning of the application and deploy the logical parts to remote servers. the only thing that needs another tool is the monitoring.
this is done through an environment console called eConsole and used to load application definition, install the application fragments on the relevant servers, start or stop them, view the logs or modify runtime parameters.

the used language is called TOOL for Transaction Object Oriented Language.

there is weakness though, there aren't any modelling tools per say, and getting a clear picture of the class tree and class relation diagram is not easy.

Forté 4GL (UDS) basics

virtual machine
the Forté Application Environment (Forté from now on) relies on a “layer” to equalise the differences amongst platforms: ftexec (+ libraries)
this is the Forté virtual machine that runs anything (compiled or interpreted) developed with the Forté IDE.

compiled vs. interpreted
interpreted: ftexec takes a .btd file as input
compiled: the produced executable is linked with ftexec.o

the way Forté manages to mix interpreted & compiled code is utterly clever, in the IDE most of the plans are 3GL objects made available to 4GL code, but some of the plans (AppModel, HTTPSupp, IIOP, LDAP, OLE, XMLSvr & XSLT) are 4GL TOOL interpreted projects.

the IDE itself is an interpreted bit of code (that has some interesting implications ... later) that can be ran with the following command :

ftexec -fi bt:$FORTE_ROOT/userapp/forte/cl0/forte -fr myRep -fw myWKS -fns myEnvNode:port

btree & other code containers

source code lives in text files so it's easy to version and archive. but Forté has its own version control & concurrency access mechanism and it all resides in the .btd & .btx

note for later: interpreted installed applications and development repositories both reside in a .btd file. btree not always the norm up to 3.0.G there used to be ctree & objectivity repositories, there are also clues that Forté Software Inc may have tried to fit the repositories into some SQLRepositories

from Forte 4GL to UDS : a bit of history

Forté founded 02/1991, the staff chained to their desks for more than three years before shipping the product 08/1994, became profitable the next year and things went pear shape from 04/1997. To cut a loss story short, 08/1999 merger with Sun complete, Forté is an iPlanet product with a Sun logo, 2002 the iPlanet Sun|Netscape alliance is over and Forté is Sun ONE Unified Development Server (UDS) with an iPlanet logo ... trivial

PRODUCTS

Forté 4GL or Forté TOOL (ADE)

The very core of the Forté's offer. Define, Version, Distribute, Build, Deploy & Monitor all in one place. Specific language: Transactional Object Oriented Language (TOOL). DevStudio provided. Multi platform (Windows, MacOS, Tru64, Alpha Open VMS, HP9000 HP-UX, OS/390, RISC/6000 AIX, Sequent Dynix/ptx, Sun SPARC SunOS,) & multi DB (DB2, Informix, Ingres, SQL Server, Oracle, Sybase & ODBC)

Applications can be distributed across a heterogeneous array of clients and servers, run in interpreted (Forté VM) or C++ compiled, integrated with external systems using Java, C, C++, XML, OLE ...


Forté Express (04/1996)

A RAD tool to generate business model and matching DB layout & access.


Forté WebEnterprise (12/1997)

A deployment add on to Web enable Forté 4GL application by generating the necessary plumbing and GUIs to be served through MS IIS (ISAPI) or NES (NSAPI or ForteCGI).


Forté Conductor (9/1997)

A GUI based workflow design environment with the ability to analyse the work in progress.

Forté 4GL UDS Sun ONE Unified Development Server

Forte 4GL UDS Sun Unified Development Server
a series of articles about Forté 4GL (UDS) undocumented features and what can be done of them.