Go Back
3 Votes

Documentation Should Be Enhanced To Describe xfpl.dbr


Accepted

Spun off from "synxfpng Utility Should Be Enhanced to Attempt To Invoke xfpl.dbr" (https://synergexresourcecenter.force.com/apex/SiteIdea?id=0870d000000TgCEAA0)

xfpl.dbr, I refer to this as "the xfServerPlus Bootstrapping Process", however some Synergex documentations refers to this as "the xfServerPlus program", from the outside looking in appears to be a critical program that performs at least the following functions:

  1. It appears that shortly after a connection is made to the service port this program is attempted to be launched. Misconfiguration of the xfServerPlus service results in the error 
    Unable to read data from the transport connection: An existing connection was forcibly closed by the remote host. ---> System.Net.Sockets.SocketException: An existing connection was forcibly closed by the remote host
    due to the socket immediate exiting
  2. I know from experience that when xfServerPlus is configured to be debuggable that xfpl.dbr is the responsible program for throwing the initial break point. My recollection is that this throws from launcher.dbl around line 400 or so.
  3. At some point (based on assumption) must somehow invoke the declared ELB from the xfServerPlus request. The assumption is that it performs some type of xsubr, which is why the SMC is so critical (as this contains the offsets to the functions, amongst other things).
  4. I know from existing documentation that part of its responsibility is the reading of xfpl.ini and the loading of variables defined there in.

It is alluded to several times within the online documentation but no mental model or block diagram is presented to document its purpose.

The existing documentation is thin:

https://www.synergex.com/docs/#xfnl/xfnlAppAXfserverplus.htm
>Each time an xfServerPlus session is started, xfpl.dbr reads the settings in the xfpl.ini file. Note that if you have set SFWINIPATH to point to the location of your synergy.ini file, the dbs runtime will read the synergy.ini file.

https://www.synergex.com/docs/#evso/evsoChap1XFPLDBR.htm
>By default, the xfServerPlus program (xfpl.dbr)

https://www.synergex.com/docs/#xfnl/xfnlChap3Usingthexfplinifile.htm
>The xfpl.ini file is read by xfpl.dbr each time an xfServerPlus session is started.

We desire that this process be explicitly documented.
 

2 Comments | Posted by Ace Olszowka to xfServerPlus, Documentation on 4/16/2020 6:16 PM
Steve Ives
Hi Ace,

As you may have noticed, this idea was accepted. We're going to allocate some Tech Writer time to bolster up the xfServerPlus documentation in this area. But we want to make sure we are addressing your specific needs. Clearly, we're not going to document what every line of code does; we're assuming you're looking for a high-level description of the major things that that happen during the lifetime of an xfpl.dbr process, from being assigned to a connection, through the termination of that connection? Would you please take a few minutes to provide some additional information about any specific type of information that you are hoping to see.

6/22/2020 10:15 PM   0  
Ace Olszowka
Yeah I don't think we need the line by line blow like you mention; but stuff that developers intuitively learn over time should be written/documented to ensure that we don't suffer from Tribal Knowledge (https://en.wikipedia.org/wiki/Tribal_knowledge) when it comes to how this works.

Imagine that the responsibility for re-implementing xfServer+ was given to a brand new developer, the original source code to this product was lost, what pieces of information would they need to recreate the product?

Obviously there will be some "secret sauce" in here, you can leave those parts out but other bits of information are important, such as those that I outlined above:
  • There is some process that is responsible for listening for commands on a socket that then launch xfpl.dbr
  • xfpl.dbr is responsible for throwing the initial breakpoint if it is configured to do so (link to the configuration page here)
  • xfpl.dbr is responsible for setting up various environment variables that would have been defined in xfpl.ini
  • xfpl.dbr is responsible for loading the customer ELB

Each of those points is important for building a mental model of how the system works. There are hints of this design scatted throughout the documentation, and after awhile developers working in the system long enough build up this mental model. However it is not formally documented anywhere.

It is difficult to write this type of documentation because we often under-estimate the amount of knowledge/skill/familiarity we have built up with the system. While it allows those developers who have this experience to work very quickly in the system, it makes it difficult to onboard new developers. Eventually this will kill your company, and everything you worked for. Dan Luu has called this the Normalization of deviance (https://danluu.com/wat/), especially when the processes are not clearly declared:
 
People don't automatically know what should be normal, and when new people are onboarded, they can just as easily learn deviant processes that have become normalized as reasonable processes.

6/26/2020 1:35 PM   0  
Please log in to comment on this idea.