pyIPCS README

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

pyIPCS Version: `1.1.0`

To check your current pyIPCS version:

pip show pyipcs

Example Scripts

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

Run IPCS subcommand against single z/OS dump

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()

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 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()

Getting Started (Installation Guide)

Back to Top

Getting Started

Contains information about:
- Dependencies and Prerequisites
- pyIPCS Installation

pyIPCS Versioning and Updates

Back to Top

Example Version: `1.2.3`

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.

CHANGELOG.md

The Changelog file contains info on changes between each new version

pyIPCS User Guide

Back to Top

User Guide

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.

Report a Bug or Request a Feature

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

Contribute to pyIPCS

Back to Top

How to Contribute to pyIPCS

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

Hex Object

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

class pyipcs.Hex(value)

Bases: object

Description

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

Args

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

Arithmetic, Logical, and Bitwise Operations With Hex Object

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)

Hex Methods

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

Hex.sign()

Back to Hex Methods

Description

Get sign of hex value.

Returns

str: '-' or '' depending on whether Hex is positive or negative

Hex.unsigned()

Back to Hex Methods

Description

Get unsigned hex value.

Returns

pyipcs.Hex: unsigned Hex

Hex.get_nibble(nibble, from_right)

Back to Hex Methods

Description

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

Args

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

Returns

pyipcs.Hex: 0 indexed nibble at position nibble

Hex.get_byte(byte, from_right)

Back to Hex Methods

Description

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

Args

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

Returns

pyipcs.Hex: 0 indexed byte at position byte

Hex.get_half_word(half_word, from_right)

Back to Hex Methods

Description

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

Args

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.

Returns

pyipcs.Hex: 0 indexed half word at position half_word

Hex.get_word(word, from_right)

Back to Hex Methods

Description

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

Args

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

Returns

pyipcs.Hex: 0 indexed word at position word

Hex.get_doubleword(doubleword, from_right)

Back to Hex Methods

Description

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

Args

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

Returns

pyipcs.Hex: 0 indexed doubleword at position doubleword

Hex.to_int()

Back to Hex Methods

Description

Convert hex to an integer.

Returns

int: hex integer

Hex.to_str()

Back to Hex Methods

Description

Convert Hex object to a hex string.

Returns

str: hex string

Hex.to_char_str()

Back to Hex Methods

Description

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

Args

encoding (str): Optional. Encoding to use to decode hex string. Default is 'ibm1047'.

Returns

str: character string

Hex.concat(other)

Back to Hex Methods

Description

Concatenate with other Hex Object

Args

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.

Returns

pyipcs.Hex: Concatenated Hex Object

Hex.resize(new_bit_length)

Back to Hex Methods

Description

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

Args

new_bit_length (int): new length of string in bits.

Returns

pyipcs.Hex: hex with new bit length.

Hex.bit_len_no_pad()

Back to Hex Methods

Description

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

Returns

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

Hex.bit_len()

Back to Hex Methods

Description

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

Returns

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

Hex.turn_on_bit(bit_position, from_right)

Back to Hex Methods

Description

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

Args

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

Returns

pyipcs.Hex: hex with bit at bit_position on

Hex.turn_off_bit(bit_position, from_right)

Back to Hex Methods

Description

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

Args

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

Returns

pyipcs.Hex: hex with bit at bit_position off

Hex.check_bit(bit_position, from_right)

Back to Hex Methods

Description

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

Args

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

Returns

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

IpcsSession Object

Back to Top
Methods

class pyipcs.IpcsSession(hlq, directory, allocations)

Bases: object

Description

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

Args

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.

Attributes

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.

IpcsSession Methods

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

IpcsSession.open()

Back to IpcsSession Methods

Description

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

Returns

None

IpcsSession.close()

Back to IpcsSession Methods

Description

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

Returns

None

IpcsSession.get_allocations()

Back to IpcsSession Methods

Description

Get allocations for your TSO environment.

Returns

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

IpcsSession.set_allocation(dd_name, specification)

Back to IpcsSession Methods

Description

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

Args

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

Returns

None

IpcsSession.update_allocations(new_allocations, clear_old_allocations)

Back to IpcsSession Methods

Description

Update multiple TSO allocations.

Args

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.

Returns

None

IpcsSession.ddir_defaults(***kwargs*)

Back to IpcsSession Methods

Description

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

Args

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

Returns

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

IpcsSession.create_ddir(ddir, ***kwargs*)

Back to IpcsSession Methods

Description

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

Args

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

Returns

None

IpcsSession.create_session_ddir(***kwargs*)

Back to IpcsSession Methods

Description

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

Args

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

Returns

str: pyIPCS session DDIR dataset name

IpcsSession.set_ddir(ddir)

Back to IpcsSession Methods

Description

Set ddir as the current dump directory for the session.

Args

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

Returns

None

IpcsSession.get_defaults()

Back to IpcsSession Methods

Description

Run SETDEF LIST to get IPCS defaults.

Returns

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

IpcsSession.set_defaults(confirm, dsname, nodsname, asid, dspname, setdef_params)

Back to IpcsSession Methods

Description

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

Args

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.

Returns

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

IpcsSession.init_dump(dsname, ddir)

Back to IpcsSession Methods

Description

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

Args

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.

Returns

pyipcs.Dump

IpcsSession.set_dump(dump)

Back to IpcsSession Methods

Description

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

Args

dump (pyipcs.Dump)

Returns

None

IpcsSession.dsname_in_ddir(dsname)

Back to IpcsSession Methods

Description

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.

Args

dsname (str): Dataset name.

Returns

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

IpcsSession.evaluate(hex_address, dec_offset, dec_length)

Back to IpcsSession Methods

Description

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

Args

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

Returns

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

Dump Object

Back to Top
Dump Methods

class pyipcs.Dump(session, dsname, ddir)

Bases: object

Description

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

Args

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.

Attributes

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) }

Dump.asid_to_jobname(asid)

Back to Dump Methods

Description

Get Jobname from ASID.
Obtained info from SELECT ALL subcommand

Args

asid (pyipcs.Hex|str|int)

Returns

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

Dump.jobname_to_asid(jobname)

Back to Dump Methods

Description

Get ASID from Jobname.
Obtained info from SELECT ALL subcommand

Args

jobname (str)

Returns

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

Dump.asid_to_ascbaddr(asid)

Back to Dump Methods

Description

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

Args

asid (pyipcs.Hex|str|int)

Returns

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

Subcmd Object

Back to Top
Extracting and Parsing Subcommand Output
Subcmd Methods

class pyipcs.Subcmd(session, subcmd, outfile, keep_file, auth)

Bases: object

Description

Runs IPCS subcommand and stores output in string or file.

Args

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.

Attributes

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.

Extracting and Parsing Subcommand Output

Back to Subcmd Object

Refer to User Guide Section - Subcmd Indexing, Find, and Get Field Methods

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

Subcmd Methods

Back to Subcmd Object
find
rfind
get_field
get_field2
rget_field
rget_field2
delete_file

Subcmd.find(substring, start, end)

Back to Subcmd Methods

Description

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

Args

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.

Returns

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

Subcmd.rfind(substring, start, end)

Back to Subcmd Methods

Description

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

Args

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.

Returns

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

Subcmd.get_field(label, end_string, separator, start, end, to_hex)

Back to Subcmd Methods

Description

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

Args

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.

Returns

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

Subcmd.get_field2(label, length, separator, start, end, to_hex)

Back to Subcmd Methods

Description

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

Args

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.

Returns

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

Subcmd.rget_field(label, end_string, separator, start, end, to_hex)

Back to Subcmd Methods

Description

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

Args

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.

Returns

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

Subcmd.rget_field2(label, length, separator, start, end, to_hex)

Back to Subcmd Methods

Description

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

Args

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.

Subcmd.delete_file()

Back to Subcmd Methods

Description

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

Returns

None

Creating Custom Subcmd Objects

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.

Creating a Custom Subcmd Object for IPCS Subcommand `YOUR SUBCMD`

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()

SetDef Custom Subcmd Object

Back to Top

class pyipcs.SetDef(session, confirm, dsname, nodsname, asid, dspname, setdef_params, outfile, keep_file)

Bases: pyipcs.Subcmd

Description

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.

Args

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.

Attributes

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.

Util Functions

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

How To Import Util Functionality

from pyipcs.util import *

pyipcs.util.is_dump(dsname)

Back To Util Functions

Description

Determine whether dataset is a z/OS dump

Args

dsname (str): z/OS dataset name

Returns

bool

pyipcs.util.dump_header_data(dsname)

Back To Util Functions

Description

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

Args

dsname (str): z/OS dataset name

Returns

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)

pyipcs.util.psw_scrunch(psw)

Back To Util Functions

Description

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

Args

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

Returns

pyipcs.Hex: 64 bit PSW

pyipcs.util.psw_parse(psw)

Back To Util Functions

Description

Obtain data from PSW

Args

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

Returns

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

pyipcs.util.opcode(session, instr)

Back To Util Functions

Description

Get mnemonic of instruction
Runs OPCODE subcommand

Args

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

Returns

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

pyipcs.util.addr_key(session, storage_addr)

Back To Util Functions

Description

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.

Args

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

Returns

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.

pyipcs.util.addr_fetch_protected(session, storage_addr)

Back To Util Functions

Description

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.

Args

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

Returns

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.

pyipcs.util.is_hex(hex_str)

Back To Util Functions

Description

Check if string is hex

Args

hex_str (str)

Returns

bool: True if string is hex, False if not

class pyipcs.util.IpcsJsonEncoder()

Bases: json.JSONEncoder

Back To Util Functions

Description

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.

Converting pyIPCS 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)
}

pyIPCS Logging

Back to Top
Logging Introduction
IpcsLogger Object

Logging Introduction

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

General Logging Information

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

Log Levels

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:

Log Level	Priority
`DEBUG`	Lowest
`SUBCMD`	Lower
`DUMP`	V
`SESSION`	V
`INFO`	V
`WARNING`	V
`ERROR`	Higher
`CRITICAL`	Highest

Log Files

Back to Logging Introduction

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

Console/Log File	Records Processed
`error.log`	Log Levels: `WARNING`, `ERROR`, and `CRITICAL`
`session.log`	Log Level: `SESSION`
`dump.log`	Log Level: `DUMP`
`subcmd.log`	Log Level: `SUBCMD`
`all.log`	All Log Levels Excluding: `NO_LOG`
console	All Log Levels Excluding: `NO_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

Default pyIPCS Log Records

Back to Logging Introduction

By default pyIPCS already has records for specific log levels:

Log Level	Messages
`SUBCMD`	`CREATED SUBCMD OBJECT`, `RUNNING SUBCMD`
`DUMP`	`CREATED DUMP OBJECT`, `START INITIALIZE DUMP`, `FINISH INITIALIZE DUMP`, `RUNNING DUMP OBJECT SUBCMDS`, `SET DUMP`
`SESSION`	`SET ALLOCATION`, `CREATE DDIR`, `SET DDIR`
`WARNING`	`CAUGHT WARNING` - All warnings using `warnings.warn()`
`ERROR`	`UNCAUGHT EXCEPTION` - All uncaught exceptions

How to Set Log Levels and Create Records

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()

IpcsLogger Object

Back to pyIPCS Logging
IpcsLogger Methods

class pyipcs.IpcsLogger

Bases: object

Description

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

Attributes

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

IpcsLogger Methods

Back to IpcsLogger Object
get_console_level
get_directory_level
set_console_level
set_directory_level
log

IpcsLogger.get_console_level()

Back To IpcsLogger Methods

Description

Get log level for records outputted to console.

Returns

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

IpcsLogger.get_directory_level()

Back To IpcsLogger Methods

Description

Get log level for records outputted to files.

Returns

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

IpcsLogger.set_console_level(new_level)

Back To IpcsLogger Methods

Description

Set log level for records outputted to console.

Args

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

Returns

None

IpcsLogger.set_directory_level(new_level)

Back To IpcsLogger Methods

Description

Set log level for records outputted to files.

Args

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

Returns

None

IpcsLogger.log(level, message, extra)

Back To IpcsLogger Methods

Description

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.

Args

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.

Returns

None

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
.cspell		.cspell
.github		.github
dev		dev
src		src
.cspell.json		.cspell.json
.gitattributes		.gitattributes
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.pre-commit-config.yaml		.pre-commit-config.yaml
.pylintrc		.pylintrc
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
GETTING_STARTED.md		GETTING_STARTED.md
LICENSE		LICENSE
README.md		README.md
USER_GUIDE.md		USER_GUIDE.md
pyproject.toml		pyproject.toml

Uh oh!

License

Uh oh!

ambitus/pyIPCS

Folders and files

Latest commit

History

Repository files navigation

pyIPCS README

pyIPCS Version: 1.1.0

Example Scripts

Run IPCS subcommand against single z/OS dump

Run IPCS subcommands against multiple z/OS dumps

Getting Started (Installation Guide)

Getting Started

pyIPCS Versioning and Updates

Example Version: 1.2.3

CHANGELOG.md

pyIPCS User Guide

User Guide

Report a Bug or Request a Feature

Contribute to pyIPCS

How to Contribute to pyIPCS

Hex Object

class pyipcs.Hex(value)

Description

Args

Arithmetic, Logical, and Bitwise Operations With Hex Object

Hex Methods

Hex.sign()

Description

Returns

Hex.unsigned()

Description

Returns

Hex.get_nibble(nibble, from_right)

Description

Args

Returns

Hex.get_byte(byte, from_right)

Description

Args

Returns

Hex.get_half_word(half_word, from_right)

Description

Args

Returns

Hex.get_word(word, from_right)

Description

Args

Returns

Hex.get_doubleword(doubleword, from_right)

Description

Args

Returns

Hex.to_int()

Description

Returns

Hex.to_str()

Description

Returns

Hex.to_char_str()

Description

Args

Returns

Hex.concat(other)

Description

Args

Returns

Hex.resize(new_bit_length)

Description

Args

Returns

Hex.bit_len_no_pad()

Description

Returns

Hex.bit_len()

Description

Returns

Hex.turn_on_bit(bit_position, from_right)

pyIPCS Version: `1.1.0`

Example Version: `1.2.3`

IpcsSession.ddir_defaults(***kwargs*)

IpcsSession.create_ddir(ddir, ***kwargs*)

IpcsSession.create_session_ddir(***kwargs*)