Merge pull request #27 from ambitus/gh-pages-robust-error-updates

Gh pages robust error updates

access/advanced/alter.md → access/advanced/permit.md

@@ -4,15 +4,15 @@ grand_parent: Access Admin
 parent: Advanced
 ---
 
-# Alter
+# Permit
 
-Create a new permission.
+Create or change a permission
 {: .fs-6 .fw-300 }
 
-## `AccessAdmin.alter()`
+## `AccessAdmin.permit()`
 
 ```python
-def alter(
+def permit(
     self,
     resource: str,
     class_name: str,
@@ -32,17 +32,11 @@ def alter(
 
  
 
-{: .warning }
-> _Alter operations in pyracf require READ access to `IRR.IRRSMO00.PRECHECK` in the `XFACILIT` class_
-> _This function will not produce output unless the user running the command has this access._
-
- 
-
-Alter an existing **permission**.
+Create or change a **permission**.
 
 #### 📥 Parameters
 * `resource`<br>
-  The **resource profile** to alter this permission to.
+  The **general resource profile** to permit this permission to.
 * `class`<br>
   The **class** that the specified resource profile belongs to.
 * `auth_id`<br>
@@ -63,10 +57,12 @@ Alter an existing **permission**.
 #### ❌ Raises
 * `SecurityRequestError`<br>
   Raises `SecurityRequestError` when the **Return Code** of a **Security Result** returned by IRRSMO00 is **NOT** equal to `0`.
+* `SegmentTraitError`<br>
+  Raises `SegmentTraitError` when the dictionary of **traits/attributes** provided contains one or more **unknown** traits.
 
 #### 💻 Example
 
-The following example **alters** an existing **permission** for the **z/OS userid** `eswift` to the **resource profile** `testing` in the **class** `elijtest` with one **trait/attribute** as defined in the `traits` dictionary.
+The following example **permits** an existing **permission** for the **z/OS userid** `eswift` to the **general resource profile** `testing` in the **class** `elijtest` with one **trait/attribute** as defined in the `traits` dictionary.
 
 ###### Python Script
 ```python
@@ -77,7 +73,7 @@ traits = {
     "base:access": "NONE",
 }
 
-access_admin.alter("TESTING", "ELIJTEST", "ESWIFT", traits=traits)
+access_admin.permit("TESTING", "ELIJTEST", "ESWIFT", traits=traits)
 ```
 
 ###### Security Result Dictionary as JSON

access/advanced/segments_traits_operators.md

@@ -41,7 +41,7 @@ Information about permission `segments` dictionaries, `traits` dictionaries, and
 
  
 
-When using the **[`AccessAdmin.add()`](../add#accessadminadd)** and **[`AccessAdmin.alter()`](../alter#accessadminalter)** functions, the following are valid access traits. Feel free to experiment with any of the other traits defined in `pyracf/access/access_admin.py` in the pyRACF source code.
+When using the **[`AccessAdmin.permit()`](../permit#accessadminpermit)** function, the following are valid access traits. Feel free to experiment with any of the other traits defined in `pyracf/access/access_admin.py` in the pyRACF source code.
 
  
 

access/standard/delete.md

@@ -28,7 +28,7 @@ Delete a specified **permission**
 
 #### 📥 Parameters
 * `resource`<br>
-  The **resource profile** to delete this permission from.
+  The **general resource profile** to delete this permission from.
 * `class_name`<br>
   The **class** that the specified resource profile belongs to.
 * `auth_id`<br>

common/add_additional_secret_traits.md

@@ -10,6 +10,11 @@ Add additional secrets to be redacted in debug log output and any returned resul
 
  
 
+{: .experimental }
+> _This feature will successfully remove references to the additional secrets in the **RACF Command Image** in the **Result XML** and debug logging output, but additional messages may contain secret values from these traits, especially if bad data is provided._
+
+ 
+
 {: .note}
 > _Changes made using the functionality described here are scoped to the target "Admin" object instance._
 

common/add_operation_error.md

@@ -0,0 +1,38 @@
+---
+layout: default
+parent: Common
+---
+
+# Add Operation Error
+
+Understanding the `AddOperationError` exception.
+{: .fs-6 .fw-300 }
+
+ 
+
+{: .note }
+> _An **Add** operation targeting an existing profile could end up effectively performing an **Alter** operation on an existing profile. pyRACF will always raise an `AddOperationError` and **refuse** to perform the requested operation to bring attention to this condition._
+
+ 
+
+Prior to executing an **Add** operation, a **Profile Extract** is attempted to determine whether the profile already exists. If the **Return Code** and the **Messages** returned by the **Profile Extract** operation indicate that the profile already exists, an `AddOperationError` will be raised and the requested **Add** operation will **NOT** be executed. An `AddOperationError` can be handled as follows.
+
+###### Python Script
+```python
+from pyracf import UserAdmin
+from pyracf import AddOperationError
+
+user_admin = UserAdmin()
+
+try:
+    user_admin.add("squidwrd")
+except AddOperationError as e:
+    print(e.message)
+```
+
+###### Console Output
+```console
+Refusing to make security request to IRRSMO00.
+
+Target profile 'squidwrd' already exists as a 'user' profile.
+```

common/alter_operation_error.md

@@ -0,0 +1,38 @@
+---
+layout: default
+parent: Common
+---
+
+# Alter Operation Error
+
+Understanding the `AlterOperationError` exception.
+{: .fs-6 .fw-300 }
+
+ 
+
+{: .note}
+> _An **Alter** operation targeting a profile that does **NOT** exist already could end up effectively performing an **Add** operation to create a new profile. pyRACF will always raise an `AlterOperationError` and refuse to perform the requested operation to bring attention to this condition._
+
+ 
+
+Prior to executing an **Alter** operation, a **Profile Extract** is attempted to determine whether the profile already exists. If the **Return Code** and the **Messages** returned by the **Extract** operation indicate that the profile does **NOT** exist, an `AlterOperationError` will be raised and the requseted **Alter** operation will **NOT** be executed. An `AlterOperationError` can be handled as follows.
+
+###### Python Script
+```python
+from pyracf import UserAdmin
+from pyracf import AlterOperationError
+
+user_admin = UserAdmin()
+
+try:
+    user_admin.alter("squidwrd")
+except AlterOperationError as e:
+    print(e.message)
+```
+
+###### Console Output
+```console
+Refusing to make security request to IRRSMO00.
+
+Target profile 'squidwrd' does not exist as a 'user' profile.
+```

common/segment_error.md

@@ -0,0 +1,35 @@
+---
+layout: default
+parent: Common
+---
+
+# Segment Error
+
+Understanding the `SegmentError` exception.
+{: .fs-6 .fw-300 }
+
+ 
+
+When an unknown **Segment** is provided in the parameters to a **Profile Extract** request, a `SegmentError` will be raised to indicate that the request cannot be built. A `SegmentError` can be handled as follows.
+
+###### Python Script
+```python
+from pyracf import UserAdmin
+from pyracf import SegmentError
+
+user_admin = UserAdmin()
+
+try:
+    user_admin.extract("squidwrd", segments=["ovms","rso"])
+except SegmentError as e:
+    print(e.message)
+```
+
+###### Console Output
+```console
+Unable to build Security Request.
+
+'rso' is not a known segment for 'user'.
+'ovms' is not a known segment for 'user'.
+
+```

common/segment_trait_error.md

@@ -0,0 +1,47 @@
+---
+layout: default
+parent: Common
+---
+
+# Segment Trait Error
+
+Understanding the `SegmentTraitError` exception.
+{: .fs-6 .fw-300 }
+
+
+ 
+
+When any unknown **Segment-Trait Combination** is provided in the parameters to a **Non-Profile Extract** request, a `SegmentTraitError` will be raised to indicate that the request cannot be built. A `SegmentTraitError` can be handled as follows.
+
+###### Python Script
+```python
+from pyracf import UserAdmin
+from pyracf import SegmentError
+
+user_admin = UserAdmin()
+traits = {
+    "base:name": "Squidward",
+    "base:passwrd": "K29521IO",
+    "base:owner": "leonard",
+    "base:special": False,
+    "base:operations": True,
+    "omvs:uid": 2424,
+    "omvs:home": "/u/squidwrd",
+    "omvs:program": "/bin/sh",
+}
+
+try:
+    user_admin.alter("squidwrd", traits=traits)
+except SegmentTraitError as e:
+    print(e.message)
+```
+
+###### Console Output
+```console
+Unable to build Security Request.
+
+'base:passwrd' is not a known segment-trait combination for 'user'.
+'ovms:home' is not a known segment-trait combination for 'user'.
+'ovms:program' is not a known segment-trait combination for 'user'.
+
+```

data_set/advanced/add.md

@@ -13,7 +13,11 @@ Create a new data set profile.
 
 ```python
 def add(
-    self, data_set: str, traits: dict, volume: Union[str, None] = None, generic: bool = False
+    self,
+    data_set: str,
+    traits: dict = {},
+    volume: Union[str, None] = None,
+    generic: bool = False
 ) -> Union[dict, bytes]:
 ```
 
@@ -48,6 +52,10 @@ Create a new **data set profile**.
 #### ❌ Raises
 * `SecurityRequestError`<br>
   Raises `SecurityRequestError` when the **Return Code** of a **Security Result** returned by IRRSMO00 is **NOT** equal to `0`.
+ * `AddOperationError`<br>
+  Raises `AddOperationError` when the **data set profile** cannot be added because it already exists.
+* `SegmentTraitError`<br>
+  Raises `SegmentTraitError` when the dictionary of **traits/attributes** provided contains one or more **unknown** traits.
 
 #### 💻 Example
 

data_set/advanced/alter.md

@@ -55,6 +55,10 @@ Alter an existing **data set profile**.
 #### ❌ Raises
 * `SecurityRequestError`<br>
   Raises `SecurityRequestError` when the **Return Code** of a **Security Result** returned by IRRSMO00 is **NOT** equal to `0`.
+* `AlterOperationError`<br>
+  Raises `AlterOperationError` when the **data set profile** cannot be altered because it does **NOT** exist.
+* `SegmentTraitError`<br>
+  Raises `SegmentTraitError` when the dictionary of **traits/attributes** provided contains one or more **unknown** traits.
 
 #### 💻 Example