• Important Disclaimer (Please Read)

• Getting Started (Installation Guide)

• pyIPCS Versioning and Updates

• Report a Bug or Request a Feature

• Contribute to pyIPCS

• pyIPCS Examples

• Documentation

  • Hex Object
  • IpcsSession Object
  • DumpHeader Object
  • Dump Object
  • Subcmd Object
  • Creating Custom Subcmd Objects
  • Util Functions
  • Converting pyIPCS Objects to JSON

• To check your current pyIPCS version:

pip show pyipcs

from pyipcs import Hex, IpcsSession, Subcmd
from pyipcs.util import *

# Create IpcsSession object
# Manages settings for your IPCS session

session = IpcsSession()

# Open IPCS Session

session.open()

# String dataset name of z/OS dump

dsname = ...

# Create Dump object `dump`
# Initializes z/OS dump and stores general info

dump = session.init_dump(dsname)

# Print the dump title
# "SAD", "SVCD", "TDMP", "SYSM", or "SLIP"

if "dump_type" in dump.header:
  print(dump.header["dump_type"])
else:
  print("Dump Type Not Found")

# Run IPCS subcommand against z/OS dump `dump` and store output

subcmd = Subcmd(session, "STATUS REGISTERS")

# Print portion of IPCS subcommand output

print(subcmd[10:20])

# Close IPCS Session

session.close()

• Back to Top

• In order to perform operations, pyIPCS creates temporary execs, DDIRs, and files while the IPCS Session is open.

• Please be aware of leftover datasets and files in the event of unintended cleanup failures.

• High level qualifiers for pyIPCS temporary datasets

  • IpcsSession.hlq
  • IpcsSession.hlq_full

• Directories for pyIPCS temporary files

  • IpcsSession.directory
  • IpcsSession.directory_full

• Back to Top

• Dependencies and Prerequisites
• pyIPCS Installation

• Back to Top

• Major Version (1)

  • Indicates a significant update.
  • Probable to include breaking changes that are not backward-compatible.

• Minor Version (2)

  • Adds new features or functionality.
  • Mostly backward-compatible with previous versions within the same major version.

• Patch Version (3)

  • Fixes bugs or makes small improvements.
  • Always backward-compatible.

• The Changelog file contains info on changes between each new version

• Back to Top

• To report a bug or request a feature/update, please open a new issue.
  • Once you open an issue, there are various templates
    • Bug Report
    • Feature Request
    • Documentation Update
    • Other requests you might have for pyIPCS

• Back to Top

• Follow the link above to get information on how to contribute to pyIPCS

• Back to Top

• You can find practical usage examples and runnable scripts in the /examples directory

• Back to Top
• Arithmetic, Logical, and Bitwise Operations With Hex Object
• Methods

Bases: object

• Contains various methods and functionality to manage hex variables in an IPCS environment
• Accepts strings or integers as input

• value (str|int): Hex string or integer for hex value

• Back to Hex Object

• The Hex object supports a variety of arithmetic, logical, and bitwise operations
• These operations include: + , - , * , / (integer division) , = , == , !=, < , <= , > , >= , % , | , &

    from pyipcs import Hex

    # Use int or str as input for hex value
    x = Hex("A")
    y = Hex(-10)

    # Prints "A"
    print(x)

    # Prints "-A"
    print(y)

    # Arithmetic
    a = Hex("8")
    b = Hex(2)

    c = a + b
    d = a - b
    e = a * b
    f = a < b
    g = a | b

    # Prints "A"
    print(c)

    # Prints "6"
    print(d)

    # Prints "10"
    print(e)

    # Prints False
    print(f)

    # Prints "A" (b"1000" logical OR with b"0010")
    print(g)

• Back to Hex Object

• sign

• unsigned

• get_nibble

• get_byte

• get_half_word

• get_word

• get_doubleword

• to_int

• to_str

• to_char_str

• concat

• resize

• bit_len_no_pad

• bit_len

• turn_on_bit

• turn_off_bit

• check_bit

• Back to Hex Methods

• Get sign of hex value.

• str: "-" or "" depending on whether Hex is positive or negative

• Back to Hex Methods

• Get unsigned hex value.

• pyipcs.Hex: Unsigned Hex

• Back to Hex Methods

• Get 0 indexed nibble. Default 0 index is from left side of hex string.

• nibble (int): 0 indexed nibble position.
• from_right (bool, optional): If True will make 0 index the right most nibble. False by Default.

• pyipcs.Hex: 0 indexed nibble at position nibble

• Back to Hex Methods

• Get 0 indexed byte. Default 0 index is from left side of hex string.

• byte (int): 0 indexed byte position.
• from_right (bool, optional): If True will make 0 index the right most byte. False by Default.

• pyipcs.Hex: 0 indexed byte at position byte

• Back to Hex Methods

• Get 0 indexed half word. Default 0 index is from left side of hex string.

• half_word (int): 0 indexed half word position.
• from_right (bool, optional): If True will make 0 index the right most half word. False by Default.

• pyipcs.Hex: 0 indexed half word at position half_word

• Back to Hex Methods

• Get 0 indexed word. Default 0 index is from left side of hex string.

• word (int): 0 indexed word position.
• from_right (bool, optional): If True will make 0 index the right most word. False by Default.

• pyipcs.Hex: 0 indexed word at position word

• Back to Hex Methods

• Get 0 indexed doubleword. Default 0 index is from left side of hex string.

• doubleword (int): 0 indexed doubleword position.
• from_right (bool, optional): If True will make 0 index the right most doubleword. False by Default.

• pyipcs.Hex: 0 indexed doubleword at position doubleword

• Back to Hex Methods

• Convert hex to an integer.

• int: Hex integer.

• Back to Hex Methods

• Convert Hex object to a hex string.

• str: Hex string.

• Back to Hex Methods

• Convert hex to character string.
• If there is an error reading the hex string to characters, will return empty string("").

• encoding (str, optional): Encoding to use to decode hex string. Default is "ibm1047".

• str: Character string.

• Back to Hex Methods

• Concatenate with other Hex Object.

• other (pyipcs.Hex|Iterable): other Hex object or Iterable of Hex objects to concatenate to the end of the current Hex object. Disregard sign of this variable in concatenation.

• pyipcs.Hex: Concatenated Hex Object.

• Back to Hex Methods

• Convert hex string to new bit length.
• Will either pad hex string with 0s or truncate string at bit length.

• new_bit_length (int): New length of string in bits.

• pyipcs.Hex: Hex with new bit length.

• Back to Hex Methods

• Determine bit length of hex string, not including leading 0s.

• int: Length in bits of hex string, not including leading 0s.

• Back to Hex Methods

• Determine bit length of hex string, including leading 0s.

• int: Length in bits of hex string, including leading 0s.

• Back to Hex Methods

• Turn on bit at 0 indexed bit position. Default 0 index is from left side of hex string.

• bit_position (int): 0 indexed bit position.
• from_right (bool, optional): If True will make 0 index the right most bit. False by Default.

• pyipcs.Hex: Hex with bit at bit_position on

• Back to Hex Methods

• Turn off bit at 0 indexed bit position. Default 0 index is from left side of hex string.

• bit_position (int): 0 indexed bit position.
• from_right (bool, optional): If True will make 0 index the right most bit. False by Default

• pyipcs.Hex: Hex with bit at bit_position off.

• Back to Hex Methods

• Check bit at 0 indexed bit position. Default 0 index is from left side of hex string.

• bit_position (int): 0 indexed bit position.
• from_right (bool, optional): If True will make 0 index the right most bit. False by Default.

• bool: True if bit is on, False if it is off.

• Back to Top
• Methods
• IpcsAllocations Object
• DumpDirectory Object
• SetDef Custom Subcmd Object

Bases: object

• Manages TSO allocations, session EXECs and DDIRs, and controls settings for IPCS Session.

• hlq (str|None, optional): High level qualifier where opened pyIPCS session is or will be under. pyIPCS session includes z/OS MVS datasets for pyIPCS EXECs and DDIRs. High level qualifier has a max length of 16 characters excluding ".". By default is None which will set the high level qualifier as your userid.

• directory (str|None, optional): File system directory where IPCS session directories and files will be placed. By default is None which will set the directory as the current working directory of executed file.

• allocations (dict[str,str|list[str]], optional): Dictionary of allocations where keys are DD names and values are string data set allocation requests or lists of cataloged datasets. The default allocations are dataset SYS1.PARMLIB for DD name IPCSPARM and dataset SYS1.SBLSCLI0 for DD name SYSPROC.

• userid (str): z/OS system userid for current user.
• hlq (str): High level qualifier where opened pyIPCS session is or will be under. pyIPCS session includes z/OS MVS datasets for pyIPCS EXECs and DDIRs.
• directory (str): File system directory where IPCS session directories and files will be placed. These include subcommand output files and other logs.
• active (bool): True if IPCS session is active, False if not active.
• aloc (pyipcs.IpcsAllocations): Manages TSO allocations for your IPCS session. IpcsAllocations Object.
• ddir (pyipcs.DumpDirectory): Manages dump directory(DDIR) functionality for your IPCS session. DumpDirectory Object.
• uid (str|None): Unique ID for open pyIPCS session. None if pyIPCS session is not active.
• hlq_full (str|None): Full high level qualifier for open pyIPCS session. None if pyIPCS session is not active.
• directory_full (str|None): Full directory where pyIPCS files for the open session will be placed. None if pyIPCS session is not active.

• Back to IpcsSession Object
• open
• close
• init_dump
• set_dump
• evaluate

• Back to IpcsSession Methods

• Opens IPCS/TSO Session.
• Create pyIPCS temporary datasets necessary for pyIPCS operations.

• None

• Back to IpcsSession Methods

• Closes IPCS/TSO Session.
• Deletes pyIPCS temporary EXECs and temporary DDIRs.

• None

• Back to IpcsSession Methods

• Initialize/Set dump dsname under dump directory ddir and return Dump object.
• Will set IPCS session DDIR to ddir.
• Will set IPCS default DSNAME to dsname

• dsname (str): Dump dataset name.
• ddir (str, optional): Dump directory. If an empty string, dump will be initialized under temporary DDIR.
• use_cur_ddir (bool, optional): Use current session DDIR. Will use the IpcsSession attribute ddir to initialize the dump under. This will take precedence over this function's ddir parameter. Default is False.

• pyipcs.Dump

• Back to IpcsSession Methods

• Set IPCS session DDIR to Dump object DDIR.
• Set IPCS default DSNAME to Dump object dataset name.

• dump (pyipcs.Dump)

• None

• Back to IpcsSession Methods

• Read data from dump. Similar to EVALUATE subcommand in REXX.
• Make sure to set correct defaults DSNAME, ASID, and DSPNAME prior to calling this method.
• EVALUATE Subcommand

• hex_address (pyipcs.Hex|str|int): Starting hex address to read from.
• dec_offset (int): Byte offset from the starting address in decimal.
• dec_length (int): Byte length of data to access in decimal.

• pyipcs.Hex: Hex object representing the data at the specified address.

• Back to Top
• Back to IpcsSession Object
• Methods

Bases: object

• Manages TSO allocations for IPCS Session.

• Back to IpcsAllocations Object
• get
• set
• drop
• update
• clear

• Back to IpcsAllocations Methods

• Get TSO allocations for your IPCS session.

• dict[str,str|list[str]]: Returns dictionary of all allocations where keys are DD names and values are string data set allocation requests or lists of cataloged datasets.

• Back to IpcsAllocations Methods

• Set a single TSO allocation for your IPCS session.

• dd_name (str)
• specification (str|list[str]): String data set allocation request or list of cataloged datasets.
• extend (bool, optional): If True and DD name dd_name already exists, will add list of datasets from specification to dd_name. Default is False.

• None

• Back to IpcsAllocations Methods

• Remove a specific TSO allocation from your IPCS session by DD name if it exists.

• dd_name (str)

• None

• Back to IpcsAllocations Methods

• Update multiple TSO allocations for your IPCS session.

• new_allocations (dict[str,str|list[str]]): Dictionary of allocations where keys are DD names and values are string data set allocation requests or lists of cataloged datasets.
• clear (bool, optional): If True will clear all allocations before update. Default is True.
• extend (bool, optional): If True, and clear is False, and DD name already exists, will add list of datasets from specification to DD name. Default is False.

• None

• Back to IpcsAllocations Methods

• Clear all TSO allocations for your IPCS session.

• None

• Back to Top
• Back to IpcsSession Object
• Methods
• SetDef Custom Subcmd Object

Bases: object

• Manages dump directory(DDIR) for IPCS Session

• dsname (str|None): Dataset name of dump directory for your IPCS session. None if dump directory is not set.

• Back to DumpDirectory Object
• use
• create
• create_tmp
• presets
• sources
• defaults

• Back to DumpDirectory Methods

• dsname (str): Dump directory that will be set as the session's DDIR.

• None

• Back to DumpDirectory Methods

• Create dump directory.
• Uses BLSCDDIR CLIST to create DDIR.
• Adding additional keyword arguments will fully override pyIPCS DDIR presets.
• BLSCDDIR CLIST

• dsname (str)
• kwargs (dict, optional): Additional parameters (see other parameters)

• dataclas (str, optional)
• mgmtclas (str, optional)
• ndxcisz (int, optional)
• records (int, optional)
• storclas (str, optional)
• volume (str, optional)
• blscddir_params (str, optional): String of BLSCDDIR parameters. Write parameters as you would in regular IPCS (ex: "NDXCISZ(4096)").

• None

• Back to DumpDirectory Methods

• Create temporary dump directory. Will be deleted on IPCS session close.
• Uses BLSCDDIR CLIST to create DDIR.
• Adding additional keyword arguments will fully override pyIPCS DDIR presets.
• BLSCDDIR CLIST

• kwargs (dict, optional): Additional parameters (see other parameters)

• dataclas (str, optional)
• mgmtclas (str, optional)
• ndxcisz (int, optional)
• records (int, optional)
• storclas (str, optional)
• volume (str, optional)
• blscddir_params (str, optional): String of BLSCDDIR parameters. Write parameters as you would in regular IPCS (ex: "NDXCISZ(4096)").

• None

• Back to DumpDirectory Methods

• Presets for dump directory creation.
• Parameters that will be added to BLSCDDIR for pyIPCS dump directory creation.
• Input optional parameters to change presets.
• BLSCDDIR CLIST

• kwargs (dict, optional): Additional parameters (see other parameters)

• dataclas (str, optional): Specifies the data class for the new directory. If you omit this parameter, there is no data class specified for the new directory.
• mgmtclas (str, optional): Specifies the management class for the new directory. If you omit this parameter, there is no management class specified for the new directory.
• ndxcisz (int, optional): Specifies the control interval size for the index portion of the new directory. If you omit this parameter, the IBM-supplied default is 4096 bytes.
• records (int, optional): Specifies the number of records you want the directory to accommodate. If you omit this parameter, the IBM-supplied default is 5000; your installation's default might vary.
• storclas (str, optional): Specifies the storage class for the new directory. If you omit this parameter, there is no storage class specified for the new directory.
• volume (str, optional): Specifies the VSAM volume on which the directory should reside. If you omit DATACLAS, MGMTCLAS, STORCLAS, and VOLUME, the IBM-supplied default is VSAM01. Otherwise, there is no IBM-supplied default.
• blscddir_params (str, optional): String of BLSCDDIR parameters. Write parameters as you would in regular IPCS (ex: "NDXCISZ(4096)").

• None

• Back to DumpDirectory Methods

• Get dataset names of the sources described in the current dump directory of your IPCS session.
• Uses the LISTDUMP IPCS subcommand.
• LISTDUMP Subcommand

• list[str]: Returns list of dataset names of the sources described in current the dump directory of your IPCS session.

• Back to DumpDirectory Methods

• Get/Set default values for certain parameters on IPCS subcommands for your IPCS session.
• Uses the SETDEF LIST IPCS subcommand.
• IPCS uses the new default value for both your current session and any subsequent sessions in which you use the same user dump directory, until you change the value.
• Note that pyIPCS only sets global defaults.
• SETDEF Subcommand

• kwargs (dict, optional): Additional parameters (see other parameters)

• confirm (bool, optional): True for CONFIRM parameter. False for NOCONFIRM parameter.
• dsname (str|None, optional): String dataset name to be used for DSNAME parameter. None for NODSNAME parameter.
• display (list[str], optional): List of sub parameters to be used for DISPLAY parameter. Possible values in the list can include "MACHINE", "REMARK", "REQUEST", "STORAGE", "SYMBOL", "ALIGN", "NOMACHINE", "NOREMARK", "NOREQUEST", "NOSTORAGE", "NOSYMBOL", "NOALIGN".
• flag (str, optional): String severity to be used for FLAG parameter. Possible string options include ERROR, INFORMATIONAL, SERIOUS|SEVERE, TERMINATING, WARNING.
• length (pyipcs.Hex|str|int, optional): pyipcs.Hex object or string or int to be used for LENGTH parameter.
• pds (bool, optional): True for PDS parameter. False for NOPDS parameter.
• asid (pyipcs.Hex|str|int, optional): pyipcs.Hex object or string or int to be used for ASID parameter.
• dspname (str, optional): String dataspace name to be used for DSPNAME parameter.
• setdef_params (str, optional): String of SETDEF parameters. Write parameters as you would in regular IPCS (ex: "ACTIVE LENGTH(4)").

• pyipcs.SetDef: Custom SETDEF Subcmd Object. SetDef Custom Subcmd Object

• Back to Top
• Back to IpcsSession Object
• Back to DumpDirectory Object

Bases: pyipcs.Subcmd

• SetDef Custom Subcmd Object
• Runs SETDEF with LIST parameter and other parameters
• SETDEF subcommand
• Address processing parameters
• Can generate SetDef object using pyipcs.IpcsSession.ddir.defaults(..)
• Only Global Defaults impact the pyIPCS session.

• data (dict): Global Defaults. Keys may not appear if information is unknown or unavailable.
  • "confirm" (bool): True for CONFIRM. False for NOCONFIRM.
  • "dsname" (str|None): String dataset name for parameter DSNAME. None for NODSNAME.
  • "display" (list[str]|None): List of sub parameters for DISPLAY parameter. None if DISPLAY is not in output. Possible values in the list can include "MACHINE", "REMARK", "REQUEST", "STORAGE", "SYMBOL", "ALIGN", "NOMACHINE", "NOREMARK", "NOREQUEST", "NOSTORAGE", "NOSYMBOL", "NOALIGN".
  • "flag" (str|None): String severity for parameter FLAG. None if FLAG is not in output. Possible string options include "ERROR", "INFORMATIONAL", "SERIOUS"|"SEVERE", "TERMINATING", "WARNING".
  • "length" (pyipcs.Hex|None): pyipcs.Hex object for parameter LENGTH. None if LENGTH is not in output.
  • "pds" (bool): True for PDS. False for NOPDS.
  • "asid" (pyipcs.Hex|None): pyipcs.Hex object for parameter ASID. None if ASID is not in output.
  • "dspname" (str|None): String dataspace name for parameter DSPNAME. None if DSPNAME is not in output.

• Back to Top
• Dump Object

Bases: dict

• Custom Dictionary with info about a dump from the dump header.
• Does not require dump initialization to instantiate object.
• Reference dump header either with header = DumpHeader(YOUR.DUMP.DSNAME) or referencing pyipcs.Dump.header. Dump Object
• Keys may not appear if information is unknown or unavailable.

• dsname (str): Dump Dataset Name.

• "dump_type" (str): "SAD", "SVCD", "TDMP", "SYSM", or "SLIP"
• "sysname" (str)
• "date_local" (str)
• "time_local" (str)
• "title" (str)
• "original_dump_dsn" (str)
• "version" (int): For example z/OS version 3 release 1
• "release" (int): For example z/OS version 3 release 1
• "sdrsn" (str)
• "complete_dump" (bool)
• "home_jobname" (str)
• "primary" (pyipcs.Hex)
• "secondary" (pyipcs.Hex)
• "home" (pyipcs.Hex)
• "sdwa_asid" (pyipcs.Hex)
• "sdwa_address" (pyipcs.Hex)
• "blocks_allocated_decimal" (int)
• "remote_sysname" (str): Appears only if remote_dump=True
• "remote_dump" (bool)
• "processor_serial_number" (str)
• "processor_model_number" (str)

• The following keys are unknown or unavailable if dump_type="SAD":
  • "home_jobname"
  • "primary"
  • "secondary"
  • "home"
  • "sdwa_asid"
  • "sdwa_address"
  • "blocks_allocated_decimal"
  • "remote_sysname"
  • "remote_dump"

• Back to Top
• Dump Methods

Bases: object

• Initializes a z/OS dump and stores general information.
• Can create a Dump object using pyipcs.IpcsSession.init_dump()

• dsname (str): Dump dataset name.
• ddir (str): Dump directory when dump was initialized.
• header (pyipcs.DumpHeader): Custom dictionary object containing information about the dump from the dump header. DumpHeader Object
• data (dict): Dictionary containing general information about the dump from various subcommands. Editable by user to store additional info about a dump. Keys may not appear if information is unknown or unavailable.
  • "sliptrap" (str): Included in data dictionary if the dump is a SLIP dump. Obtained from LIST SLIPTRAP subcommand.
  • "ipl_date_local" (str): Known if CSA is dumped. Obtained from IPLDATA subcommand.
  • "ipl_time_local" (str): Known if CSA is dumped. Obtained from IPLDATA subcommand.
  • "asids_dumped" (list[pyipcs.Hex]): List of ASIDs that were dumped. Obtained from CBF RTCT subcommand.
  • "asids_all" (list[dict]): Info about all asids on the system at the time of the dump. List of dictionaries containing the hex asid, string jobname, and ASCB address. Obtained from SELECT ALL subcommand.
    • "asid" (pyipcs.Hex)
    • "jobname" (str)
    • "ascb_addr" (pyipcs.Hex)
  • "storage_areas" (list[dict]): Info about dumped storage areas. Contains dataspace information. Obtained from LISTDUMP subcommand with DSNAME and SELECT parameters.
    • "asid" (pyipcs.Hex)
    • "total_bytes" (pyipcs.Hex|None): Total number of bytes dumped for ASID in hex. None if total_bytes for ASID is not defined in LISTDUMP.
    • "sumdump" (pyipcs.Hex): Number of SUMMARY DUMP Data bytes dumped in hex.
    • "dataspaces" (dict): Dictionary where the keys are the string dataspace names. Values are Hex objects containing the number of bytes dumped for dataspace.

• Back to Dump Object
• asid_to_jobname
• jobname_to_asid
• asid_to_ascb_addr

• Back to Dump Methods

• Get Jobname from ASID.
• Obtained info from SELECT ALL subcommand.

• asid (pyipcs.Hex|str|int)

• str|None: Jobname associated with ASID or None if ASID is not found.

• Back to Dump Methods

• Get ASID from Jobname.
• Obtained info from SELECT ALL subcommand.

• jobname (str)

• list[pyipcs.Hex]: List of ASIDs associated with jobname.

• Back to Dump Methods

• Get ASCB address from ASID.
• Obtained info from SELECT ALL subcommand.

• asid (pyipcs.Hex|str|int)

• pyipcs.Hex|None: ASCB address associated with ASID or None if ASID is not found.

• Back to Top
• Extracting and Parsing Subcommand Output
• Subcmd Methods
• Creating Custom Subcmd Objects

Bases: object

• Runs IPCS subcommand and stores output in string or file.

• session (pyipcs.IpcsSession)
• subcmd (str): IPCS subcommand to run.
• outfile (bool, optional): If True, will create and store output in directory [pyipcs.IpcsSession.directory_full]/subcmd_output/. File would then be specified in outfile attribute of Subcmd object. If False, stores output in string specified in output attribute of Subcmd object. Default is False.
• keep_file (bool, optional): If True preserves subcommand output file after program execution. If False deletes subcommand output file after program execution. Default is False.
• auth (bool, optional): If True, subcommand will be run from an authorized environment. Default is False.

• subcmd (str): IPCS subcommand that was ran.
• outfile (str|None): File containing subcommand output. None if outfile parameter in constructor was set to False or if file was deleted with pyipcs.Subcmd.delete_file() method.
• output (str): Returns string containing the entire subcommand output.
• keep_file (bool): If True preserves subcommand output file after program execution. If False deletes subcommand output file after program execution. Editable by user.
• rc (int): Return code from running subcommand.
• data (dict): Editable by user to store additional info about a IPCS subcommand. Initially empty.

• Back to Subcmd Object

• There are a few methods of extracting data from subcommand output

  • Find Methods: Find the index of a particular string within subcommand output.

    • Subcmd.find
    • Subcmd.rfind

  • Get Field Methods: Get a particular value within subcommand output based on a label that precedes the value.

    • Subcmd.get_field
    • Subcmd.get_field2
    • Subcmd.rget_field
    • Subcmd.rget_field2

  • Direct Indexing

    subcmd = Subcmd(session, "STATUS REGISTERS")
    # indexed_output = string of portion of subcommand output
    indexed_output = subcmd[10:20]

• Back to Subcmd Object
• find
• rfind
• get_field
• get_field2
• rget_field
• rget_field2
• delete_file

• Back to Subcmd Methods

• Find the first occurrence of a substring. Returns -1 if the value is not found.

• substring (str): Substring to search for.
• start (int, optional): Index where to start the search. Default is 0.
• end (int|None, optional): Index where to end the search. Default is None for the end of the output.

• int: Output index where substring was found. -1 if substring was not found.

• Back to Subcmd Methods

• Find the last occurrence of a substring. Returns -1 if the value is not found.

• substring (str): Substring to search for.
• start (int, optional): Index where to end the reverse search. Default is 0.
• end (int|None, optional): Index where to start the reverse search. Default is None for the end of the output.

• int: Output index where substring was found. -1 if substring was not found.

• Back to Subcmd Methods

• Attempts to get the field value from the output based on a label, separator, and end string.

• label (str): The label of the field.
• end_string (str): End string that indicates the end of the value.
• separator (str, optional): The separator between the label and the value.
• start (int, optional): Index where to start the search. Default is 0.
• end (int|None, optional): Index where to end the search. Default is None for the end of the output.
• to_hex (bool, optional): Return value as pyipcs.Hex if to_hex is True. Default is False for returning a string.

• list: A list [value (str|pyipcs.Hex), start (int), end (int)] where subcmd[start:end] == value. [None, -1, -1] if field is not found.

• Back to Subcmd Methods

• Attempts to get the field value from the output based on a label, separator, and field length.

• label (str): The label of the field.
• length (int): Length of the value to get.
• separator (str, optional): The separator between the label and the value.
• start (int, optional): Index where to start the search. Default is 0.
• end (int|None, optional): Index where to end the search. Default is None for the end of the output.
• to_hex (bool, optional): Return value as pyipcs.Hex if to_hex is True. Default is False for returning a string.

• list: A list [value (str|pyipcs.Hex), start (int), end (int)] where subcmd[start:end] == value. [None, -1, -1] if field is not found.

• Back to Subcmd Methods

• Attempts to get the field value in a reverse search from the output based on a label, separator, and end string.

• label (str): The label of the field.
• end_string (str): End string that indicates the end of the value.
• separator (str, optional): The separator between the label and the value.
• start (int, optional): Index where to end the reverse search. Default is 0.
• end (int|None, optional): Index where to start the reverse search. Default is None for the end of the output.
• to_hex (bool, optional): Return value as pyipcs.Hex if to_hex is True. Default is False for returning a string.

• list: A list [value (str|pyipcs.Hex), start (int), end (int)] where subcmd[start:end] == value. [None, -1, -1] if field is not found.

• Back to Subcmd Methods

• Attempts to get the field value in a reverse search from the output based on a label, separator, and field length.

• label (str): The label of the field.
• length (int): Length of the value to get.
• separator (str, optional): The separator between the label and the value.
• start (int, optional): Index where to end the reverse search. Default is 0.
• end (int|None, optional): Index where to start the reverse search. Default is None for the end of the output.
• to_hex (bool,optional). Return value as pyipcs.Hex if to_hex is True. Default is False for returning a string.

• Back to Subcmd Methods

• Method to preemptively delete file associated with subcommand. Will not be able to index into file output after completion.

• None

• Back to Top
• Back to Subcmd Object

• pyIPCS allows users to create custom Subcmd objects for specific subcommands and or specific issues.

• Users can use the data attribute of the Subcmd objects to store additional info.

from pyipcs import IpcsSession, Subcmd

class YourSubcmd(Subcmd):

    def __init__(self, session:IpcsSession) -> None:

        # Call constructor from original Subcmd object
        super().__init__(session, "YOUR SUBCMD")

        # Store additional info in data dict attribute
        self.data["data_key"] = "data_value"  


session = IpcsSession()
session.open()

# String dataset name of z/OS dump

dsname = ...

dump = session.init_dump(dsname)

# Run 'YOUR SUBCMD' with custom Subcmd object

your_subcmd = YourSubcmd(session)

# Will print 'data_value'

print(your_subcmd.data["data_key"])

session.close()

• Back to Top
• is_dump
• psw_scrunch
• psw_parse
• opcode
• addr_key
• addr_fetch_protected
• is_hex
• IpcsJsonEncoder

from pyipcs.util import *

• Back To Util Functions

• Determine whether dataset is a z/OS dump
• Will recall dataset if it exists.

• dsname (str): z/OS dataset name

• bool

• Back To Util Functions

• Scrunch 128 bit PSW to 64 bits
• If 64 bit PSW is inputted as argument return PSW as is

• psw (pyipcs.Hex): 128 bit PSW or 64 bit PSW

• pyipcs.Hex: 64 bit PSW

• Back To Util Functions

• Obtain data from PSW.

• psw (pyipcs.Hex): 128 bit PSW or 64 bit PSW.

• dict: data from PSW
  • "enabled" (bool|None): True for Enabled for I/O and External Interrupts if bit 6 and 7 are on. False for Disabled for I/O and External Interrupts if they are both off. None if one of either bit 6 or 7 is on and one is off.
  • "key" (int): PSW key.
  • "privileged" (bool): True for supervisor state(privileged). False for problem program state(unprivileged)
  • "asc_mode" (str): One of either "PRIMARY", "AR", "SECONDARY", or "HOME".
  • "cc" (int): Condition code.
  • "amode" (int|None): Either 24, 31, 64, or None if invalid.
  • "instr_addr" (pyipcs.Hex): Instruction address.

• Back To Util Functions

• Get mnemonic of instruction.
• Runs OPCODE subcommand.

• session (pyipcs.Session)
• instr (str|int|pyipcs.Hex): Instruction to get mnemonic from.

• str|None: Instruction mnemonic. Returns None if OPCODE subcommand returns with non-zero return code or mnemonic can't be found.

• Back To Util Functions

• Get storage key of storage address.
• Runs LIST subcommand with the DISPLAY parameter.
• Make sure to set correct defaults DSNAME, ASID, and DSPNAME prior to calling this function.

• session (pyipcs.IpcsSession)
• storage_addr (str|int|pyipcs.Hex): Storage Address.

• int|None: Storage key. Returns None if LIST subcommand with the DISPLAY parameter subcommand returns with non-zero return code or key can't be determined.

• Back To Util Functions

• Return if storage address is fetch protected.
• Runs LIST subcommand with the DISPLAY parameter.
• Make sure to set correct defaults DSNAME, ASID, and DSPNAME prior to calling this function.

• session (pyipcs.IpcsSession)
• storage_addr (str|int|pyipcs.Hex): Storage Address.

• bool: True if storage_addr is fetch protected, False if not. Returns None if LIST subcommand with the DISPLAY parameter subcommand returns with non-zero return code or fetch protected can't be determined.

• Back To Util Functions

• Check if string is hex

• hex_str (str)

• bool: True if string is hex, False if not.

• Back To Util Functions

Bases: json.JSONEncoder

• Custom pyIPCS JSON Encoder.
• Can be specified in the cls parameter of json.dump and json.dumps functions to convert Hex, Dump, and Subcmd objects to JSON.

• Back to Top

• pyIPCS objects can be converted to JSON using the IpcsJsonEncoder object from the util library.

• Examples:

import json
from pyipcs import Hex, IpcsSession, Subcmd
from pyipcs.util import IpcsJsonEncoder

# Setup

dsname = ...
session = IpcsSession()
dump = session.init_dump(dsname)
subcmd = Subcmd(session, "STATUS REGISTERS")

# Convert Hex, Dump, and Subcmd objects to JSON strings

hex_json = json.dumps( { "Key": Hex("1") }, cls=IpcsJsonEncoder)

dump_json = json.dumps(dump, cls=IpcsJsonEncoder)

subcmd_json = json.dumps(subcmd, cls=IpcsJsonEncoder)

# Write Subcmd JSON to file

with open("output.json", "w") as f:
    json.dump(subcmd, f, cls=IpcsJsonEncoder)

• Hex JSON

{
  "__ipcs_type__": "Hex"
  "value" (str)
}

• Dump JSON:

{
  "__ipcs_type__": "Dump"
  "dsname" (str)
  "ddir" (str)
  "header" (str)
  "data" (dict)
}

• Subcmd JSON

{
  "__ipcs_type__": "Subcmd"
  "subcmd" (str)
  "outfile" (str|None)
  "output" (str),
  "keep_file" (bool)
  "rc" (int)
  "data" (dict)
}