Python API datasets module

Description

• This class represents the z/OS dataset.

• Bases: object

• Defined in: zoautil_py.datasets

Parameters

• name (str) - Name of the dataset.

• organization (str) - Dataset organization of the dataset. None if unknown.

• record_format (str) - Record format of the dataset. None if unknown.

• volume (str) - Volume the dataset resides on. None if unknown.

• block_size (int) - Block size of the dataset. None if unknown.

• record_length (int) - Record length of the dataset. None if unknown.

• total_space (int) - Estimated total space of the dataset. None if unknown.

• used_space (int) - Estimated used space of the dataset. None if unknown.

• last_referenced (datetime) - Date when the dataset was last referenced. None if unknown.

Other methods

Description

• ZOAU dmod function to be used by zos_blockinfile Ansible module.

Returns

• ZOAUResponse - Response object from dsed call.

Return type

• str

Parameters

• dataset (str) – The target dataset or z/OS UNIX file to modify to (example: “IBMUSER.TEST.MOD”).

• state (boolean) – True (default): Insert or replace block. False: Remove block.

Other Parameters

• block (str) – The line(s) to insert inside the marker lines separated by ‘\\n’. (Example: “line 1\\nline 2\\nline 3”)

• marker (str) – The marker line template in this format <marker_begin>\\n<marker_end>\\n< {mark} marker>

  • The template should be three sections separated by ‘\\n’. (Example: “OPEN\\nCLOSE\\n# {mark} IBM BLOCK”).

  • “{mark}” should be included in the < {mark} marker> (default = ”# {mark} MANAGED BLOCK”) section and will be replaced with <marker_begin> (default = ”BEGIN”) and <marker_end> (default = ”END”).

  • The two marker lines will be surrounding the lines that are going to be inserted.

  • Marker lines can only be used once. If marker lines already exist in the target dataset or HFS file, they will be removed with the surrounded lines before new block get inserted.

• insert_after (str) – Insert block after matching regex pattern. The special value “EOF” inserts the block at the end of the target dataset or HFS file.

• insert_before (str) – Insert block before matching regex pattern. The special value “BOF” inserts the block at the beginning of the target dataset or HFS file.

• encoding (str) – Encoding of the dataset.

• lock (bool) – Obtain exclusive lock for the dataset.

• force (bool) – Force open. Open dataset member in DISP=SHR mode. Default is DISP=OLD mode when False.

• as_json (bool) – Display output in JSON format.

Notes

• Use debug=True parameter for debug information in JSON format.
• blockinfile() supports operations on generation datasets (GDS). GDS relative name notation is supported, but the GDG base is not protected during execution. Use a batch job if you need to serialize the group.

Description

• Compare two datasets, output the ISRSUPC output.

Returns

• str (ISRSUPC output) – The output from ISRSUPC.

• None – Datasets are the same.

Parameters

• source (str) – First dataset to compare.

• target (str) – Second dataset to compare.

Other Parameters

• columns (str, int) - Specify column comparison specifiers to pass to SUPERCE.

• ignore_case (boolean) - Ignore case in comparison.

• lines (str, int) - Display n lines of context around a displayed line.

• tmphlq : (str) - Use an alternative high-level qualifier (HLQ) for the temporary dataset name.

Notes

The function arguments support generation dataset relative name notation.

Description

• Copy a z/OS source (dataset, HFS file) to a z/OS target.

Returns

• RC from z/OS.

Return type

• int

Raises

• ZOAUException – See exception text for ZOAU error.

Parameters

• source (str) – Absolute path of z/OS dataset or zFS file to copy from.

• target (str) – Absolute path of z/OS dataset or zFS file to copy to.

• alias (bool) - If the source data set has aliases, they will be recreated in the target data set.

• executable (bool) - This should be set if the source data set is an executable.

• force (bool) – Forces the copy. IMPORTANT: Use of this option can lead to permanent loss of the original target information.

  • NOTE: If a dataset member has aliases and is not a program object, copying that member to a dataset that is in use results in the aliases not being preserved in the target dataset. When this scenario occurs, an exception is raised, along with an error message and a non-zero return code.

Notes

• Generation data sets (GDS) are supported with the following considerations:

  • The generation data group (GDG) is not locked when referencing a GDS.

  • Relative names have their scope in the function call. This means that two consecutive copy calls that target a new generation, i.e. "GDG(+1)", result in the creation of two consecutive new generations.

• Generation data groups (GDG) are supported as source, and can be copied to a new GDG as target. The source GDG attributes and all its active generations are copied to the target. The source GDG base will not be locked, so prefer a job to ensure the GDG order is protected from concurrent operations.

Description

• Create a z/OS dataset.

Returns

• Dataset object.

Return type

• types.Dataset object

Raises

• ZOAUException – See exception text for ZOAU error.

• DatasetVerificationError – Failed to verify the creation of the dataset after ZOAU call.

Parameters

• name (str) – Name of the dataset.

• dataset_type (str) – Type of dataset (also known as dsorg).

  • Options: KSDS, ESDS, RRDS, LDS, SEQ, LARGE, PDS, PDSE.

Other Parameters

• primary_space (str) – Space to allocate for the dataset.

  • Defaults to 5M.

  • Examples: 1M, 2MB, 1G, 2GB.

• secondary_space (str) – Secondary (extent) space to allocate for the dataset. Defaults to 1/10 of primary space.

  • Examples: 1M, 2MB, 1G, 2GB.

• block_size (int) – Block size of dataset.

  • Default varies on record format: FBA=32718, FB=32720, VBA=32743, VB/U=32760.

• record_format (str) – Record format of dataset.

  • Options: FB (default), F, FBA, FBS, U, VB, VBA, VBS.

• storage_class_name (str) – The storage class for an SMS-managed dataset.

  • Required for SMS-managed datasets that do not match an SMS-rule.

  • Not valid for datasets that are not SMS-managed.

  • Note that all non-linear VSAM datasets are SMS-managed.

• data_class_name (str) – Data class name for dataset.

• management_class_name (str) – The management class for an SMS-managed dataset.

  • Optional for SMS-managed datasets that do not match an SMS-rule.

  • Not valid for datasets that are not SMS-managed.

  • Note that all non-linear VSAM datasets are SMS-managed.

• record_length (int) – Logical record length, expressed in bytes.

  • Defaults vary on format. F/FB/FBS=80, FBA=133, VB/VBA/VBS=137, U=0.

  • For variable datasets, the length must include the 4-byte prefix area.

• key_length (int) – Mutally inclusive with key_offset. Required for KSDS datasets.

• key_offset (int) – Mutally inclusive with key_length. Required for KSDS datasets.

• volumes (str) – Comma separated list of volume serials. Offline volumes are not considered.

• directory_blocks (int) – Directory blocks for PDS-type datasets. Default is 5.

• device_unit (str) - Unit name of the device that the dataset will reside on.

  • To target a specific device number, you must precede the address with a slash (/) character.

Description

• Delete a z/OS non-VSAM dataset, VSAM cluster, generation data set, or an empty generation data group.

Returns

• Return code from z/OS.

Return type

• int

Parameters

• dataset (str) – Dataset to delete.

Description

• Delete members contained in a dataset.

Returns

• Return code from z/OS action.

Return type

• int

Parameters

• pattern (str) – Dataset pattern to match.

Other Parameters

• force (bool) – Force the deletion of a member that is in use.

Description

• Unzips a dzip archive and restores the datasets to either the original or a new location.

Returns

• Return code from z/OS.

Return type

• int

Parameters

• file (str) – zFS path or dataset name of the dzip archive.

• high_level_qualifier (str) – Single segment HLQ that is used to unpack the archive. Default is None, which unpacks to the user's HLQ. You can use either keep_original_hlq or high_level_qualifier, but not both.

Other Parameters

**`admin`** : (**bool**) - Sets the ADMINISTRATOR keyword for the ADRDSSU
RESTORE command. Acts as a DFSMSdss storage administrator.  For administrators,
DFSMSdss bypasses access checking for data sets and catalogs.

**`bypass_acs`** : (**str**) - Specifies that Automatic Class Selection (ACS)
routines are not to be invoked to determine the target data set's storage
class or management class names. Equivalent to BYPASSACS command keyword.

• dataset : (str) - Source is a dataset.

• dest_volume : (str) - Specifies a particular volume should be used when creating temporary datasets.

• exclude : (str) - Exclude particular dataset patterns when restoring the datasets from the dzip archive.

  import_dataset : (bool) - Specifies that the data sets that are being restored were dumped from a different system and they should be considered new data sets. Equivalent to IMPORT command keyword.

• include : (str) - Include particular dataset patterns from the dzip binary file in the unzipped contents.

• high_level_qualifier : (str), optional - Single segment HLQ to unpack to. None by default, which unpacks to the user's HLQ

• keep_original_hlq : (bool) - Restores the datasets to their original high-level-qualifier. You can use either keep_original_hlq or high_level_qualifier, but not both.

• management_class_name : (str) - Specifies the user-desired management class that is to replace the source management class as input to the ACS routines.

  no_rename : (bool) - Restore datasets to their original HLQ from when they were archived. This overrides any value specified by the keep_original_hlq argument, if any. Equivalent to RENUNC command keyword.

  null_management_class : (bool) - Specifies that the input to the ACS routines is a null management class rather than the source data set's management class. Equivalent to NULLMGMTCLAS command keyword.

  null_storage_class : (bool) - Specifies that the input to the ACS routines is to be a null storage class rather than the source data set's storage class. Equivalent to NULLSTORCLAS command keyword.

• overwrite : (bool) - Overwrite existing datasets with the same name on target device.

  rename : (bool) - Specifies that, if a data set with the old name exists on the output DASD volume, DFSMSdss is to allocate a new data set with the new name and restore the data set. If the data set with the old name does not exist on the volume, the data set is restored with the old name. For a VSAM data set that already exists on another DASD volume and is cataloged, the VSAM data set is restored with the new name unless the new name also exists and is cataloged. Equivalent to RENAME command keyword.

  share : (bool) -Specifies that DFSMSdss is to share, for read access with other programs, the data sets that are to be restored. The resetting of the data set change indicator is bypassed if share is specified on a data set restore operation. Equivalent to the SHARE command keyword.

• sms_for_tmp : (bool) - Specifies the SMS classes specified with -S and/or -m should be used when creating temporary datasets.

  sphere : (bool) - Specifies that for any VSAM cluster dumped with the SPHERE keyword, DFSMSdss must also restore all associated AIX clusters and paths. Individual sphere component names need not be specified; only the base cluster name is required. Equivalent to the SPHERE keyword.

• src_volume : (str) - Name of volume to unzip.

• storage_class_name : (str) - Specifies the user-desired storage class that is to replace the source storage class as input to the ACS routines.

• target_gds : (str) - Specifies the status in which SMS-managed generation datasets are to be restored. The target GDG base must exist for a successful restore. Status may be one of the following:

  • active
  • deferred
  • rolledoff
  • source

• tmphlq : (str) - Use an alternative high-level qualifier (HLQ) for the temporary dataset name.

• volume : (str) - Unzip volume (default is dataset).

Description

• Zip datasets into an HFS file.

Returns

• Return code from z/OS.

Return type

• int

Parameters

• file (str) – Fully qualified HFS file path or data set.

• target (str) – Dataset name or dataset pattern.

Other Parameters

• dataset (str) - Dataset name or pattern to archive.

• dest_volume (str) - Specifies a particular volume should be used when creating temporary and target datasets.

• exclude (str) - Exclude particular dataset patterns when dumping the source datasets. This option is ignored if dumping a volume.

• force (bool) - Specifies potentially recoverable errors should be tolerated.

• management_class_name (str) - Specifies the user-desired management class that is to be used when creating temporary and target datasets.

• overwrite (bool) - Overwrite file or dataset destination if it already exists.

• size (int) - Specify how large to allocate datasets. Valid units are: CYL, TRK, K, M, G. Defaults to bytes if no unit provided.

• src_volume (str) - Dump a volume instead of datasets.

• storage_class_name (str) - Specifies the user-desired storage class is to be used when creating temporary and target datasets.

• tmphlq (str) - Use an alternative high-level qualifier (HLQ) for temporary dataset name.

• volume (str) - Dump a volume instead of datasets.

Description

• Check whether or not a dataset exists.

Returns

• True or False.

Return type

• bool

Raises

• ZOAUException – See message for details.

Parameters

• dataset (str) – The dataset to check for.

Description

• Find dataset that contains member within a concatenation. Returns the first dataset that contains member.

Returns

• The dataset name containing the member.

Return type

• str

Parameters

• member (str) – The member to find.

• concatenation (str) – The concatenation of datasets (e.g “IBMUSER.A:IBMUSER.B”).

Examples

• datasets.find_member(“PGM”, “:”.join(“IBMUSER.A”, “IBMUSER.B”))

Notes

• User can call _find_member to receive a ZOAUResponse object.

Description

• Replace text within a dataset.

Returns

• Return code from z/OS.

Return type

• int

Parameters

• dataset (str) – Dataset to act on.

• find (str) – String to find.

• replace (str) – String to replace find with.

Description

• Get the active TSO high-level qualifier (HLQ).

Returns

• The active TSO high-level qualifier.

Return type

• str

Description

• ZOAU dsed function to be used by zos_lineinfile Ansible module.

Returns

• Return code from z/OS.

Return type

• int

Parameters

• dataset (str) – The target dataset or HFS file to modify to (e.g “IBMUSER.TEST.MOD”).

• state (bool) – True (default): Insert or replace block. False: Remove block.

Other Parameters

• line (str) – The line to insert/replace.

• regex (str) – The regular expression to look for in every line of the dataset or HFS file.

  • For state = True, the pattern to replace if found. Only the last line found will be replaced.

  • For state = False, the pattern of the line(s) to remove.

  • If the regular expression is not matched, the line will be added to the dataset or HFS file in keeping with insert_after or insert_before settings.

• insert_after (str) – Insert line after matching regex pattern.

  • The special value “EOF” will insert the line at the end of the target dataset or HFS file.

  • If regex is provided, insert_after is only honored if no match for regex is found.

  • insert_before will be ignored if provided.

• insert_before (str) – Insert line before matching regex pattern.

  • The special value “BOF” will insert the line at the beginning of the target dataset or HFS file.

  • If regex is provided, insert_before is only honored if no match for regex is found.

  • insert_before will be ignored if insert_after is provided.

• first_match (bool) – If set, insert_after and insert_before will work with the first line that matches the given regular expression.

• encoding (str) – Encoding of the dataset.

• lock (bool) – Obtain exclusive lock for the dataset.

• force (bool) – Force open. Open dataset member in DISP=SHR mode. Default is DISP=OLD mode when False.

• backref (bool) – Use back references in regular expressions. Default is False.

Notes

• Use debug = True parameter for debug information in JSON format.
• lineinfile() supports operations on generation datasets (GDS). GDS relative name notation is supported, but the GDG base is not protected during execution. Use a batch job if you need to serialize the group.

Description

• Returns a list of the datasets that match the supplied pattern, excluding migrated or tape datasets. To include migrated and tape datasets in the list, use list_dataset_names().

Returns

• List of Dataset objects, empty list if none found.

Return type

• list

Raises

• ZOAUException – See message for details.

Parameters

• pattern (str) – Pattern to match, such as "IBMUSER.*".

• volume (str) - Filter dataset by volume name.

Description

• List the contents of a given volume.

Returns

• List of Dataset objects with only these attributes set: name, organization, record_format, record_length, volume

Return type

• list

Parameters

• volume (str) – Volume to list.

Description

• Returns a listing of names matching the supplied pattern.

Returns

• List of dataset names as strings, empty list if none found.

Return type

• list

Raises

• ZOAUException – See message for details.

Parameters

• pattern (str) – Pattern to match, such as "IBMUSER.*".

• migrated (bool) - Enables fetching information from migrated datasets, by default False.

Description

• Get a list of members from a dataset.

Returns

• Members contained within dataset.

Return type

• list[str]

Parameters

• alias (bool) - Display dataset member aliases. Enabled by default.

• pattern (str) – The dataset pattern to search.

Description

• Returns a listing of Datasets matching the supplied pattern.

Returns

• List of Dataset objects found. These objects will have only the name attribute set

Return type

• list

Raises

• ZOAUException – See message for details.

Parameters

• pattern (str) – Pattern to match, such as "IBMUSER.*".

• migrated (bool) - Display migrated datasets.

Description

• Move (rename) a non-VSAM dataset or generation data group (GDG).

Returns

• True if successful.

Return type

• bool

Raises

• ZOAUException – See message for details.

Parameters

• source (str) – The source dataset name or GDG base name.

• target (str) – The target dataset name or GDG base name.

Notes

The generation dataset relative name syntax is supported. move() can only rename generation data groups and generation datasets located on disk.

Description

• Move (rename) a member.

Returns

• Return code from z/OS.

Return type

• int

Parameters

• dataset (str) – The dataset that contains the member.

• source (str) – The current member name.

• target (str) – The desired member name.

Description

• Get the contents of a non-VSAM dataset.

Returns

• Contents of the dataset.

Return type

• str

Parameters

• dataset (str) – The dataset to read. Generation dataset relative name notation is supported.

Other Parameters

• tail (int) – Read the last tail lines from the dataset.

• from_line (int) – Returns lines from the given line.

Description

• Get the contents of a non-VSAM dataset.

Returns

• Contents of the dataset.

Return type

• Bytes

Parameters

• dataset (str) – The dataset to read. Generation dataset relative name notation is supported.

• tail (int) – Read the last tail lines from the dataset.

• from_line (int) – Returns lines from the given line.

• suppress_newlines (boolean) – Do not print a newline character between each line in the dataset output. Useful if the dataset has binary data.

Description

• A function to display the head content of a non-VSAM dataset.

Returns

• Contents of the dataset.

Return type

• str

Parameters

• dataset (str) – The dataset to read. Generation dataset relative name notation is supported.

Other Parameters

• nlines (int) – Read the first nlines lines from the dataset.

Description

• Search a dataset using ISRSUPC.

Returns

• str (ISRUPSC output) – The ISRUPSC output from the search command.

• None - Content was not found in dataset.

Parameters

• dataset (str) – The dataset to search.

• value (str) – The string to search for in dataset.

Other Parameters

• count_lines (bool) - Print only a count of matched lines in the dataset.

• display_lines (bool) - Display the line number for each match.

• lines (int) - Number of lines to be shown before and after each match.

• ignore_case (bool) - Ignore case for search.

Description

• Creates a temporary dataset name.

Returns

• Temporary dataset name.

Return type

• str

Parameters

• high_level_qualifier (str) – The high-level qualifier of the temporary dataset name. Maximum of 17 characters long. Example: "HLQ.NAME".

Description

• Write content to a z/OS data set.

Returns

• RC from z/OS.

Return type

• int

Parameters

• dataset (str) – Dataset to write content to.

• content (str) – String to write to the dataset.

• append (bool) – Append-mode will add the content to the end of the dataset.

Other Parameters

• force (bool) – Force open. Open dataset member in DISP=SHR mode. Default is DISP=OLD mode when False.

Notes

Generation dataset (GDS) relative name notation is supported. When using a positive generation level, the function creates a dataset with variable record format.