Cookbook
========

Open and extract (unload) XMI/AWS/HET mainframe files.

The most simple way to use this library is to import this module and use
``xmi.open_file()`` to open an XMI, AWS, or HET file::

    import xmi
    xmi_obj = xmi.open_file("/path/to/file.xmi")
    het_obj = xmi.open_file("/path/to/file.het")
    aws_obj = xmi.open_file("/path/to/file.aws")

To list all datasets and dataset members::

    for f in het_obj.get_files():
        if het_obj.is_pds(f):
            for m in het_obj.get_members(f):
                print("{}({})".format(f, m))
        else:
            print(f)

Print JSON metatdata::

    print(xmi_obj.get_json())
    print(het_obj.get_json(text=True)) # Adds plaintext files to json output
    print(aws_obj.get_json(indent=6)) # Increases the json indent

Silently extract all files/folders to ``/tmp/xmi_files/``::

    aws_obj.set_output_folder("/tmp/xmi_files/")
    aws_obj.set_quiet(True)
    aws_obj.extract_all()

Print detailed file information::

    xmi_obj.print_details()
    xmi_obj.print_xmit()  # Same output as previous, print_xmit() is an alias to print_details()
    het_obj.print_tape()  # print_tape() is an alias to print_details()
    aws_obj.print_tape(human=True)  # Converts size to human readable

Print message::

    if xmi_obj.has_message():
        print(xmi_obj.get_message())

or just::

    print(xmi_obj.get_message())  # Prints 'None' if no message

Creating XMI mainframe files (datasets)::

    from xmi import create_xmi 

    create_xmi(
        '/path/to/file/or/folder',
        output_file='/path/to/your/XMI',
        dsn='MY.DS',
        from_user='DADE',
        from_node='PYTHON'
    )


Creating an XMI with an embedded message (displayed on the z/OS terminal on ``RECEIVE``)::

    create_xmi(
        '/path/to/file/or/folder',
        output_file='/path/to/your/XMI',
        dsn='MY.DS',
        message='Hello from Python!\nSee release notes inside.',
    )

``message_format`` controls the terminal width and maximum line count.
The default is ``'80x32'`` (80 columns, 32 lines — suits a standard Model 3/4
terminal).  Use ``'132x27'`` for wide terminals (Model 5, 132 columns, 27 lines)::

    create_xmi(
        '/path/to/file/or/folder',
        output_file='/path/to/your/XMI',
        dsn='MY.DS',
        message='Wide banner line spanning 132 columns.',
        message_format='132x27',
    )

Lines longer than the column limit are silently truncated; messages longer than
the line limit are also truncated — both emit a warning to stderr.

The message can also be read from a UTF-8 text file — useful for multi-line
banners::

    create_xmi(
        '/path/to/file/or/folder',
        output_file='/path/to/your/XMI',
        dsn='MY.DS',
        message_file='/path/to/banner.txt',
        # message_format defaults to '80x32'; pass '132x27' for wide terminals
    )

This will create a XMI file at `/path/to/your/XMI` that is 'receivable' on z/OS.
If the `/path/to/file/or/folder`  is a folder it will be stored in the XMI as 
as PDS named `MY.DS`. If it's a single file it will be stored in the XMI as
a sequential file called `MY.DS`. If you omit the `dsn` the datasetname 
inside the XMIT will be `folder` (last part of input) in UPPERCASE.

If you you're having problems with the library or want to see whats happening
behind the scenes you can enable debugging::

    import logging
    import xmi

    xmi_obj = xmi.XMIT(filename="/path/to/file.xmi",loglevel=logging.DEBUG)
    xmi_obj.open()

As you can see, using this library is fairly easy.

Command-line tools
==================

After installation two commands are available from the terminal.

``extractxmi`` — open, list, and extract XMI / AWS / HET files
---------------------------------------------------------------

.. code-block:: bash

    # List all datasets and members
    extractxmi -l FILE.XMI

    # Extract everything to the current directory
    extractxmi FILE.XMI

    # Extract a single PDS member
    extractxmi FILE.XMI "MY.PDS(MEMBER)"

    # Print detailed metadata
    extractxmi -pH FILE.XMI

    # Extract to a specific folder
    extractxmi FILE.XMI --outputdir /tmp/out/

    # Print the embedded message (if any)
    extractxmi --message FILE.XMI

    # Full option list
    extractxmi --help

``createxmi`` — create an XMI file from a local file or folder
--------------------------------------------------------------

.. code-block:: bash

    # Package a folder as a PDS (dataset name defaults to folder name)
    createxmi myfolder/

    # Specify output path and dataset name
    createxmi myfolder/ -o MY.XMI --dsn MY.PDS

    # Set originating user (appears in ISPF statistics on z/OS)
    createxmi myfolder/ -o MY.XMI --dsn MY.PDS --from-user IBMUSER

    # Package a single file as a sequential dataset
    createxmi myfile.jcl -o SEQ.XMI --dsn MY.SEQ

    # Package XMI files inside a PDS (auto-detects binary, uses RECFM=U)
    createxmi xmi_folder/ -o MULTI.XMI --dsn MULTI.PDS

    # Embed a message displayed on z/OS RECEIVE (use \n for line breaks)
    createxmi myfile.jcl -o SEQ.XMI --message "Hello from Python!\nSee release notes inside."

    # Read message from a file (useful for banners or EBCDIC art)
    createxmi myfile.jcl -o SEQ.XMI --message-file banner.txt

    # Wide terminal format (132 columns, Model 5)
    createxmi myfile.jcl -o SEQ.XMI --message-file banner-132.txt --message-format 132x27

    # Full option list
    createxmi --help