• Getting Started (Installation Guide)
• pyIPCS Versioning and Updates
• pyIPCS User Guide
• Report a Bug or Request a Feature
• Contribute to pyIPCS
• Documentation
  • Hex Object
  • IpcsSession Object
  • Dump Object
  • Subcmd Object
  • Creating Custom Subcmd Objects
  • SetDef Custom Subcmd Object
  • Util Functions
  • Converting pyIPCS Objects to JSON
  • pyIPCS Logging

• To check your current pyIPCS version:

pip show pyipcs

• Back to Top
• Run IPCS subcommand against single z/OS dump
• Run IPCS subcommands against multiple z/OS dumps

• Back to Example Scripts

# Import pyIPCS objects and util functions
from pyipcs import Hex, IpcsSession, Subcmd
from pyipcs.util import *

# Create IpcsSession object
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
print(dump.data["title"])

# 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 Example Scripts

# Import pyIPCS objects and util functions
from pyipcs import Hex, IpcsSession, Subcmd
from pyipcs.util import *

# Create IpcsSession object
session = IpcsSession()

# Open IPCS Session
session.open()

# String datasets names of z/OS dumps
dsnameA = ...
dsnameB = ...

# Create Dump object `dumpA`
dumpA = session.init_dump(dsnameA)

# Run IPCS subcommand against z/OS dump `dumpA` and store output
subcmdA = Subcmd(session, "LIST TITLE")

# Create Dump object `dumpB`
dumpB = session.init_dump(dsnameB)

# Run IPCS subcommand against z/OS dump `dumpB` and store output
subcmdB = Subcmd(session, "LIST TITLE")

# Set session back to `dumpA`
session.set_dump(dumpA)

# Run IPCS subcommand against z/OS dump `dumpA` and store output
subcmdA2 = Subcmd(session, "STATUS REGISTERS")

# Close IPCS Session
session.close()

• Back to Top

• Contains information about:
  • 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 get the most out of pyIPCS, we strongly recommend checking out the User Guide.

• The User Guide provides:
  • Key Features: Learn about the core capabilities and functionality of the package.
  • Best Practices: Discover tips and recommendations for optimal performance and maintainability.
  • Advanced Features: Dive deeper into advanced functionality to unlock the full potential of the package.

• Back to Top

• To report a bug, or request a feature or other update, please open a new issue.
  • Once you open an issue, there are templates for submitting a Bug Report, Feature Request, Documentation Update, or 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
• 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

Bases: object

• 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. 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.
• ddir (str|None): DDIR that IPCS will use to run subcommands. None if session is not active.
• logger (pyipcs.IpcsLogger): Manages logging for the pyIPCS session.

• Back to IpcsSession Object
• open
• close
• get_allocations
• set_allocation
• update_allocations
• ddir_defaults
• create_ddir
• create_session_ddir
• set_ddir
• get_defaults
• set_defaults
• init_dump
• set_dump
• dsname_in_ddir
• 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

• Get allocations for your TSO environment.

• 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 IpcsSession Methods

• Set a TSO allocation.
• If the specification is an empty list or empty string, will remove or not include DD name-specification pair within allocations

• dd_name (str)
• specifications (str|list[str]): string data set allocation request or list of cataloged datasets

• None

• Back to IpcsSession Methods

• Update multiple TSO allocations.

• 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_old_allocations (bool): Optional. If True, will clear all old allocations before setting new allocations. Default is True.

• None

• Back to IpcsSession Methods

• Returns default parameters for dump directory creation.
• Input arguments to edit defaults.
• Returns BLSCDDIR CLIST parameters where keys are BLSCDDIR parameters and the values are BLSCDDIR parameter values.
• BLSCDDIR Documentation

• 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)').

• dict: Keys are BLSCDDIR parameters and the values are BLSCDDIR parameter values.

• Back to IpcsSession Methods

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

• ddir (str): Dump directory that will be created.
• 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 IpcsSession Methods

• Create pyIPCS session dump directory. Will be deleted on session close.
• Adding additional keyword arguments will override pyIPCS DDIR defaults.
• BLSCDDIR Documentation

• 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)').

• str: pyIPCS session DDIR dataset name

• Back to IpcsSession Methods

• Set ddir as the current dump directory for the session.

ddir (str): Dump directory will be set as the sessions DDIR

• None

• Back to IpcsSession Methods

• Run SETDEF LIST to get IPCS defaults.

• pyipcs.SetDef: Custom SETDEF Subcmd Object. outfile parameter is set to False for string output.

• Back to IpcsSession Methods

• Runs SETDEF with LIST parameter and other parameters to set IPCS defaults
• SETDEF subcommand
• Address processing parameters
• Only Global Defaults impact the pyIPCS session.

• confirm (bool|None): Optional. True for CONFIRM parameter. False for NOCONFIRM parameter. Default is None to not include parameter in subcommand.
• dsname (str|None): Optional. String dataset name to be used for DSNAME parameter. Default is None to not include parameter in subcommand.
• nodsname (bool): Optional. True for NODSNAME parameter. Default is False to not include parameter in subcommand.
• asid (pyipcs.Hex|str|int|None): Optional. pyipcs.Hex object or string or int to be used for ASID parameter. Default is None to not include parameter in subcommand.
• dspname (str|None): Optional. String dataspace name to be used for DSPNAME parameter. Default is None to not include parameter in subcommand.
• setdef_params (str|None): Optional. String of SETDEF parameters. Write parameters as you would in regular IPCS (ex: 'ACTIVE LENGTH(4)'). Default is None to not include in subcommand.

• pyipcs.SetDef: Custom SETDEF Subcmd Object. outfile parameter is set to False for string output.

• 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 not specified, 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

• Check if dataset is a source described in the current session DDIR.
• Used to check if a dump dataset was initialized under the current DDIR.

• dsname (str): Dataset name.

• bool: True if dataset name a source described in the current DDIR, False if not.

• 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
• Dump Methods

Bases: object

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

• On Dump object initialization:
  • Sets regular or temporary DDIR for dump and parses out general info about dump from various subcommands
  • Initializes/Sets dump dsname under dump directory ddir.
  • Will set IPCS session DDIR to ddir.
  • Will set IPCS default DSNAME to dsname

• session (pyipcs.IpcsSession): IPCS Session.
• dsname (str): Dump dataset name.
• ddir (str): Optional. Dump directory. If not specified, dump will be initialized under temporary DDIR which will be deleted on session close.
• 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.

• dsname (str): Dump dataset name.
• ddir (str|None): Dump directory when dump was initialized.
• data (dict): Dictionary containing general data about the dump. Editable by user to store additional info about a dump. If Dump object cannot find or parse one of the data dictionary items below, the item will not be included in the data dictionary.
  • '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): Not included if 'dump_type'=='SAD'.
  • 'primary' (pyipcs.Hex): Not included if 'dump_type'=='SAD'.
  • 'secondary' (pyipcs.Hex): Not included if 'dump_type'=='SAD'.
  • 'home' (pyipcs.Hex): Not included if 'dump_type'=='SAD'.
  • 'sdwa_asid' (pyipcs.Hex): Not included if 'dump_type'=='SAD'.
  • 'sdwa_address' (pyipcs.Hex): Not included if 'dump_type'=='SAD'.
  • 'blocks_allocated_decimal' (int): Not included if 'dump_type'=='SAD'.
  • 'remote_sysname' (str): Included only if 'remote_dump'==True. Not included if 'dump_type'=='SAD'.
  • 'remote_dump' (bool): Not included if 'dump_type'=='SAD'.
  • 'processor_serial_number' (str)
  • 'processor_model_number' (str)
  • 'sliptrap' (str): Included in data dictionary if 'dump_type'=='SLIP'. Obtained from LIST SLIPTRAP subcommand.
  • 'ipl_date_local' (str): Included in 'data' dictionary if CSA is dumped. Obtained from IPLDATA subcommand.
  • 'ipl_time_local' (str): Included in 'data' dictionary 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. Dictionaries contain the hex ASID on the system, the string jobname, and the 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. Obtained from LISTDUMP subcommand with parameters DSNAME and SELECT:
    • '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):{ str(Dataspace Name) : pyipcs.Hex(Number of bytes dumped for dataspace in hex) }

• 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

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]/pyipcs_session/[time of session open]/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

• Provides More Detailed Explanation

• Indexing:

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

• Find and Get Field Methods:
  • Listed in Subcmd Methods

• 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 end of 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 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 end of 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 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

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

• 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, 
        outfile:bool=False,
        keep_file:bool=False,
    ) -> None:

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

        # Store additional info in data dict attribute
        self.data["new_subcmd_data_key"] = "new_subcmd_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 'new_subcmd_data_value'
print(your_subcmd.data["new_subcmd_data_key"])

session.close()

• Back to Top

Bases: pyipcs.Subcmd

• Runs SETDEF with LIST parameter and other parameters
• SETDEF subcommand
• Address processing parameters
• Can create a pyipcs.SetDef object using pyipcs.IpcsSession.get_defaults() and pyipcs.IpcsSession.set_defaults()
• Only Global Defaults impact the pyIPCS session.

• session (pyipcs.IpcsSession)
• confirm (bool|None): Optional. True for CONFIRM parameter. False for NOCONFIRM parameter. Default is None to not include parameter in subcommand.
• dsname (str|None): Optional. String dataset name to be used for DSNAME parameter. Default is None to not include parameter in subcommand.
• nodsname (bool): Optional. True for NODSNAME parameter. Default is False to not include parameter in subcommand.
• asid (pyipcs.Hex|str|int|None): Optional. pyipcs.Hex object or string or int to be used for ASID parameter. Default is None to not include parameter in subcommand.
• dspname (str|None): Optional. String dataspace name to be used for DSPNAME parameter. Default is None to not include parameter in subcommand.
• setdef_params (str|None): Optional. String of SETDEF parameters. Write parameters as you would in regular IPCS (ex: 'ACTIVE LENGTH(4)'). Default is None to not include in subcommand.
• outfile (bool): Optional.
• keep_file (bool): Optional.

• subcmd (str): SETDEF subcommand that was ran
• outfile (str|None)
• output (str|None)
• keep_file (bool)
• rc (int)
• data (dict): Global Defaults. If Global Defaults are not found in the output the data dictionary will be empty.
  • 'confirm' (bool): True for parameter CONFIRM. False for parameter NOCONFIRM.
  • 'dsname' (str|None): String dataset name for parameter DSNAME. None for parameter NODSNAME.
  • 'asid' (pyipcs.Hex|None): pyipcs.Hex object for parameter ASID. None if parameter ASID is not included.
  • 'dspname' (str|None): String dataspace name for parameter DSPNAME. None if parameter DSPNAME is not included.

• Back to Top
• is_dump
• dump_header_data
• 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

• dsname (str): z/OS dataset name

• bool

• Back To Util Functions

• Obtain info about z/OS dump from dump header without the need to create a Dump object

• dsname (str): z/OS dataset name

• dict: Info about z/OS dump obtained from dump header
  • '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): Not included if 'dump_type'=='SAD'.
  • 'primary' (pyipcs.Hex): Not included if 'dump_type'=='SAD'.
  • 'secondary' (pyipcs.Hex): Not included if 'dump_type'=='SAD'.
  • 'home' (pyipcs.Hex): Not included if 'dump_type'=='SAD'.
  • 'sdwa_asid' (pyipcs.Hex): Not included if 'dump_type'=='SAD'.
  • 'sdwa_address' (pyipcs.Hex): Not included if 'dump_type'=='SAD'.
  • 'blocks_allocated_decimal' (int): Not included if 'dump_type'=='SAD'.
  • 'remote_sysname' (str): Included only if 'remote_dump'==True. Not included if 'dump_type'=='SAD'.
  • 'remote_dump' (bool): Not included if 'dump_type'=='SAD'.
  • 'processor_serial_number' (str)
  • 'processor_model_number' (str)

• 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

Bases: json.JSONEncoder

• Back To Util Functions

• 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( { Hex("1"): Hex("2") }, 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 object keys and values get converted to a string representation for JSON

• Dump JSON:

{
  "dsname" (str)
  "ddir" (str)
  "data" (dict)
}

• Subcmd JSON

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

• Back to Top
• Logging Introduction
• IpcsLogger Object

• Back to pyIPCS Logging
• General Logging Information
• Log Levels
• Log Files
• Default pyIPCS Log Records
• How to Set Log Levels and Create Records

• Back to Logging Introduction

• pyIPCS logging is enabled while the pyIPCS session is open
  • Between calls of pyipcs.IpcsSession.open() and pyipcs.IpcsSession.close()

• pyIPCS Logging is managed by the IpcsLogger object, which is stored in the attribute pyipcs.IpcsSession.logger

• All pyIPCS log records are outputted in JSON format

• Back to Logging Introduction

• There are two separate log levels for the pyIPCS session
  • The Console Log Level
  • The Directory Log Level

• Console Log Level: Controls log level for records outputted to console.
• Directory Log Level: Controls log level for records outputted to files. Log files are placed in directory [pyipcs.IpcsSession.directory]/pyipcs_session/[time of session open]/logs/

• Use log level, NO_LOG to not display any records
  • The Console Log Level and Directory Log Level are NO_LOG by default

• Note: Only records at the specified log level and higher priority will be processed

• Log levels and their priority:

• Back to Logging Introduction

• Files potentially contained in ../logs/ directory:
  • error.log
  • session.log
  • dump.log
  • subcmd.log
  • all.log

• Note: in order for records to be processed the corresponding Directory or Console Log Level must also be met or be of lower priority

• Back to Logging Introduction

• By default pyIPCS already has records for specific log levels:

• Back to Logging Introduction

• Get the current Console Log Level and Directory Log Level:

session = IpcsSession()

session.open()

# Print Console Log Level: NO_LOG
print(session.logger.get_console_level())

# Print Directory Log Level: NO_LOG
print(session.logger.get_directory_level())

session.close()

• Set current Console Log Level and Directory Log Level:

session = IpcsSession()

session.open()

# Set the Console Log Level
session.set_console_level("DUMP")

# Print Console Log Level: DUMP
print(session.logger.get_console_level())

# Set the Directory Log Level
session.set_console_level("SUBCMD")

# Print Directory Log Level: SUBCMD
print(session.logger.get_directory_level())

session.close()

• Log Record:

session = IpcsSession()

# Set the Directory Log Level
session.set_directory_level("SUBCMD")

session.open()

# Print Directory Log Level: SUBCMD
print(session.logger.get_directory_level())

# Log Records: Will appear in subcmd.log and all.log: 

# Record = {"time": [record time], "level": "SUBCMD", "message": "TEST MESSAGE 1"}
session.logger.log("SUBCMD", "TEST MESSAGE 1")

# Record = {"time": [record time], "level": "SUBCMD", "message": "TEST MESSAGE 2", "test_key": "test_value"}
session.logger.log("SUBCMD", "TEST MESSAGE 2", extra={"test_key": "test_value"})

session.close()

• Back to pyIPCS Logging
• IpcsLogger Methods

Bases: object

• Logging Object for pyIPCS
• Attribute logger of the IpcsSession object is of type pyipcs.IpcsLogger and manages logging for the pyIPCS session.

• logging_directory (str): Directory where log files are placed in.

• Back to IpcsLogger Object
• get_console_level
• get_directory_level
• set_console_level
• set_directory_level
• log

• Back To IpcsLogger Methods

• Get log level for records outputted to console.

• str: Log level. Will be one of 'DEBUG', 'SUBCMD', 'DUMP', 'SESSION', 'INFO', 'WARNING', 'ERROR', 'CRITICAL', or 'NO_LOG'

• Back To IpcsLogger Methods

• Get log level for records outputted to files.

• str: Log level. Will be one of 'DEBUG', 'SUBCMD', 'DUMP', 'SESSION', 'INFO', 'WARNING', 'ERROR', 'CRITICAL', or 'NO_LOG'

• Back To IpcsLogger Methods

• Set log level for records outputted to console.

• new_level (str): New log level. Should be one of 'DEBUG', 'SUBCMD', 'DUMP', 'SESSION', 'INFO', 'WARNING', 'ERROR', 'CRITICAL', or 'NO_LOG'

• None

• Back To IpcsLogger Methods

• Set log level for records outputted to files.

• new_level (str): New log level. Should be one of 'DEBUG', 'SUBCMD', 'DUMP', 'SESSION', 'INFO', 'WARNING', 'ERROR', 'CRITICAL', or 'NO_LOG'

• None

• Back To IpcsLogger Methods

• Log a record with message and level in JSON.
• By default the record will include the time, level, and message.
• Can include extra key value pairs for the record using the optional extra parameter.

• level (str): Log level. Should be one of 'DEBUG', 'SUBCMD', 'DUMP', 'SESSION', 'INFO', 'WARNING', 'ERROR', 'CRITICAL', or 'NO_LOG'
• message (str)
• extra (dict): Optional. Extra key-value pairs to include in record. Should follow JSON format.

• None