Merge pull request #233 from markcocker/dev

cxharris · web-flow · commit 024c31de6fc4 · 2019-06-06T11:35:02.000+01:00
Add CICS profile to doc
diff --git a/docs/pages/cdp/cdp-Creating-Zowe-CLI-profiles.md b/docs/pages/cdp/cdp-Creating-Zowe-CLI-profiles.md
@@ -8,9 +8,9 @@ permalink: cdp-Creating-Zowe-CLI-profiles.html
 folder: cdp
 ---
 
-### Step 1: Create a z/OSMF profile
+### Create a z/OSMF profile
 
-This profile defines the parameters needed to connect to the z/OSMF server on z/OS. You need to know the following from your z/OS system administrator:
+The z/OSMF profile defines the parameters needed to connect to the z/OSMF server on z/OS. You need to know the following from your z/OS system administrator:
 
 | Option | Description |
 | --- | --- |
@@ -39,9 +39,9 @@ To test the connection to the z/OSMF server using the profile:
 zowe zosmf check status
 ```
 
-### Step 2: Create an SSH profile
+### Create an SSH profile
 
-This profile defines the parameters needed to connect to the SSH server on z/OS. You need to know the following from your z/OS system administrator:
+The SSH profile defines the parameters needed to connect to the SSH server on z/OS. You need to know the following from your z/OS system administrator:
 
 | Option | Description |
 | --- | --- |
@@ -70,9 +70,9 @@ To test the connection to the SSH server using the profile:
 zowe zos-uss issue ssh 'uname -a'
 ```
 
-### Step 3: Create a cics-deploy profile
+### Create a cics-deploy profile
 
-This profile identifies the CICS environment for deployment. You need to know the following from your CICS system administrator:
+The cics-deploy profile identifies the CICS environment for deployment. An example of how to create an environment using using z/OS Provisioning Toolkit as described in [Provisioning a CICS region using z/OS PT](cdp-Provisioning-a-CICS-region-using-zospt). You need to know the following from your CICS system administrator:
 
 | Option | Description |
 | --- | --- |
@@ -96,4 +96,35 @@ For help on using the options:
 zowe profiles create cics-deploy-profile --help
 ```
 
-To test the cics-deploy profile, follow the steps in [Deploying your first Node.js app](cdp-Deploying-your-first-nodejs-app).
+To test the cics-deploy profile, follow the steps in [Deploying your first Node.js app](cdp-Deploying-your-first-nodejs-app).
+
+### Create a CICS profile
+
+The CICS profile identifies the connection to the CICS Web User Interface (WUI) server to query application resources. You need to know the following from your CICS system administrator:
+
+| Option | Description |
+| --- | --- |
+| cics-plex | CPSM CICSplex name. This will typically be set to the same as cicsplex in the cics-deploy profile. |
+| protocol | HTTP or HTTPS to use to connect to the CICS WUI server. |
+| host | Host name of the CICS WUI server. |
+| port | Port number of the CICS WUI server. |
+| user | User ID to identify yourself to the CICS WUI server . |
+| password | Password to identify yourself to the CICS WUI server. |
+
+For example, to create an SSH profile:
+
+```console
+zowe profiles create cics-profile cics --cics-plex PLEX1 --protocol https --host myzos.example.com --port 1490 --user myuserid --password mypassword --overwrite
+```
+
+For help on using the options:
+
+```console
+zowe profiles create cics-profile --help
+```
+
+To test the connection to the CICS WUI server using the profile:
+
+```console
+zowe cics get resource CICSRegion
+```
diff --git a/docs/pages/cdp/cdp-Deploying-your-first-nodejs-app.md b/docs/pages/cdp/cdp-Deploying-your-first-nodejs-app.md
@@ -17,7 +17,7 @@ CICS TS V5.5 introduced support to run Node.js applications and is required by t
 
 1. Install the Zowe CLI and cics-deploy plugin by following the steps in [Installing](cdp-Installing).
 
-2. Create Zowe CLI profiles for z/OSMF, SSH, and cics-deploy by following the steps in [Creating Zowe CLI profiles](cdp-Creating-Zowe-CLI-profiles).
+2. Create Zowe CLI profiles for z/OSMF, SSH, cics-deploy and CICS by following the steps in [Creating Zowe CLI profiles](cdp-Creating-Zowe-CLI-profiles).
 
 3. Create a Node.js application using the [Express Application Generator](https://expressjs.com/en/starter/generator.html):
 
diff --git a/docs/pages/cdp/cdp-Provisioning-a-CICS-region-using-zospt.md b/docs/pages/cdp/cdp-Provisioning-a-CICS-region-using-zospt.md
@@ -9,21 +9,23 @@ folder: cdp
 toc: true
 ---
 
-The [z/OS Provisioning Toolkit](https://developer.ibm.com/mainframe/products/zospt/) (z/OS PT) provides a command line utility and z/OSMF workflows to provision CICS regions and other development environments on z/OS. This tutorial requires z/OS PT version 1.1.5 or above to be installed.
+The [z/OS Provisioning Toolkit](https://developer.ibm.com/mainframe/products/zospt/) (z/OS PT) provides a command line utility and z/OSMF workflows to provision CICS regions and other development environments on z/OS. This tutorial requires z/OS PT version 1.1.5 or above to be installed on z/OS.
 
 ### Prepare a z/OS PT image
 
-A z/OS PT image contains the configuration and files necessary to provision a CICS region. This is typically prepared by the CICS system administrator. The CICS image should include the following properties. Other properties are available to customise the CICS region to your requirements - see [Configuration properties for CICS images](https://www.ibm.com/support/knowledgecenter/en/SSXH44E_1.0.0/zospt/cics/zospt-cics-properties.html).
+A z/OS PT image contains the configuration and files necessary to provision a CICS region. This is typically prepared by the CICS system administrator. The main configuration is in the file `zosptfile` in the form of properties that are described in [Configuration properties for CICS images](https://www.ibm.com/support/knowledgecenter/en/SSXH44E_1.0.0/zospt/cics/zospt-cics-properties.html).
+
+For example, to support Node.js applications `zosptfile` should include:
 
 | zosptfile&nbsp;entry&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Usage |
 | --- | -- |
-| `FROM cics_55` | Provision a CICS TS V5.5 region. Required to support Node.js applications. |
-| `ENV DFH_CICS_TYPE=MAS` | The CICS region should be managed by CPSM. |
-| `ENV DFH_CICSPLEX=` | The name of the CICSplex. |
-| `ENV DFH_NODE_HOME=` | The installation directory for IBM SDK for Node.js - z/OS. Required to support Node.js applications. |
-| `COPY bundles bundles` | Create an empty bundles directory in the provisioned file system to contain CICS bundles. |
+| `FROM cics_55` | Provision a CICS TS V5.5 region that is the minimum release that supports Node.js applications. |
+| `ENV DFH_CICS_TYPE=MAS` | CICS region should be managed by CPSM to enable the DFHDPLOY utility to deploy applications. |
+| `ENV DFH_CICSPLEX=` | Name of the CICSplex this region is to join. |
+| `ENV DFH_NODE_HOME=` | Installation directory for Node.js runtime provided by IBM SDK for Node.js - z/OS. |
+| `COPY bundles bundles` | Create an empty `bundles` directory in the provisioned file system to contain CICS bundles. |
 
-For example, to create the z/OS PT image source directory and configuration file, and build it ready for developers to provision CICS regions:
+To create a z/OS PT image source directory, a `zosptfile` file, and build it ready for developers to provision CICS regions, run the following commands on z/OS:
 
 ```console
 export ZOSPTIMAGE=~/zosptimages/cics_55_nodejs
@@ -43,16 +45,26 @@ chtag -tc UTF-8 $ZOSPTIMAGE/zosptfile
 zospt build $ZOSPTIMAGE -t cics_55_nodejs
 ```
 
-### Provision your CICS region and deploy a Node.js application
+### Provision your CICS region using a z/OS image
 
 1. Update your user `.profile` file on z/OS to run z/OS PT.
 
-   Add the directory to the `zospt` command to your PATH, and add the following environment variables as described in [Configuring z/OS Provisioning Toolkit](https://www.ibm.com/support/knowledgecenter/en/SSXH44E_1.0.0/zospt/zospt-configuring.html):
+   Add the directory to the `zospt` command to your PATH.
+   ```properties
+   export PATH=$PATH:zospt_directory/bin
+   ```
+
+   Optional: To avoid the password prompt for each zospt command, specify your password as the environment variable. Ensure others do not have access to read your .profile:
+
+   ```properties
+   export zospt_pw=
+   ```
+
+   Optional: If z/OSMF is configured with domain and tenant names that are not the default as described in [Configuring z/OS Provisioning Toolkit](https://www.ibm.com/support/knowledgecenter/en/SSXH44E_1.0.0/zospt/zospt-configuring.html), add the following environment variables:
 
    ```properties
    export zospt_domain=
    export zospt_tenant=
-   export zospt_pw=
    ```
 
 2. Provision your CICS region.
@@ -63,7 +75,7 @@ zospt build $ZOSPTIMAGE -t cics_55_nodejs
    zowe zos-uss issue ssh "zospt run cics_55_nodejs --name my_cics_region"
    ```
 
-3. Display the CICS region information.
+3. Display your CICS region information.
 
    ```console
    zowe zos-uss issue ssh "zospt inspect my_cics_region"
@@ -75,37 +87,50 @@ zospt build $ZOSPTIMAGE -t cics_55_nodejs
     "DFH_REGION_APPLID": "CICPY000",
     "DFH_REGION_ZFS_DIRECTORY": "/u/cicprov/mnt/CICPY000",</pre>
 
-4. Update your Zowe CLI cics-deploy profile options.
+    Your applications can make use of the directories and files under the DFH_REGION_ZFS_DIRECTORY path:
+
+   | DFH_REGION_ZFS_DIRECTORY<br>sub-directory | Usage |
+   | --- | -- |
+   | /JVMProfiles | JVM server profiles |
+   | /bundles | CICS bundles |
+   | /dfhconfig | CICS configuration files |
+   | /dfhconfig/nodejsprofiles/general.profile | General profile containing values for WORK_DIR and NODE_HOME. Node.js application should include this by adding `%INCLUDE=&USSCONFIG;/nodejsprofiles/general.profile` to their CICS Node.js application profile |
+   | /workdir | Trace, log and configuration files create by applications, Node.js runtimes, Java runtimes, and CICS runtimes |
+
 
-   Update `--scope` to be the value from DFH_REGION_APPLID, and `--bundle-directory` to be a bundles subdirectory of DFH_REGION_ZFS_DIRECTORY. For example:
+4. Update your Zowe CLI cics-deploy profile options to deploy to your CICS region by default.
+
+   Update `--scope` to be the value from DFH_REGION_APPLID, and `--bundle-directory` to be the `bundles` subdirectory of DFH_REGION_ZFS_DIRECTORY. For example:
 
    ```console
-   zowe profiles update cics-deploy cics --scope CICPY000 --bundle-directory /u/cicprov/mnt/CICPY000/bundles
+   zowe profiles update cics-deploy cics --scope CICPY000 --bundle-directory "/u/cicprov/mnt/CICPY000/bundles"
    ```
 
-You are now ready to deploy applications to the provisioned CICS region. You can try this out by following the steps in [Deploying your first Node.js app](cdp-Deploying-your-first-nodejs-app).
+### Deploying an application to your CICS region
+
+You are now ready to deploy applications to the provisioned CICS region. You can try this out by following the steps in [Deploying your first Node.js app](cdp-Deploying-your-first-nodejs-app). During deployment, the CICS bundle will be copied into the `/bundles` directory, and output files will be written into a sub-directory of `/workdir`.
 
 ### Stop your CICS region
 
-The CICS region and the applications running in it can be stopped if you are not going to be using them for a while by using command:
+The CICS region and the applications running in it can be stopped if you are not going to be using them for a while by using the following command:
 
 ```console
 zowe zos-uss issue ssh "zospt stop my_cics_region"
 ```
 
 ### Start your CICS region
 
-The CICS region can be started after it was previously stopped, or the z/OS system was restarted, by using command:
+The CICS region can be started after it was previously stopped, or the z/OS system was restarted, by using the following command:
 
 ```console
 zowe zos-uss issue ssh "zospt start my_cics_region"
 ```
 
 ### Deprovision your CICS region
 
-The CICS region can be stopped and removed using the following commands. This will remove the z/OS directory used to upload your CICS bundles:
+The CICS region can be stopped and removed completely using the following commands. This will remove the z/OS directory used to upload your CICS applications:
 
 ```console
 zowe zos-uss issue ssh "zospt stop my_cics_region"
 zowe zos-uss issue ssh "zospt rm my_cics_region"
-```
+```
diff --git a/docs/pages/cdp/cdp-Requirements.md b/docs/pages/cdp/cdp-Requirements.md
@@ -23,4 +23,6 @@ The [z/OS Secure SHell daemon (sshd)](https://www.ibm.com/support/knowledgecente
 
 The [DFHDPLOY](https://www.ibm.com/support/knowledgecenter/SSGMCP_5.5.0/applications/deploying/dfhdploy_overview.html) utility is provided with IBM CICS Transaction Server (CICS) and is required to run the [`zowe cics-deploy push bundle`](cdp-CLIReadMe#push--p), [`zowe cics-deploy deploy bundle`](cdp-CLIReadMe#deploy--d--dep), and [`zowe cics-deploy undeploy bundle`](cdp-CLIReadMe#undeploy--u--udep) commands. These commands start DFHDPLOY with a script to perform deploy and undeploy operations.
 
-CICSPlex System Manager \(CPSM\) is provided with CICS and is required to run the DFHDPLOY utility. CPSM should be connected to the CICS regions into which the application is being installed.
+### CICSPlex System Manager
+
+CICSPlex System Manager \(CPSM\) is provided with CICS and is required to run the DFHDPLOY utility, and for the [`zowe cics-deploy push bundle`](cdp-CLIReadMe#push--p) to query application resources. CPSM should be connected to the CICS regions into which the application is being installed.
