Skip to content

Commit f45c968

Browse files
kiera-bennettledina
kiera-bennett
authored and
ledina
committed
Change Readme to new certified collection format
1 parent 2f2296c commit f45c968

File tree

1 file changed

+160
-0
lines changed

1 file changed

+160
-0
lines changed

‎README.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,166 @@ and ansible-doc to:
4444
- Provision or deprovision CICS regions.
4545
- Start or stop a CICS region.
4646

47+
## Requirements
48+
49+
The tasks in the IBM® z/OS® CICS® collection can be classified into two types, CMCI tasks and provisioning tasks, that have different requirements of the managed node.
50+
51+
The CMCI tasks in the IBM® z/OS® CICS® collection interact with the managed node over an HTTP connection by leveraging the CMCI REST API. Therefore, an SSH connection is not required. Instead, you can delegate Ansible tasks to run on the control node, for example, by specifying delegate_to: 'localhost' for the task in the playbook. In this case, you install dependencies on your localhost instead of the managed node.
52+
53+
The requirements of the managed node for **CMCI tasks** are as follows:
54+
55+
* z/OS Version 2.3 or later
56+
57+
* All IBM CICS TS releases that are in service
58+
59+
* A CMCI connection must be set up in either a CICSplex or a stand-alone CICS region
60+
61+
* Python module dependencies:
62+
63+
* requests
64+
65+
* xmltodict
66+
67+
68+
The **provisioning tasks** in the IBM® z/OS® CICS® collection interact with a z/OS managed node over SSH, and therefore have different requirements to the CMCI tasks.
69+
The requirements include installation of the following components
70+
71+
* z/OS Version 2.3 or later
72+
73+
* z/OS OpenSSH
74+
75+
* IBM Open Enterprise SDK for Python (previously IBM Open Enterprise Python for z/OS)
76+
77+
* IBM Z Open Automation Utilities (ZOAU) 1.2.x
78+
79+
* The z/OS shell
80+
81+
Note that you must have z/OS core collection 1.5.0 to 1.9.2 installed in the control node if you want to run the provisioning tasks.
82+
83+
For more details on the different requirements, please see [here](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_cics/docs/source/requirements_managed.html).
84+
85+
86+
87+
## Installation
88+
89+
You can install this collection with the Ansible Galaxy command-line tool:
90+
```sh
91+
ansible-galaxy collection install ibm.ibm_zos_cics
92+
```
93+
94+
95+
You can also include it in a requirements.yml file and install it with ansible-galaxy collection install -r requirements.yml, using the format:
96+
```sh
97+
collections:
98+
- name: ibm.ibm_zos_cics
99+
```
100+
101+
102+
To install a specific version of the collection or upgrade an an existing installation to a specific version, for example installing 2.1.0, use the following syntax:
103+
```sh
104+
ansible-galaxy collection install ibm.ibm_zos_cics:2.1.0
105+
```
106+
107+
108+
If you want to upgrade the collection to the latest version, you can run:
109+
```sh
110+
ansible-galaxy collection install ibm.ibm_zos_cics --upgrade
111+
```
112+
113+
As part of the installation, the collection requirements must be made available to Ansible through the use of environment variables. The preferred configuration is to place the environment variables in group_vars and host_vars. An example of the variables file can be seen here:
114+
115+
116+
```sh
117+
pyz: "path_to_python_installation_on_zos_target"
118+
zoau: "path_to_zoau_installation_on_zos_target"
119+
120+
environment_vars:
121+
_BPXK_AUTOCVT: "ON"
122+
ZOAU_HOME: "{{ zoau }}"
123+
PYTHONPATH: "{{ zoau }}/lib"
124+
LIBPATH: "{{ zoau }}/lib:{{ pyz }}/lib:/lib:/usr/lib:."
125+
PATH: "{{ zoau }}/bin:{{ pyz }}/bin:/bin:/var/bin"
126+
_CEE_RUNOPTS: "FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)"
127+
_TAG_REDIR_ERR: "txt"
128+
_TAG_REDIR_IN: "txt"
129+
_TAG_REDIR_OUT: "txt"
130+
LANG: "C"
131+
```
132+
133+
## Use Cases
134+
135+
* Use Case Name: Provision a standalone CICS region
136+
* Actors:
137+
* System Programmer
138+
* Description:
139+
* A system programmer can provision a set of region data sets and start up a standalone CICS region.
140+
* Flow:
141+
* Create and activate a VTAM node to ensure user had a valid applid
142+
* Create region data sets
143+
* Update the CSD data set with a CSDUP script
144+
* Create CICS startup JCL data set
145+
* Submit the CICS startup JCL data set as a job using zoau's jsub.
146+
* Use Case Name: Deprovision a standalone CICS region
147+
* Actors:
148+
* System Programmer
149+
* Description:
150+
* A system programmer can stop a standalone cics region and delete the region data sets.
151+
* Flow:
152+
* Stop the CICS region
153+
* Check the CICS region has been shut down
154+
* If it has not stopped, shut the region down with state "immediate" or cancel the job.
155+
* Delete the region data sets
156+
* Delete the CICS startup JCL data set
157+
* Use Case Name: Provision an SMSS CICS region
158+
* Actors:
159+
* System Programmer
160+
* Description:
161+
* A system programmer can start a SMSS CICS region.
162+
* Flow:
163+
* Create and activate a VTAM node to ensure user had a valid applid
164+
* Ensure user has an allocated/free port available
165+
* Create region data sets
166+
* Update the CSD data with a CSDUP script which also alters the TCPIP service
167+
* Create CICS startup JCL data set
168+
* Submit the CICS startup JCL data set as a job using zoau's jsub task
169+
* Use Case Name: Install a bundle in a CICS region
170+
* Actors:
171+
* Application Developer
172+
* Description:
173+
* An application developer can install a CICS bundle into a CICS region
174+
* Flow:
175+
* Find if the CICS bundle already exists in target region
176+
* Disable and discard existing CICS bundle
177+
* Install bundle definition into target region
178+
* Wait for bundle to reach enabled status
179+
* Use Case Name: Deploy a program to a CICS region
180+
* Actors:
181+
* Application Developer
182+
* Description:
183+
* An application developer can deploy a program to a CICS region
184+
* Flow:
185+
* Copy load module to load library
186+
* Use NEWCOPY PROGRAM to deploy program into CICS
187+
188+
## Release Notes and Roadmap
189+
190+
The collection's cumulative release notes can be reviewed [here](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_cics/docs/source/release_notes.html).
191+
192+
<br/>The collection's changelogs can be reviewed in the following table.
193+
194+
| Version | Status | Release notes | Changelogs |
195+
|----------|----------------|---------------|------------|
196+
| 2.1.1 | In development | unreleased | unreleased |
197+
| 2.1.0 | Released | [Release notes](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_cics/docs/source/release_notes.html#version-2-1-0) | [Changelogs](https://github.com/ansible-collections/ibm_zos_cics/blob/v2.1.0/CHANGELOG.rst) |
198+
| 2.0.x | Released | [Release notes](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_cics/docs/source/release_notes.html#version-2-0-0) | [Changelogs](https://github.com/ansible-collections/ibm_zos_cics/blob/v2.0.0/CHANGELOG.rst) |
199+
| 1.0.x | Released | [Release notes](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_cics/docs/source/release_notes.html#version-1-0-6) | [Changelogs](https://github.com/ansible-collections/ibm_zos_cics/blob/v1.0.6/CHANGELOG.rst) |
200+
201+
202+
## Related Information
203+
204+
Example playbooks and use cases can be be found in the [z/OS playbook repository](https://github.com/IBM/z_ansible_collections_samples).
205+
Supplemental content on getting started with Ansible, architecture and use cases is available [here](https://ibm.github.io/z_ansible_collections_doc/reference/helpful_links.html).
206+
47207
## Contributing
48208

49209
We welcome contributions! Find out how in our [contribution guide](https://github.com/ansible-collections/ibm_zos_cics/blob/main/CONTRIBUTING.md).

0 commit comments

Comments
 (0)