Developer Guide¶

This comprehensive guide helps developers quickly find and understand the right resources for working with Pure3270 and TN3270 protocols.

Documentation Structure¶

Getting Started¶

Installation - Setting up Pure3270 environment
Usage - Basic usage patterns and concepts
Examples - Common usage examples and code samples
Configurable Terminal Models - Available terminal models and specifications

Protocol & Deep Technical Content¶

Protocol Examples - NEW: Comprehensive TN3270/TN3270E protocol examples * Basic connection flows with step-by-step examples * TN3270E negotiation with detailed explanations * Data stream parsing examples * Screen buffer manipulation examples * Field attribute handling examples * Protocol error handling examples * Connection recovery examples
Advanced Patterns - NEW: Advanced usage patterns and optimization * Complex session management patterns * Error handling and recovery strategies * Performance optimization techniques * Custom protocol extensions * Testing strategies for protocol implementations
pure3270.protocol Module - Low-level protocol implementation details * IND$FILE file transfer protocol * Protocol utility functions * Data stream handling

Reference Documentation¶

API Reference - Complete API reference with all modules and classes
pure3270.session Module - Session management and lifecycle
pure3270.emulation Module - Screen buffer and terminal emulation
pure3270.patching Module - Patching and compatibility features
Configurable Terminal Models - Terminal model specifications
Advanced Usage - Advanced features (printer sessions, etc.)
<no title> - Warning system and categorization

Learning Path by Use Case¶

For Application Developers¶

Basic Integration → Installation → Usage → Examples
API Compatibility → Usage (P3270Client section) → Examples
Terminal Configuration → Configurable Terminal Models → Usage
Basic Error Handling → Examples → Advanced Usage (Error Handling section)

For Protocol Engineers¶

Protocol Fundamentals → Protocol Examples (Basic Connection Flow)
TN3270E Features → Protocol Examples (TN3270E Negotiation)
Data Stream Processing → Protocol Examples (Data Stream Parsing)
Error Recovery → Protocol Examples (Error Handling)
Protocol Implementation → pure3270.protocol Module → Advanced Patterns

For Enterprise Architects¶

System Integration → Integration Scenarios (Enterprise Integration)
High Availability → Integration Scenarios (Multi-Session Management)
Printer Management → Integration Scenarios (Printer Emulation)
Network Resilience → Integration Scenarios (Network Resilience)
Production Deployment → Integration Scenarios (Production Deployment)
MCP Integration → Integration Scenarios (MCP Server Integration)

For Performance Engineers¶

Session Management → Advanced Patterns (Session Management)
Performance Optimization → Advanced Patterns (Performance Optimization)
Resource Management → Advanced Patterns (Memory Optimization)
Monitoring Integration → Integration Scenarios (Production Monitoring)

For Security Engineers¶

Connection Security → Usage (SSL/TLS Configuration)
Authentication → Integration Scenarios (Enterprise Authentication)
Network Security → Integration Scenarios (Network Resilience)
Compliance → Integration Scenarios (Production Security)

Example Code Organization¶

The examples directory contains organized code samples:

Core Examples (`examples/`)¶

example_standalone.py - Basic standalone usage
example_advanced_screen_operations.py - Advanced screen manipulation
example_error_handling.py - Error handling patterns
example_protocol_operations.py - Protocol-level operations
example_end_to_end.py - Complete workflow examples

Real-World Examples (`examples/`)¶

example_pub400*.py - Real mainframe interactions
example_printer_session.py - Printer session management
example_terminal_models.py - Terminal model configurations

Development and Testing Examples (`examples/`)¶

trace_*.py - Protocol tracing and debugging
integration_test.py - Integration testing patterns
batch_*.py - Performance and batch testing

Protocol Implementation Examples¶

Connection Flows: Protocol Examples - Basic TN3270 Connection Flow
Negotiation: Protocol Examples - TN3270E Negotiation Details
Data Processing: Protocol Examples - Data Stream Parsing Examples
Error Recovery: Protocol Examples - Protocol Error Handling
Session Management: Advanced Patterns - Complex Session Management

Enterprise Integration Examples¶

Banking Systems: Integration Scenarios - Bank Processing System
Multi-Session: Integration Scenarios - Enterprise Session Management
Printer Management: Integration Scenarios - Enterprise Printer Management
MCP Integration: Integration Scenarios - AI-Integrated Terminals
Network Resilience: Integration Scenarios - Mission-Critical Environments
Production: Integration Scenarios - Enterprise Production Deployment

Common Development Tasks¶

Creating a New Session¶

from pure3270 import AsyncSession

async def create_session():
    async with AsyncSession() as session:
        await session.connect('mainframe.example.com')
        # Session ready for use

See: Usage, Examples

Handling Protocol Errors¶

import asyncio
from pure3270.exceptions import ConnectionError

async def robust_connection():
    for attempt in range(3):
        try:
            session = AsyncSession()
            await session.connect('mainframe.example.com')
            return session
        except ConnectionError:
            await asyncio.sleep(1)
    raise ConnectionError("Failed to connect")

See: Protocol Examples (Protocol Error Handling Examples), Advanced Patterns

Implementing File Transfer¶

async def transfer_file():
    async with AsyncSession() as session:
        await session.connect('mainframe.example.com')
        await session.send_file('local.txt', 'remote.txt')
        await session.receive_file('remote.txt', 'local_copy.txt')

See: pure3270.protocol Module (IND$FILE Protocol), Examples

Managing Multiple Sessions¶

async def multi_session_example():
    sessions = []
    for i in range(5):
        session = AsyncSession()
        await session.connect(f'mainframe{i}.example.com')
        sessions.append(session)

    # Use sessions...
    for session in sessions:
        await session.close()

See: Integration Scenarios (Multi-Session Management), Advanced Patterns

Performance Optimization¶

import asyncio
from pure3270 import AsyncSession

async def batch_operations():
    async with AsyncSession() as session:
        await session.connect('mainframe.example.com')

        # Batch operations for performance
        await session.string("DATA1")
        await session.key("ENTER")
        await session.key("TAB")
        await session.string("DATA2")
        await session.key("ENTER")

See: Advanced Patterns (Performance Optimization)

Troubleshooting Guide¶

Common Issues and Solutions¶

Connection Timeout

Problem: Connections timing out
Solution: Increase timeout values, check network connectivity
See: Protocol Examples (Connection Recovery Examples)

Screen Parsing Errors

Problem: Cannot parse screen data correctly
Solution: Use proper EBCDIC/ASCII conversion, check field attributes
See: Protocol Examples (Data Stream Parsing Examples)

Performance Issues

Problem: Slow operation response times
Solution: Implement connection pooling, optimize data handling
See: Advanced Patterns (Performance Optimization)

Memory Usage

Problem: High memory consumption
Solution: Implement proper session cleanup, buffer management
See: Advanced Patterns (Memory Optimization)

Debugging Tools¶

Protocol Tracing¶

Enable detailed protocol logging:

from pure3270 import setup_logging

setup_logging(level="DEBUG", component="tn3270")

Screen State Analysis¶

Analyze current screen state:

screen_text = session.ascii(session.read())
print("Screen content:", screen_text)

# Analyze fields
fields = session.screen_buffer.get_fields()
for field in fields:
    print(f"Field at {field.position}: {field.attribute}")

See: Examples (example_trace.py), Examples (example_advanced_screen_operations.py)

Integration Checkpoints¶

Before Production Deployment¶

✓ Security Review

SSL/TLS configuration validated
Authentication mechanisms tested
Network security measures implemented

✓ Performance Testing

Load testing completed
Response time benchmarks met
Resource usage optimized

✓ Reliability Testing

Connection recovery tested
Failover mechanisms verified
Error handling validated

✓ Monitoring Setup

Metrics collection configured
Alerting rules defined
Performance baselines established

See: Integration Scenarios (Production Deployment)

Code Quality Guidelines¶

For Pure3270 Development¶

Follow CONTRIBUTING guidelines
Ensure all code passes linting: python -m flake8 pure3270/
Run type checking: python -m mypy pure3270/
Format code: python -m black pure3270/
Run tests: python -m pytest tests/

For Documentation Contributions¶

Update relevant documentation sections
Add examples for new features
Ensure code examples are tested
Update this guide if adding new sections

Best Practices Summary¶

Always use context managers for session lifecycle
Implement proper error handling with recovery strategies
Use connection pooling for production environments
Enable detailed logging for troubleshooting
Test with real mainframe systems when possible
Follow RFC specifications for protocol implementation
Use proper EBCDIC/ASCII conversion functions
Implement resource cleanup in finally blocks

Additional Resources¶

External References¶

RFC 854 - Telnet Protocol Specification
RFC 1576 - TN3270 Current Practices
RFC 1646 - TN3270 Extensions for LUname and-printer Session
IBM 3270 Information Display System: Data Stream Programmer’s Reference

Community and Support¶

GitHub Issues - Bug reports and feature requests
GitHub Discussions - Community support and questions
Code Examples - Additional examples in the repository

Version History¶

v3.0 - Major protocol examples and advanced patterns added
v2.0 - Enhanced enterprise integration features
v1.0 - Initial release with basic TN3270 support

This developer guide provides a comprehensive navigation framework for the enhanced Pure3270 documentation. Use the cross-references to find specific information quickly and efficiently.