Custom Field

Resource Administration subfunctions for Custom Field Administration.

 

This may not be the only step to manage a Custom Field in your environment. You may also have to refresh the CFIELD class to enact these changes. Please consult RACF documentation and manuals for an understanding of the CFIELD class.

ResourceAdmin.add_custom_field() 

def add_custom_field(
    self, custom_field_name: str, custom_field_type: str, traits: dict = {}
) -> Union[dict, bytes]:

📄 Description

 

Only a subset of available Segments and Traits are considered Stable. See Segments and Traits for more details.

 

Define a new Custom Field profile in the CFIELD class.

📥 Parameters

  • custom_field_name
    The name of the Custom Field being defined.

  • custom_field_type
    The Type of the Custom Field being defined. Valid Types are user or group in RACF.

  • traits
    A dictionary of traits/attributes that should be given to the resource on creation. See Traits to see what all of the valid Resource Traits are.

📤 Returns

  • Union[dict, bytes]
    Returns a Security Result dictionary or Security Request XML bytes if the ResourceAdmin.generate_requests_only class attribute is set to True.

❌ Raises

  • SecurityRequestError
    Raises SecurityRequestError when the SAF Return Code of a Security Result is equal to 4.
  • DownstreamFatalError
    Raises DownstreamFatalError when the SAF Return Code of a Security Result is greater than 4.
  • AddOperationError
    Raises AddOperationError when the general resource profile cannot be added because it already exists.
  • SegmentTraitError
    Raises SegmentTraitError when the dictionary of traits/attributes provided contains one or more unknown traits.

💻 Example

Python REPL 
from pyracf import ResourceAdmin
resource_admin = ResourceAdmin()
resource_admin.add_custom_field("TVSHOW","user")
{'securityResult': {'resource': {'name': 'USER.CSDATA.TVSHOW', 'class': 'CFIELD', 'operation': 'set', 'requestId': 'ResourceRequest', 'commands': [{'safReturnCode': 0, 'returnCode': 0, 'reasonCode': 0, 'image': 'RDEFINE CFIELD             (USER.CSDATA.TVSHOW) '}]}, 'returnCode': 0, 'reasonCode': 0, 'runningUserid': 'testuser'}}
Security Result Dictionary as JSON 
{
  "securityResult":{
    "resource":{
      "name":"USER.CSDATA.TVSHOW",
      "class":"CFIELD",
      "operation":"set",
      "requestId":"ResourceRequest",
      "commands":[
        {
          "safReturnCode":0,
          "returnCode":0,
          "reasonCode":0,
          "image":"RDEFINE CFIELD             (USER.CSDATA.TVSHOW) "
        }
      ]
    },
    "returnCode":0,
    "reasonCode":0
  }
}

ResourceAdmin.alter_custom_field() 

def alter_custom_field(
    self, custom_field_name: str, custom_field_type: str, traits: dict = {}
) -> Union[dict, bytes]:

📄 Description

 

Only a subset of available Segments and Traits are considered Stable. See Segments and Traits for more details.

 

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 Custom Field profile in the CFIELD class.

📥 Parameters

  • custom_field_name
    The name of the Custom Field being altered.

  • custom_field_type
    The Type of the Custom Field being altered. Valid Types are user or group in RACF.

  • traits
    A dictionary of traits/attributes that should be given to the resource. See Traits to see what all of the valid Resource Traits are.

📤 Returns

  • Union[dict, bytes]
    Returns a Security Result dictionary or Security Request XML bytes if the ResourceAdmin.generate_requests_only class attribute is set to True.

❌ Raises

  • SecurityRequestError
    Raises SecurityRequestError when the SAF Return Code of a Security Result is equal to 4.
  • DownstreamFatalError
    Raises DownstreamFatalError when the SAF Return Code of a Security Result is greater than 4.
  • AlterOperationError
    Raises AlterOperationError when the z/OS userid supplied cannot be altered because it does NOT exist.
  • SegmentTraitError
    Raises SegmentTraitError when the dictionary of traits/attributes provided contains one or more unknown traits.

💻 Example

Python REPL 
from pyracf import ResourceAdmin
resource_admin = ResourceAdmin()
cf_traits = {
  "cfdef:help_text":"Favorite TV Show",
  "cfdef:valid_first_characters":"ALPHA",
  "cfdef:valid_other_characters":"ALPHA"
}
resource_admin.alter_custom_field("TVSHOW","user",traits=cf_traits)
{'securityResult': {'resource': {'name': 'USER.CSDATA.TVSHOW', 'class': 'CFIELD', 'operation': 'set', 'requestId': 'ResourceRequest', 'info': ['Definition exists. Add command skipped due  to precheck option'], 'commands': [{'safReturnCode': 0, 'returnCode': 0, 'reasonCode': 0, 'image': "RALTER  CFIELD             (USER.CSDATA.TVSHOW)  CFDEF    (HELP        ('Favorite TV Show') FIRST       (ALPHA) OTHER       (ALPHA))", 'messages': ['IRR52216I An error was detected in the definition of custom field USER.CSDATA.TVSHOW. MAXLENGTH is missing or incorrect for a field with TYPE(CHAR).']}]}, 'returnCode': 0, 'reasonCode': 0, 'runningUserid': 'testuser'}}
Security Result Dictionary as JSON 
{
  "securityResult":{
    "resource":{
      "name":"USER.CSDATA.TVSHOW",
      "class":"CFIELD",
      "operation":"set",
      "requestId":"ResourceRequest",
      "info":[
        "Definition exists. Add command skipped due  to precheck option"
      ],
      "commands":[
        {
          "safReturnCode":0,
          "returnCode":0,
          "reasonCode":0,
          "image":"RALTER  CFIELD             (USER.CSDATA.TVSHOW)  CFDEF    (HELP        ('Favorite TV Show') FIRST       (ALPHA) OTHER       (ALPHA))",
          "messages":[
            "IRR52216I An error was detected in the definition of custom field USER.CSDATA.TVSHOW. MAXLENGTH is missing or incorrect for a field with TYPE(CHAR)."
          ]
        }
      ]
    },
    "returnCode":0,
    "reasonCode":0
  }
}

ResourceAdmin.extract_custom_field() 

def extract_custom_field(
    self, custom_field_name: str, custom_field_type: str
) -> Union[dict, bytes]:

📄 Description

Extract an existing Custom Field profile in the CFIELD class.

📥 Parameters

  • custom_field_name
    The name of the Custom Field being extracted.

  • custom_field_type
    The Type of the Custom Field being extracted. Valid Types are user or group in RACF.

📤 Returns

  • Union[dict, bytes]
    Returns a Trait dictionary of the values of the traits extracted from the CFDEF segment of the Resource Profile or Security Request XML bytes if the ResourceAdmin.generate_requests_only class attribute is set to True.

❌ Raises

  • SecurityRequestError
    Raises SecurityRequestError when the SAF Return Code of a Security Result is equal to 4.
  • DownstreamFatalError
    Raises DownstreamFatalError when the SAF Return Code of a Security Result is greater than 4.

💻 Example

Python REPL 
from pyracf import ResourceAdmin
resource_admin = ResourceAdmin()
resource_admin.extract_custom_field("SHELCITY")
{"customFieldDataType": "char", "maxlength": None, "maxNumericValue": None, "minNumericValue": None, "validFirstCharacters": "alpha", "validOtherCharacters": "alpha", "mixedCaseAllowed": None, "helpText": ["favorite", "tv", "show"]}
Trait Dictionary as JSON 
{
  "customFieldDataType": "char",
  "maxlength": null,
  "maxNumericValue": null,
  "minNumericValue": null,
  "validFirstCharacters": "alpha",
  "validOtherCharacters": "alpha",
  "mixedCaseAllowed": null,
  "helpText": ["favorite", "tv", "show"]
}

ResourceAdmin.delete_custom_field() 

def delete_custom_field(
    self, custom_field_name: str, custom_field_type: str
) -> Union[dict, bytes]:

📄 Description

Delete an existing Custom Field profile in the CFIELD class.

📥 Parameters

  • custom_field_name
    The name of the Custom Field being deleted.

  • custom_field_type
    The Type of the Custom Field being deleted. Valid Types are user or group in RACF.

📤 Returns

  • Union[dict, bytes]
    Returns a Security Result dictionary or Security Request XML bytes if the ResourceAdmin.generate_requests_only class attribute is set to True.

❌ Raises

  • SecurityRequestError
    Raises SecurityRequestError when the SAF Return Code of a Security Result is equal to 4.
  • DownstreamFatalError
    Raises DownstreamFatalError when the SAF Return Code of a Security Result is greater than 4.

💻 Example

Python REPL 
from pyracf import ResourceAdmin
resource_admin = ResourceAdmin()
resource_admin.delete_custom_field("TVSHOW","user")
{'securityResult': {'resource': {'name': 'USER.CSDATA.TVSHOW', 'class': 'CFIELD', 'operation': 'del', 'requestId': 'ResourceRequest', 'commands': [{'safReturnCode': 0, 'returnCode': 0, 'reasonCode': 0, 'image': 'RDELETE CFIELD             (USER.CSDATA.TVSHOW) '}]}, 'returnCode': 0, 'reasonCode': 0, 'runningUserid': 'testuser'}}
Security Result Dictionary as JSON 
{
  "securityResult":{
    "resource":{
      "name":"USER.CSDATA.TVSHOW",
      "class":"CFIELD",
      "operation":"del",
      "requestId":"ResourceRequest",
      "commands":[
        {
          "safReturnCode":0,
          "returnCode":0,
          "reasonCode":0,
          "image":"RDELETE CFIELD             (USER.CSDATA.TVSHOW) "
        }
      ]
    },
    "returnCode":0,
    "reasonCode":0
  }
}