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 !

[SanjulaGanepola]

Server mode (through HTTP).

@sebjulliand Throughout this doc and in the diagram, I see we mention that server mode uses HTTP where in fact it would use secure web sockets. Shall we correct that?

[SanjulaGanepola]

Suggested change

	Since version 3, Code for IBM i uses Mapepire to access Db2 for i and run queries. Mapepire is a database access layer that can be used in Single mode (through Code for IBM i SSH channel) or in Server mode (through HTTP).
	Since version 3, Code for IBM i uses [Mapepire](https://mapepire-ibmi.github.io/) to access Db2 for i and run queries. Mapepire is a database access layer that can be used in Single mode (through Code for IBM i SSH channel) or in Server mode (through HTTP).

[SanjulaGanepola]

Suggested change

	Mapepire can run in two distinct mode. The mode used by Code for IBM i is determined by the `Connect to remote Mapepire server` connection settings described below.
	Mapepire can run in two distinct modes. The mode used by Code for IBM i is determined by the `Connect to remote Mapepire server` connection settings described below.

[SanjulaGanepola]

Some of what is in this paragraph looks to be a repeat of the last such as the first sentence was repeated. Was that intentional?

[SanjulaGanepola]

Suggested change

	When connecting and using single mode, Code for IBM i will upload the Mapepire jar file under the current user `.vscode` folder under their home directory before starting Mapepire. (i.e. the remote file is `~/.vscode/mapepire-server-X.Y.Z.jar`). Code for IBM i takes care of checking and updating the jar file when needed.
	When connecting and using single mode, Code for IBM i will upload the Mapepire jar file under the current user's `.vscode` folder under their home directory before starting Mapepire. (i.e. the remote file is `~/.vscode/mapepire-server-X.Y.Z.jar`). Code for IBM i takes care of checking and updating the jar file when needed.

[SanjulaGanepola]

it must know your password.

What did you mean by this part?

[SanjulaGanepola]

Again, the first sentence looks to be repeated from the last paragraph. Was that on purpose?

[SanjulaGanepola]

Suggested change

When using Server mode, Mapepire is assumed to be started beforehand and running on IBM i. As its name implies, it acts as a server, handling every connection coming from clients on port `8076`, by default. One server is used by everyone. Mapepire is not meant to be started from by clients in this case, it wouldn't make sense. hence why it is assumed that it will be running on the remote IBM i. Every client connects to it through HTTPS.

When using Server mode, Mapepire is assumed to be started beforehand and running on IBM i. As its name implies, it acts as a server, handling every connection coming from clients on port `8076`, by default. One server is used by everyone. Mapepire is not meant to be started from by clients in this case, it wouldn't make sense. Hence why it is assumed that it will be running on the remote IBM i. Every client connects to it through HTTPS.

[SanjulaGanepola]

Suggested change

	<Card>Every Mapepire client settings a regrouped under the connection settings' `Mapepire` tab.</Card>
	<Card>All Mapepire client settings are regrouped under the connection settings' `Mapepire` tab.</Card>

[SanjulaGanepola]

This also looks to be a repeat of the sentence above.