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.