Python API modules

zoau_io

The zoau_io module provides Python interfaces to z/OS data sets that are opened in a record stream model.

Three classes are provided within the module:

  • The abstract base class ZIOBase defines a basic interface to z/OS stream models.
  • The concrete class RecordIO extends ZIOBase and defines reading and writing methods for I/O operations over a stream that is opened in record access mode. This model is binary by nature.
    • NOTE: The current version of ZOAU supports read operations. Writing methods will be added in a future version.
  • Instances of the RecordIO_TextWrapper class aggregate one of the RecordIO type and provide a layer to encode and decode the stream into text.

Depending on which arguments are provided, a zopen factory function constructs an instance of one of these classes.

Module constants are as follows:

  • zoautil_py.zoau_io.SEEK_SET = 0
  • zoautil_py.zoau_io.SEEK_CUR = 1
  • zoautil_py.zoau_io.SEEK_END = 2


zoautil_py.zoau_io.zopen(file, mode, encoding, type="record", *args, **kwargs)


Description

  • Open a z/OS data set and return a stream. Raise OSError upon failure. Supported files include regular sequential and partitioned data sets.

Returns

  • A RecordIO or RecordIO_TextWrapper instance depending on whether or not the encoding parameter is given.

Parameters

  • file (str) - Identifies the name of the data set to be opened.

    • Provide the data set name surrounded by quotes and prepending the sequence // to open a fully qualified data set.
      • Example: f"//'{dataset_name}'"
    • The system will apply PROFILE PREFIX to prepend your TSO profile prefix as the HLQ of the provided name if it is not surrounded by quotes.
    • Open a temporary data set by providing the sequence //&& followed by a valid qualifier.
      • Example: "//&&MYTMP"
  • mode (str) - The file mode specifies the type of access requested for the file. Choices are as follows:

    • 'r' - Open the file for reading. The file must exist.
    • 'w' - Open the file for writing. If the file already exists, its contents are destroyed.
    • 'a' - Open the file for writing and append content to the end of the file. The file is created if it does not exist.
    • 'b' - Binary mode, (implicit when using a record access model)
    • '+' - Open the file for updating (reading and writing)
  • encoding (str) - An optional parameter giving the name of the encoding to be used to decode or decode the stream. Only the single byte character set encodings from the EBCDIC package are supported.

  • type (str) - Identifies the open access model to follow for the stream. Currently supports and defaults to the 'record' access model.

Other parameters

  • noseek (bool) - Indicates that the stream may not use repositioning functions. If true the system will try to open the file in QSAM (queued sequential access method). This access method generally provides the best performance. If the parameter is omitted or false, the access method will be BSAM (basic sequential access method).


class zoautil_py.zoau_io.RecordIO(file, mode='r', /, *, noseek)


Description

  • Open a z/OS data set as a record stream.

Parameters

  • file (str) - The file name (data set name).

    • Provide the data set name surrounded by quotes and prepending the sequence // to open a fully qualified data set.
      • Example: f"//'{dataset_name}'"
    • The system will apply PROFILE PREFIX to prepend your TSO profile prefix as the HLQ of the provided name if it is not surrounded by quotes.
    • Open a temporary data set by providing the sequence //&& followed by a valid qualifier.
      • Example: "//&&MYTMP"
      • The supported data set types are regular sequential and partitioned data sets.
  • mode (str) - The file mode specifies the type of access requested for the file. Choices are as follows:

    • 'r' - Open the file for reading. The file must exist.
    • 'w' - Open the file for writing. If the file already exists, its contents are destroyed.
    • 'a' - Open the file for writing and append content to the end of the file. The file is created if it does not exist.
    • 'b' - Binary mode, (implicit when using a record access model)
    • '+' - Open the file for updating (reading and writing)

Other parameters

  • noseek (bool) - Indicates that the stream may not use repositioning functions.
    • If true the system will try to open the file in QSAM (queued sequential access method). This access method generally provides the best performance.
    • If the parameter is omitted or false, the access method will be BSAM (basic sequential access method).

Class members

  • closed (bool) - True if the file is closed.

  • openmode (str) - File open mode.

  • device (str) - Device type.

  • access_method (str) - Identifies the access method used for the data set. Valid only for dsorg PS or PO.

  • noseek_to_seek (str) - Identifies the reason noseek was changed to seek. Valid only for dsorg PS or PO.

  • recfm (str) - Data set record format.

  • dsorg (str) - Data set organization.

  • dsname (str) - For DASD datasets identifies the real name of the data set.

  • maxreclen (int) - Maximum record length of the data set.

  • blksize (int) - Data set block size.

Class methods

  • clearerr() (None)
    • Resets the error indicator and EOF indicator of the file stream.

  • close() (None)
    • Flush and close the file stream IO object.
      • This method has no effect if the file is already closed.

  • flush() (None)
    • Flushes the file stream
      • This function has no effect for blocked I/O files.

  • readable() (bool)
    • Returns whether file stream was opened for reading.

  • read(size=1, count=LRECL, /) (bytes)
    • Reads up to count items of size length from the record stream.
    • Each time this method is called, only one record is read, with a request for less than a complete record, the requested bytes are returned and the file position of the stream is set to the start of the next record.
    • If the request is for more bytes than are in the record, one record is read and the position is set to the start of the next record.
    • If the request is for 0 total bytes, the state of the stream remains unchanged.
    • A failed read operation may lead to undefined behavior, so the stream needs to be repositioned with a call to seek or rewind.
    • Parameters
      • size (int) = 1
        • Size in bytes of each item to read.
      • count (int) = LRECL
        • Number of items to read.
    • Returns
      • bytes - The bytes read from the request, empty bytes object if reading past EOF.
    • Notes
      • There must be a intervening flush or reposition operation between a read call after a write operation.
      • A failed read operation will result on an undefined file position indicator.
      • Reading past the end of the file stream will return an empty bytes object.

  • readrecord() (bytes)
    • Read a record from the record stream.
    • Returns
      • bytes - The content of the record, an empty bytes object if reading past EOF.
    • Notes
      • There must be a intervening flush or reposition operation between a readrecord call after a write operation.
      • A failed read operation will result on an undefined file position indicator.
      • Reading past the end of the file stream will return an empty bytes object.

  • readrecords(nrecords=ALL, /) ([bytes])
    • Reads an amount of records from the current position of the record stream.
    • Parameters
      • nrecords (int)
        • Amount of records to read from the record stream. If no amount is specified the request will be for reading until the EOF.
    • Returns
      • list - A list of bytes objects with the contents of the read request. An empty list if the call is done after the EOF.
    • Notes
      • There must be a intervening flush or reposition operation between a readrecords call after a write operation.
      • A failed read operation will result on an undefined file position indicator.

  • rewind() (None)
    • Repositions the file position indicator of the file stream.
      • A call to rewind is equivalent to a call of seek() to the beginning of the file except that rewind() also clears the error indicator of the stream.

  • seek (offset=0, origin=zoau_io.SEEK_SET, /) (None)
    • Changes the current file position associated with the record stream to a new record location within the file. The next operation on the stream will take place at the new location. On a stream opened for update, the next operation can be either a reading or writing operation
    • Parameters
      • offset (int)
        • Relative record number offset
      • origin (int)
        • Must be one of the following constants included in the module:
          • SEEK_SET (0) : Begining of the file
          • SEEK_CUR (1) : Current position
          • SEEK_END (2) : End of the file
    • Examples
      • seek(-2, zoau_io.SEEK_CUR) seeks backward two records from the current position.
      • seek(55, zoau_io.SEEK_SET) seeks to relative record 55.
    • Notes
      • Opening the record stream with the noseek parameter set disables this method.
      • An implicit flush of records to the system is done with reposition operations.
      • This method is valid for all types of files except for:
        • Files on nonseekable devices.
        • Partitioned data sets opened in write mode.
        • You cannot seek past the end or before the beginning of a file.
        • A failed seek operation may lead to undefined behavior, so the stream error indicator needs to be reset with a call to clearerr() or rewind() in that case.

  • seekable() (bool)
    • Return whether file stream supports random access.

  • tell() (int)
    • Returns the relative record offset of the current position from the beginning of the record stream. The first record of a file is relative record 0.
    • Returns
      • int - Relative record number of the current position.
    • Notes
      • All offset values are given in terms of records.
      • Opening the record stream with the noseek parameter set disables this method.

  • writable() (bool)
    • Return whether file stream was opened for writing.


class zoautil_py.zoau_io.RecordIO_TextWrapper(record_stream, encoding, /)


Description

  • Opens a text based layer over a record stream object, providing a decode/encode step before read/write operations of the stream.

Parameters

  • record_stream - (RecordIO)
    • The RecordIO instance to be transformed.
  • encoding - str
    • Gives the name of the encoding that the stream will be decoded or encoded with.

Notes

  • This wrapper currently supports only single byte character set encodings from the EBCDIC package.

Class members

  • record_stream - (RecordIO)
    • The underlying record stream object.

Class methods

  • clearerr() (None)
    • Resets the error and EOF indicators of the underlying record stream object.

  • close() (None)
    • Closes the underlying record stream object. This method has no effect if the file is already closed.

  • detach() (RecordIO)
    • Detaches and returns the underlying record stream object.
    • Returns
      • RecordIO : the underlying record stream object.

  • flush() (None)
    • Flushes the underlying record stream object.

  • read(nchars=LRECL, /) (str)
    • Reads up to nchars characters from the underlying record stream object.
    • Each time this method is called, only one record is read, with a request for less than a complete record, the requested string is returned and the file position of the stream is set to the start of the next record.
    • If the requested character count exceeds the record length, one record is read and the position is set to the start of the next record.
    • If the request is for 0 characters, the state of the stream remains unchanged.
    • A failed read operation may lead to undefined behaviour, so the stream needs to be repositioned with a call to seek or rewind.
    • Parameters
      • nchars (int) = LRECL
        • Character count to be read.
    • Returns
      • str - Output string from the read operation. Returns an empty string past EOF.
    • Notes
      • There must be a intervening flush or reposition operation between a read call after a write operation.
      • A failed read operation will result on an undefined file position indicator.
      • Reading past the end of the file stream will return an empty string.

  • readable() (bool)
    • Returns whether the underlying record stream object supports reading operations.

  • readrecord() (str)
    • Read a record from the underlying record stream object.
    • Returns
      • str - The content of the record, an empty string if reading past EOF.
    • Notes
      • There must be a intervening flush or reposition operation between a readrecord call after a write operation.
      • A failed read operation will result on an undefined file position indicator.
      • Reading past the end of the file stream will return an empty string.

  • readrecords(nrecords=ALL, /) (str)
    • Reads an amount of records from the current position of the underlying record stream object.
    • Parameters
      • nrecords (int)
        • Amount of records to read from the record stream.
        • If no amount is specified the request will be for reading until the EOF.
    • Returns
      • list - A list of strings with the contents of the read request. An empty list if the call is done after the EOF.
    • Notes
      • There must be a intervening flush or reposition operation between a readrecords call after a write operation.
      • A failed read operation will result on an undefined file position indicator.

  • rewind() (None)
    • Repositions the file position indicator of the underlying record stream. A call to rewind is equivalent to a call of seek() to the beginning of the file except that rewind() also clears the error indicator of the stream.

  • seek (offset=0, origin=zoau_io.SEEK_SET, /) (None)
    • Changes the current file position associated with the underlying record stream to a new record location within the file. The next operation on the stream will take place at the new location. On a stream opened for update, the next operation can be either a reading or writing operation.
    • Parameters
      • offset (int) - Relative record number offset.
      • origin (int) - Must be one of the following constants included in the module:
        • SEEK_SET (0) : Begining of the file
        • SEEK_CUR (1) : Current position
        • SEEK_END (2) : End of the file
    • Examples
      • seek(-2, zoau_io.SEEK_CUR) seeks backward two records from the current position.
      • seek(55, zoau_io.SEEK_SET) seeks to relative record 55.
    • Notes
      • Opening the record stream with the noseek parameter set disables this method.
      • An implicit flush of records to the system is done with reposition operations.
      • This method is valid for all types of files except for:
        • Files on nonseekable devices
        • Partitioned data sets opened in write mode
      • You cannot seek past the end or before the beginning of a file.
      • A failed seek operation may lead to undefined behavior, so the stream error indicator needs to be reset with a call to clearerr() or rewind() in that case.

  • seekable() (bool)
    • Returns whether the underlying record stream object supports repositioning operations.

  • tell() (int)
    • The relative record offset of the current position from the beginning of the underlying record stream object. The first record of a file is relative record 0.
    • Returns
      • int - Relative record number of the current position.
    • Notes
      • All offset values are given in terms of records.
      • Opening the record stream with the noseek parameter set disables this method.

  • writable() (bool)
    • Returns whether the underlying record stream object supports writing operations.