Merge pull request #110 from codefori/mapepireDoc

Added Mapepire description and settings

Author: SanjulaGanepola

.astro/astro/content.d.ts

@@ -509,6 +509,13 @@ declare module 'astro:content' {
   collection: "docs";
   data: InferEntrySchema<"docs">
 } & { render(): Render[".mdx"] };
+"settings/mapepire.mdx": {
+	id: "settings/mapepire.mdx";
+  slug: "settings/mapepire";
+  body: string;
+  collection: "docs";
+  data: InferEntrySchema<"docs">
+} & { render(): Render[".mdx"] };
 "settings/profiles.mdx": {
 	id: "settings/profiles.mdx";
   slug: "settings/profiles";
@@ -638,5 +645,5 @@ declare module 'astro:content' {
 
 	type AnyEntryMap = ContentEntryMap & DataEntryMap;
 
-	export type ContentConfig = typeof import("../../src/content/config.js");
+	export type ContentConfig = typeof import("./../../src/content/config.js");
 }

.astro/settings.json

@@ -1,5 +1,5 @@
 {
 	"_variables": {
-		"lastUpdateCheck": 1782633265498
+		"lastUpdateCheck": 1784908943237
 	}
 }

src/assets/settings/mapepire_01.png

@@ -16,9 +16,6 @@ The Db2 for i extension allows users to browse database schemas, execute SQL sta
 
 The extension can be [installed from the Marketplace](https://marketplace.visualstudio.com/items?itemName=HalcyonTechLtd.vscode-db2i)<Icon name="external" color="cyan" class="icon-inline" /> and is also part of the [IBM i Development Pack](https://marketplace.visualstudio.com/items?itemName=HalcyonTechLtd.ibm-i-development-pack)<Icon name="external" color="cyan" class="icon-inline" />.
 
-### Server Component
-
-As of 0.3.0, the Db2 for i extension requires a server component. The component provides improved performance and makes it easy for us to add advanced features. The Db2 for i extension manages the server component installation when you connect to an IBM i with Code for IBM i and will ask the user to confirm any installation or update. The server component is installed into `$HOME/.vscode`, which means a per-user installation. [The server component is also open-source](https://github.com/Mapepire-IBMi/mapepire-server)<Icon name="github" class="icon-inline" />.
 
 ## Executing Statements
 

src/assets/settings/mapepire_02.png

@@ -13,6 +13,7 @@ import { CardGrid, Card, Badge, LinkCard, Icon } from '@astrojs/starlight/compon
    - (Licensed program 5733-SC1 provides SSH support.)
    - `STRTCPSVR *SSHD` starts the daemon.
    - User `QSSHD` is enabled.
+- Java 8 minimum must be installed to run <a href="/docs/settings/mapepire/">Mapepire</a>
 - Some familiarity with VS Code. An introduction can be found [here](https://code.visualstudio.com/docs/getstarted/introvideos)<Icon name="external" color="cyan" class="icon-inline" />.
 
 Optionally, ensure you know how to connect to pase from a shell. See this [official IBM i OSS docs](https://ibmi-oss-docs.readthedocs.io/latest/user_setup/README.html#step-1-install-an-ssh-client)<Icon name="external" color="cyan" class="icon-inline" />.

src/assets/settings/mapepire_03.png

@@ -0,0 +1,70 @@
+---
+title: Mapepire
+---
+
+import { Aside, CardGrid, Card } from '@astrojs/starlight/components';
+
+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 a secure WebSocket).
+
+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.
+
+## Single mode
+The default mode used by Code for IBM i. Mapepire is started by Code for IBM i in an 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. Mapepire runs endlessly in its SSH channel, reading requests from the channel's standard input and replying on the channel's standard output.
+
+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.
+
+![assets/mapepire_01.png](/src/assets/settings/mapepire_02.png)
+
+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.
+
+Single mode does not require a separate 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 another SSH channel with its own 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 a secure WebSocket connection, by default on port `8076`). This one server is used by everyone and it doesn't support private keys and needs a password to maintain security. So you'll either enter a password every time you connect or save your password in your connection.
+
+Mapepire server mode is started using no argument when running the mapepire.jar file. See [Server Install/Config](https://mapepire-ibmi.github.io/guides/sysadmin/)
+
+![assets/mapepire_01.png](/src/assets/settings/mapepire_03.png)
+
+When connecting and using Server mode, Code for IBM i doesn't upload and use the Mapepire jar file.
+
+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.
+
+## Client settings
+<CardGrid>
+    <Card>All Mapepire client settings are regrouped under the connection settings' `Mapepire` tab.</Card>
+    <Card>![assets/mapepire_01.png](/src/assets/settings/mapepire_01.png)</Card>
+</CardGrid>
+
+### Use secure SQL connection
+Turning this on will force Mapepire to establish a secured JDBC connection (i.e. it sets the `secure` JDBC option to true). The connection is secured using `TLS` between Mapepire and the Database Server daemon (the `QZDASRVSD` job). Turning this on requires the Database Server daemon to use a valid certificate and accept connections on its secure port (`9471` by default). You can also read more about [configuring Host Servers with TLS using Navigator for i
+](https://www.ibm.com/support/pages/configure-host-servers-tls-using-navigator-i).
+
+### SQL Job Naming
+The naming convention used by the databse job. This setting will affect the syntax and how unqualified SQL objects are resolved.
+- **System**: system naming convention. Separator to qualify object can be `/` or `.`. The library list is used to resolve unqualified objects.
+- **SQL**: SQL naming convention. Separator to qualify objects is `.`. The current schema is used to resolve unqulified objects.
+
+### Keep action spooled files
+When enabled, spooled files generated by an Action will not be deleted once the action is done. Otherwise, any spooled file generated by an Action will be cleared after it's done.
+
+### Mapepire Java runtime (single mode)
+Select which version of Java should be used to run Mapepire in Single mode.
+- **Default**: use the default Java installation on the target LPAR (i.e. the Java installation used when running the unqualified `java` command).
+- **Java XX**: use Java version XX, where XX can be 8, 11, 17 or 21. Make sure you select a version that is actually installed on the target LPAR. 
+
+### Connect to remote Mapepire server
+When enabled, Code for IBM i will connect through a secure WebSocket to Mapepire.
+
+<Aside type="note">
+Enabling this setting means Code for IBM i will connect to a Mapepire server already started and running in server mode on the remote LPAR instead of running it in Single mode through SSH.
+</Aside>
+
+### Allow all certificates
+When enabled, this setting allows validation of either self-signed certificates or certificates from a CA when connecting to a remote Mapepire server.
+<Aside type="note">
+This must be enabled if no certificate has been configured when the Mapepire server was started on the LPAR.
+</Aside>
+
+### Remote Mapepire Server port
+The TCP port number Code for IBM will use when connecting to a remote Mapepire server. Defaults to `8076`.