Merge branch 'main' of github.com:halcyon-tech/docs

Signed-off-by: worksofliam <mrliamallan@live.co.uk>

Author: worksofliam

src/content/docs/developing/debug/image-1.png

@@ -61,15 +61,40 @@ To debug a program from the Object Browser, right-click on the program object an
 * IBM i Debug extension ([marketplace](https://marketplace.visualstudio.com/items?itemName=IBM.ibmidebug))
   * installed into Visual Studio Code
 * Debug Service Certificates setup
-  * created in `/QIBM/UserData/IBMiDebugService/certs` by default
-  * Debug Service certificate `debug_service.pfx`
-  * Debug Service client certificate `debug_service.crt`
+  * As of Code for IBM i 2.16.0, the Debug Service is configured inside of Navigator for IBM i. **If you're using Code for IBM i 2.16.0**, then you are required to use this method to configure and start the Debug Service. Code for IBM i 2.16.0+ supports only Debug Service 3+.
 
 ## Required PTFs
 
 To make use of the Debug Service, you need the following PTFs:
 
 <Tabs>
+<TabItem label="Version 3" >
+
+* IBM i 7.6
+   * Debug Service PTF SJ04601
+   * Navigator for i PTF SJ04647
+   * Java 17 LPP 5770JV1 Option 20 (not Java from Yum)
+* IBM i 7.5
+   * Debug Service PTF SJ05012
+   * Navigator for i PTF SJ03406
+   * Java 11 is required via LPP 5770JV1 Option 19 (not Java from Yum)
+* IBM i 7.4
+   * Debug Service PTF SJ05013
+   * Navigator for i PTF SJ03404
+   * Java 11 is required via LPP 5770JV1 Option 19 (not Java from Yum)
+* IBM i 7.3
+   * Debug Service PTF SJ05014
+   * Navigator for i PTF SJ03402
+   * Java 11 is required via LPP 5770JV1 Option 19 (not Java from Yum)
+
+**All OS versions require** 5770WDS option 60 (Workstation Tools - Base).
+
+* Java 11 information:
+   * `/QOpenSys/QIBM/ProdData/JavaVM/jdk11/64bit`
+   * [IBM documentation for PTFs](https://www.ibm.com/support/pages/download-installation-and-usage-java-11-ibm-i-os)   
+
+</TabItem>
+
 <TabItem label="Version 2.0.2" >
 
 * IBM i debug client v2.0.2 requires the following host PTFs:
@@ -112,158 +137,25 @@ After you have installed the PTFs, the connection inside of Visual Studio Code w
 
 ## Configuring & starting the service
 
-<CardGrid>
-<Card>
-After connecting to a system in Code for IBM i, you can hover over the connection in the bottom status bar to check the Debugger version and status. The status will be `on` if both the Debug Server and Debug Service are running.
-</Card>
-<Card>
-![](./debug6.png)
-</Card>
-</CardGrid>
-<CardGrid>
-<Card>
-Clicking on the Debugger status will take you to the IBM i Debugger view. This view shows the status of the Debug Server and the Debug Service. It also allows to start/stop the Debug Server and manage the Debug Service.
-</Card>
-<Card>
-![](./debug7.png)
-</Card>
-</CardGrid>
-
-### Start/stop the Server and Service
-<CardGrid>
-<Card>
-The start/stop/restart actions are located on the right of each status. Running one of these actions will refresh the statuses once it's done.
-</Card>
-<Card>
-![](./debug8.png)
-![](./debug9.png)
-</Card>
-</CardGrid>
-
-<Aside type="tip">
-   Starting and stopping the Debug Server and Service requires the *ALLOBJ special authority.
-</Aside>
-
-### Managing the Debug Service
-<CardGrid>
-<Card>
-If the Debug Service is not correctly configured, a warning sign will appear next to it. Expanding the Debug Service node will show the cause of the issue.
-</Card>
-<Card>
-![](./debug10.png)
-![](./debug11.png)
-</Card>
-</CardGrid>
-
-<Aside type="tip">
-   There only needs to be one instance of the Debug Service running and therefore the certificates should only be generated once. All developers share the Debug Service.
-</Aside>
-
-#### Generating certificates
-The Debug Service needs a certificate to be able to be started. This is required because the Debug Service is basically a web server exposing web services through HTTPS, and encrypting the traffic on HTTPS requires a certificate. Supported formats for the certificate are `PKCS12` and `JKS`. If Code for IBM i is used to generate the certificate, it will use the PKCS12 format.
-
-By default, certificates are generated in `/QIBM/UserData/IBMiDebugService/certs` (which is the recommended location). The path to the Debug Service certificate is set in `/QIBM/ProdData/IBMiDebugService/bin/DebugService.env` with `DEBUG_SERVICE_KEYSTORE_FILE`.
-
-If the certificate is missing, the IBM i Debugger view will show this error:
-
-![](./debug10.png)
-
-Clicking on the Setup Service Certificate button will start a process that offers to either generate a certificate or import an existing one (`PKCS12` format only). Once the certificate is successfully generated or imported, two files will be found under `/QIBM/UserData/IBMiDebugService/certs`:
-* `debug_service.pfx`
-  * the Debug Service certificate, used by the service to encrypt the communication.
-* `debug_service.crt`
-  * the client certificate that clients must download to be able to connect to the Debug Service.
-
-Generating the certificates will also update the Debug Service configuration file `/QIBM/ProdData/IBMiDebugService/bin/DebugService.env` to set the correct path to the required JDK and save the encrypted certificate password.
-
-If these certificates are deleted for some reason, they can be simply regenerated from the IBM i Debugger view as described above. They are used only to encrypt the traffic between the clients and Debug Service.
-
-It also possible to regenerate the certificates by right-clicking on the Debug Service and choosing `Regenerate service certificate`
-
-![](./debug14.png)
-
-If the client certificate cannot be found locally or does not match the remote certificate, Code for IBM i will show a warning in the IBM i Debugger view and offer an action to import the client certificate.
-
-![](./debug11.png)
-
-
-#### Starting the Debug Service from Code for IBM i
-Starting the Debug Service can be done from the IBM i Debugger view and requires `*ALLOBJ` special authority.
-
-![](./debug12.png)
-
-Clicking on the action to start the Service will first show a prompt showing `SBMJOB` parameters. Since the shell script that starts the service will be submitted, this lets you modify the submission parameters if needed. Only the `CMD` and `JOB` parameters are imposed.
-
-![](./debug13.png)
-
-Once the prompt is validated, the SBMJOB command will be executed and Code for IBM i will monitor its execution until the Debug Service is actually started (or fails to start).
-
-#### Starting the Debug Service outside of Code for IBM i
-If the Debug Service was configured from Code for IBM i (i.e the certificate was generated from Code for IBM i), then it is possible to start the Debug Service by running the same `SBMJOB` command that Code for IBM i uses:
-
-```
-SBMJOB CMD(STRQSH CMD('/QOpenSys/pkgs/bin/bash -c /QIBM/ProdData/IBMiDebugService/bin/startDebugService.sh')) JOB(DBGSVCE) JOBQ(QSYS/QUSRNOMAX) JOBD(QSYS/QSYSJOBD) USER(*CURRENT)
-```
-
-<Aside type="tip">
-   This will only work if Code for IBM i was used to configure the Service and generate its certificate.
-</Aside>
----
-
-## Debug Service ports
-
-The Debug Service depends on three ports by default:
-
-* Port 8001 (unsecure port)
-   * this port is not used for anything in regards to debugging, though it is required to start and stop the Debug Service
-* Port 8005 (secure port)
-   * this port is used by all debugging clients and is required to start the Debug Service.
-* Port 8008
-   * this port is used for Service Entry Breakpoint (*only applies to version 2 of the Debug Service*)
-
-While you can configure the ports in the Connection Settings, it is recommended the defaults are used for consistency.
-
-{/* These ports can be changed in `/QIBM/ProdData/IBMiDebugService/bin/DebugService.env`, both `DBGSRV_PORT` and `DBGSRV_SECURED_PORT` respectively.
-
-If `DBGSRV_SECURED_PORT` is changed, make sure to:
-
-* restart the Debug Service
-* reconnect every Code for IBM i instances. **Every user will need to do this step.** */}
-
-# FAQ
-
-### What's the difference between the Debug Service and Debug Server?
-
-<CardGrid>
-
-<Card>
-
-As depicted in this diagram, the client (VS Code, IBM i Debug) connects to the Debug Service, which talks to the Debug Server.
-
-* The Debug Service is started up inside of Visual Studio Code as documented above. In the future it will also be possible to start it from Navigator for i.
-* The Debug Server is started up with `STRDBGSVR`. You may get an error message in VS Code if you attempt to debug when the Debug Server is not running.
-
-</Card><Card>
-
-![](./debug4.png)
-
-</Card></CardGrid>
-
-### I can't see the variables when debugging CL
-
-<CardGrid>
-
-<Card>
-
-This is a limitation for CL. The local variables will not show up in the Variables view for CL. You can add a local variable to the Watch view to inspect its value. The CL limitation also exists in RDi.
-
-[See GitHub issue here](https://github.com/codefori/vscode-ibmi/issues/1069)<Icon name="github" class="icon-inline" />.
-
-</Card><Card>
-
-![](./debug5.png)
-
-</Card></CardGrid>
+This must be done with user that has *ALLOBJ and *SYSADM privlages.
+Below are the base requirements to configure the certificate: 
+- Master key 1 is set (this can be done in Navigator for IBM i under Security > Cryptographic Services Key Management > Manage Master Keys)
+- *SYSTEM store is populated with a valid certificate (this can be done in Digital Certificate Manager)
+
+1. On Navigator for IBM i, go to Network > Servers > TCP/IP Servers
+2. Scroll down to System Debugger and right click
+3. Hover over Stop Instance, select Debug Service
+![](image-4.png)
+4. Right click System Debugger again, select Regenerate Debug Service Trust Store 
+![](image-3.png)
+5. Enter in the password for the *SYSTEM store, click OK
+![](image-1.png)
+6. Select the certificate you want to use, click OK
+![](image-2.png)
+7. Right click System Debugger again, hover over Start Instance, select Debug Service
+![](image-5.png)
+
+**NOTE:** This needs to be done each time you renew or replace that certificate, it does not automatically update when you update the *SYSTEM store
 
 # Common issues
 

src/content/docs/developing/debug/image-2.png

@@ -56,6 +56,9 @@ csv: select * from sample.employee;
 -- result set as SQL insert statement
 sql: select * from sample.employee;
 
+-- RPG data structure based on result set columns
+rpg: select * from sample.employee;
+
 -- run CL commands. output is directed to IBM i output channel
 cl: dspffd sample/employee
 ```