Added Mapepire description and settings

[sebjulliand]

Changes

This PR adds a new Mapepire sub-section to the Settings section.

It describes what single mode and server modes are and explains each settings exposed in Code for IBM i.

@SJLennon please feel free to have a look as well and tell me if this needs to be improved or if something is missing. You have a keen eye for that 😉 Thanks.

Checklist

• have tested my change

[SJLennon]

@sebjulliand Not sure is this is the best way to comment, since I have never commented on a PR before. Also, be aware that I rarely see a document I don't want to edit, but you did ask me to look 😦.

Single Mode question: "Every connection made from VS Code this way creates a Mapepire Java process." Is this saying a JVM is started up in each action request made to the IBM i? Maybe I have confusion between the initial session connection and subsequent SSH connection requests in that session. Possibly I don't understand "Mapepire is started in the SSH channel". What I'm trying to figure out is there any advantage/overhead/performance running server vs single, other than in single there is the JVM start up in the initial connection, and should there be something said about server mode being better (?). I remember Bob Cozzi having delay issues in his Cl prompter (which server mode might help).

Bearing the above in mind, here are some suggested restructurings, based on my current understanding:

Single mode

The default mode used by Code for IBM i. Mapepire is started by Code for IBM i in the SSH channel opened from VS Code, when you first connect to the IBM i. On the IBM i it creates a Java JVM that exists until you disconnect.

Think of Mapepire as a bridge between VS Code and Db2 for i in this case. The single mode is started using --single as an argument when running the mapepire.jar file.

Single mode does not require a HTTPS connection and this may be easier if there are network restrictions. But when connecting, starting Mapepire adds the overhead of starting a JVM which can be slow on IBM i. And if there are many connections more IBM i resources may be consumed which might be significant on a smaller machine. And using the Db2 for i extension also creates a JVM.

Server mode

Mapepire is assumed to have been started beforehand and is running on IBM i. It acts as a shared database server, handling every connection coming from clients (through HTTPS, by default on port 8076). This one server is used by everyone and to maintain security it must know your password.

Mapepire server mode is started using no argument when running the mapepire.jar file. See Server Install/Config

Server mode makes the connection faster and it consumes fewer resources globally on the IBM i. But it requires more initial work on the sys admin side to set up and ensure it is running.

[sebjulliand]

Thanks a lot for lookimg at that @SJLennon !

Is this saying a JVM is started up in each action request made to the IBM i? Maybe I have confusion between the initial session connection and subsequent SSH connection requests in that session. Possibly I don't understand "Mapepire is started in the SSH channel".

Here is a simple description I've found online that may help understand that concept:

The SSH protocol requires that requests for services on a remote machine be made over channels.
A single SSH connection may contain multiple channels, all run simultaneously over that connection.

When Code for i connects through SSH, it opens one channel to run shell commands. Then, if Mapepire is used in single mode, another channel will be open to run Mapepire. In that channel, Mapepire will listen for reauest sent over the channel and reply on it. Havinh Mapepire running in that channel instantiate a JVM.

If the Db2 extension is installed, it will also start a channel to run Mapepire (Db2 extension uses its own DB job).

I could list the pros/cons for single vs server mode. But basically, single mode doesn't require an HTTPS connection besides the SSH connection. It all runs through SSH which makes it easier if there are network restrictions. But starting Mapepire adds an overhead when connecting (starting a JVM is notoriously slow on IBM i). And since it crates one JVM per channel, it means that 20 users connected in single mode spawns 20 JVM (40 if they all use the Db2 extension 😓 ).

Server mode requires to have Mapepire up and running on the IBM i and the capability to reach it over the network. But it makes the connection faster and it consumes less resources globally on the IBM i. But it requires more initial work on the sys admin side 😄

[SJLennon]

@sebjulliand Thanks for the explanations. I edited my original comments based on what you said. Hope this helps.

[sebjulliand]

Perfect; thanks a lot @SJLennon !