From c2f88be4fff3b6e43a75262c84188bcd2ea3cbcc Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 21 Jan 2026 23:39:34 +0000 Subject: [PATCH 1/2] Initial plan From f0e035bdb3bce0f8b933e7fc52a2f5cc2cbd782d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 21 Jan 2026 23:46:07 +0000 Subject: [PATCH 2/2] Add comprehensive analysis reports for QCBLLESRC COBOL programs Co-authored-by: raykao <860691+raykao@users.noreply.github.com> --- .../COBOL_examples/Holidays/QCBLLESRC/PRD.md | 641 ++++++++++++++++ .../QCBLLESRC/cobol_analyzer_report.md | 718 ++++++++++++++++++ .../QCBLLESRC/cobol_dependency_report.md | 469 ++++++++++++ 3 files changed, 1828 insertions(+) create mode 100644 AS400/COBOL_examples/Holidays/QCBLLESRC/PRD.md create mode 100644 AS400/COBOL_examples/Holidays/QCBLLESRC/cobol_analyzer_report.md create mode 100644 AS400/COBOL_examples/Holidays/QCBLLESRC/cobol_dependency_report.md diff --git a/AS400/COBOL_examples/Holidays/QCBLLESRC/PRD.md b/AS400/COBOL_examples/Holidays/QCBLLESRC/PRD.md new file mode 100644 index 0000000..cda6703 --- /dev/null +++ b/AS400/COBOL_examples/Holidays/QCBLLESRC/PRD.md @@ -0,0 +1,641 @@ +# Product Requirements Document (PRD) + +## Title +**Holiday Day-of-Week Calculator - Canada Day Edition** + +--- + +## Introduction + +The Holiday Day-of-Week Calculator is a specialized computational utility designed to determine which day of the week a specific holiday falls on for any given year. This initial version focuses on Canada Day (July 1st) and provides both an interactive user interface for individual queries and an automated testing framework to ensure accuracy. + +The system is designed to support historical research, event planning, workforce scheduling, and any application requiring advance knowledge of holiday dates. The solution provides accurate day-of-week calculations for a wide temporal range (1600-3000) using industry-standard date calculation algorithms. + +--- + +## Problem Statement + +Organizations, event planners, HR departments, and government agencies frequently need to determine when national holidays fall within specific years to: + +1. **Plan Events and Celebrations**: Knowing whether a holiday falls on a weekend or weekday affects venue bookings, attendance projections, and resource allocation. + +2. **Schedule Workforce**: HR departments need to plan long weekends, shift schedules, and coverage well in advance when holidays fall on specific weekdays. + +3. **Financial Planning**: Retail, hospitality, and service industries require advance knowledge of holiday timing for budgeting and inventory management. + +4. **Historical Research**: Researchers need to accurately reconstruct calendars for historical analysis and documentation. + +5. **Compliance**: Government and regulated industries must ensure accurate holiday observance across multi-year planning horizons. + +**Current Challenge**: Manual calendar consultation is time-consuming and error-prone, especially for distant past or future dates. Existing calendar applications often lack the ability to quickly query specific holidays across multiple years or provide contextual information about holiday timing. + +--- + +## Objectives + +### Primary Objectives + +1. **Accuracy**: Provide mathematically correct day-of-week calculations for Canada Day (July 1st) for any year within the supported range (1600-3000). + +2. **Usability**: Enable non-technical users to quickly and easily determine holiday day-of-week information through an intuitive interface. + +3. **Performance**: Deliver instant results with minimal computational overhead, supporting both interactive and batch processing modes. + +4. **Extensibility**: Design the system architecture to support additional holidays and calendar systems in future releases. + +### Secondary Objectives + +5. **Educational Value**: Provide contextual information about holiday timing (e.g., weekend vs. weekday implications) to support decision-making. + +6. **Quality Assurance**: Include comprehensive automated testing capabilities to ensure ongoing accuracy. + +7. **Portability**: Maintain platform independence to support deployment across various operating systems and environments. + +--- + +## Requirements + +### Functional Requirements + +#### FR1: Date Calculation Engine +- **FR1.1**: System shall calculate the day of the week for July 1st of any year between 1600 and 3000 (inclusive). +- **FR1.2**: System shall use a mathematically proven algorithm (e.g., Zeller's Congruence, integer-based date functions) to ensure accuracy. +- **FR1.3**: System shall correctly handle leap years and century transitions in calculations. +- **FR1.4**: System shall return day names in English: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday. + +#### FR2: Interactive User Interface +- **FR2.1**: System shall provide a console-based or GUI interface for user interaction. +- **FR2.2**: System shall prompt users to enter a year value. +- **FR2.3**: System shall validate user input and reject values outside the range 1600-3000. +- **FR2.4**: System shall display clear error messages for invalid input. +- **FR2.5**: System shall allow users to perform multiple queries in a single session. +- **FR2.6**: System shall provide an option to exit the application gracefully. + +#### FR3: Result Presentation +- **FR3.1**: System shall display results in a clear, formatted output including: + - The holiday name (Canada Day) + - The date (July 1) + - The year queried + - The day of the week +- **FR3.2**: System shall provide contextual information about the result: + - Whether the holiday falls on a weekend or weekday + - Special messaging for specific days (Monday, Friday) that affect long weekends +- **FR3.3**: System shall format output for readability with appropriate spacing and visual separators. + +#### FR4: Automated Testing Framework +- **FR4.1**: System shall include a test harness capable of running multiple test cases. +- **FR4.2**: Test framework shall support predefined test years including: + - Recent years (e.g., 2024, 2025, 2026) + - Historical significant years (e.g., 1867 - Canadian Confederation) + - Future years for long-term planning (e.g., 2030) +- **FR4.3**: Test framework shall invoke the calculation engine programmatically (batch mode). +- **FR4.4**: Test framework shall validate results against expected outcomes. +- **FR4.5**: Test framework shall report test success/failure status. + +#### FR5: Input Validation +- **FR5.1**: System shall validate year input is numeric. +- **FR5.2**: System shall validate year is within supported range (1600-3000). +- **FR5.3**: System shall provide specific error messages for different validation failures. +- **FR5.4**: System shall allow users to retry after invalid input without restarting the application. + +### Non-Functional Requirements + +#### NFR1: Performance +- **NFR1.1**: Day-of-week calculation shall complete in less than 100 milliseconds on standard hardware. +- **NFR1.2**: System shall support batch processing of at least 100 years per second. +- **NFR1.3**: Interactive response time (from input to display) shall not exceed 500 milliseconds. + +#### NFR2: Reliability +- **NFR2.1**: System shall provide 100% accurate results for all dates within the supported range. +- **NFR2.2**: System shall handle edge cases correctly: + - Leap years (divisible by 4, except century years not divisible by 400) + - Century boundaries (1700, 1800, 1900, 2000, 2100, etc.) + - Minimum boundary (year 1600) + - Maximum boundary (year 3000) +- **NFR2.3**: System shall not crash or terminate abnormally for any valid input. + +#### NFR3: Usability +- **NFR3.1**: User interface shall be intuitive enough for first-time users without training. +- **NFR3.2**: Error messages shall be clear and actionable. +- **NFR3.3**: Output shall be readable by non-technical users. +- **NFR3.4**: System shall provide helpful prompts and instructions throughout user interaction. + +#### NFR4: Maintainability +- **NFR4.1**: Code shall be modular with clear separation of concerns: + - Input handling module + - Calculation engine module + - Output formatting module + - Testing framework module +- **NFR4.2**: Calculation algorithm shall be documented with references to mathematical basis. +- **NFR4.3**: System shall use standard libraries and functions where possible. +- **NFR4.4**: Code shall include comments explaining business logic and complex calculations. + +#### NFR5: Portability +- **NFR5.1**: System shall avoid platform-specific dependencies where possible. +- **NFR5.2**: Date calculation shall not rely on system clock or locale settings. +- **NFR5.3**: System shall be implementable in multiple programming languages without algorithm changes. + +#### NFR6: Extensibility +- **NFR6.1**: Architecture shall support addition of new holidays without modifying core calculation engine. +- **NFR6.2**: System shall support addition of new output formats (e.g., JSON, XML, CSV). +- **NFR6.3**: Design shall accommodate future internationalization requirements (multiple languages). + +#### NFR7: Security +- **NFR7.1**: System shall not store sensitive user information. +- **NFR7.2**: System shall validate all input to prevent injection attacks or buffer overflows. +- **NFR7.3**: System shall handle unexpected input gracefully without exposing system internals. + +--- + +## User Stories + +### Epic 1: Individual Date Queries + +**US1.1: As an event planner, I want to check what day Canada Day falls on in 2026, so I can book venues and plan celebrations accordingly.** + +- **Acceptance Criteria**: + - Given I launch the application + - When I enter the year 2026 + - Then the system displays "Canada Day (July 1, 2026) falls on a Wednesday" + - And provides contextual information about weekday implications + +**US1.2: As a historical researcher, I want to determine what day Canada Day fell on during the year of Confederation (1867), so I can accurately document the first Canada Day observance.** + +- **Acceptance Criteria**: + - Given I am using the application + - When I enter the year 1867 + - Then the system correctly calculates and displays the day of the week for July 1, 1867 + - And the result is historically accurate + +**US1.3: As an HR manager, I want to check multiple years in one session, so I can plan long-term workforce schedules efficiently.** + +- **Acceptance Criteria**: + - Given I have completed a query for one year + - When I choose to continue + - Then the system prompts me for another year without restarting + - And I can repeat this process as many times as needed + +### Epic 2: Input Validation and Error Handling + +**US2.1: As a user, I want to receive clear error messages when I enter an invalid year, so I understand what went wrong and how to correct it.** + +- **Acceptance Criteria**: + - Given I enter a year less than 1600 or greater than 3000 + - When the system validates my input + - Then I see an error message: "Error: Please enter a year between 1600 and 3000" + - And I am prompted to enter a new year without restarting + +**US2.2: As a user, I want the system to prevent me from entering non-numeric values, so I don't receive unexpected errors.** + +- **Acceptance Criteria**: + - Given I enter non-numeric characters + - When the system processes my input + - Then I receive an appropriate error message + - And the system remains stable and operational + +### Epic 3: Contextual Information + +**US3.1: As an event coordinator, I want to know if Canada Day falls on a weekend, so I can adjust my planning for higher attendance.** + +- **Acceptance Criteria**: + - Given Canada Day falls on Saturday or Sunday + - When I query that year + - Then the system displays "Canada Day is on a weekend! Perfect for celebrations!" + - And I can use this information for event planning + +**US3.2: As a business owner, I want to know if Canada Day falls on a Monday or Friday, so I can plan for extended long weekends.** + +- **Acceptance Criteria**: + - Given Canada Day falls on Monday + - When I query that year + - Then the system displays "Great way to start the week with a holiday!" + - And I understand the long weekend implications + +### Epic 4: Automated Testing and Quality Assurance + +**US4.1: As a QA engineer, I want to run automated tests against multiple years, so I can verify the system's accuracy without manual testing.** + +- **Acceptance Criteria**: + - Given I run the test framework + - When it processes the predefined test cases (2024, 2025, 2026, 1867, 2030) + - Then each test executes successfully + - And I receive a summary of test results + +**US4.2: As a developer, I want the test framework to validate results against known correct answers, so I can detect regressions quickly.** + +- **Acceptance Criteria**: + - Given the test framework has expected results defined + - When it runs calculations + - Then it compares actual results to expected results + - And reports any discrepancies clearly + +### Epic 5: System Usability + +**US5.1: As a first-time user, I want clear instructions and prompts, so I can use the system without referring to documentation.** + +- **Acceptance Criteria**: + - Given I launch the application for the first time + - When the application starts + - Then I see a clear title and purpose statement + - And prompts that explain what input is expected + +**US5.2: As a user, I want a clean and organized output format, so I can easily read and understand the results.** + +- **Acceptance Criteria**: + - Given I receive results from a query + - When the system displays output + - Then information is formatted with visual separators + - And key information is highlighted or clearly labeled + +--- + +## Acceptance Criteria + +### System-Level Acceptance Criteria + +#### AC1: Calculation Accuracy +- **AC1.1**: System correctly calculates day-of-week for all years 1600-3000 (verified through known historical dates and astronomical references). +- **AC1.2**: System produces identical results to verified calendar systems (e.g., perpetual calendar algorithms, astronomical databases). +- **AC1.3**: System correctly handles leap year calculations: + - Years divisible by 4 are leap years + - Exception: Years divisible by 100 are not leap years + - Exception to exception: Years divisible by 400 are leap years +- **AC1.4**: Test cases for years 1600, 1700, 1800, 1900, 2000, 2100, 2400 pass with correct leap year handling. + +#### AC2: Input Validation +- **AC2.1**: System rejects year < 1600 with error message. +- **AC2.2**: System rejects year > 3000 with error message. +- **AC2.3**: System handles non-numeric input gracefully without crashing. +- **AC2.4**: System allows retry after invalid input. +- **AC2.5**: Error messages are displayed clearly and guide user to correct input. + +#### AC3: User Interface +- **AC3.1**: Application displays title and purpose on startup. +- **AC3.2**: Application prompts user clearly for year input. +- **AC3.3**: Application displays results in formatted, readable manner. +- **AC3.4**: Application provides option to continue or exit after each query. +- **AC3.5**: Application handles both uppercase and lowercase for continue/exit responses (Y/y/N/n). +- **AC3.6**: Application displays exit message when user chooses to quit. + +#### AC4: Output Content +- **AC4.1**: Output includes holiday name (Canada Day). +- **AC4.2**: Output includes full date (July 1, YYYY). +- **AC4.3**: Output includes calculated day of the week. +- **AC4.4**: Output includes contextual "Fun Facts" based on day of week: + - Weekend message for Saturday/Sunday + - Weekday long weekend message for Monday-Friday + - Special Monday message + - Special Friday message + +#### AC5: Testing Framework +- **AC5.1**: Test framework executes without manual intervention. +- **AC5.2**: Test framework processes all predefined test years (2024, 2025, 2026, 1867, 2030). +- **AC5.3**: Test framework invokes calculation engine correctly for each test case. +- **AC5.4**: Test framework validates results against expected values. +- **AC5.5**: Test framework reports pass/fail status for each test. +- **AC5.6**: Test framework provides summary upon completion. + +#### AC6: Performance +- **AC6.1**: Single calculation completes in < 100ms. +- **AC6.2**: Interactive response (input to output) completes in < 500ms. +- **AC6.3**: Batch processing of 100 years completes in < 1 second. +- **AC6.4**: System remains responsive during all operations. + +#### AC7: Reliability +- **AC7.1**: System does not crash for any valid input within range. +- **AC7.2**: System does not crash for invalid input. +- **AC7.3**: System produces consistent results across multiple runs with same input. +- **AC7.4**: System handles edge cases correctly: + - Year 1600 (minimum boundary) + - Year 3000 (maximum boundary) + - Century years (1700, 1800, 1900, 2000, 2100, etc.) + - Leap years and non-leap years + +#### AC8: Modularity (for developers) +- **AC8.1**: Input validation logic is separate from calculation logic. +- **AC8.2**: Calculation engine can be invoked programmatically (batch mode). +- **AC8.3**: Output formatting is separate from calculation logic. +- **AC8.4**: Test framework can invoke calculation engine without user interaction. +- **AC8.5**: Day-of-week lookup (numeric to name) is table-driven and easily modifiable. + +--- + +## Timeline + +### Phase 1: Core Development (Weeks 1-3) +**Deliverables:** +- Calculation engine implementation +- Input validation module +- Interactive user interface +- Basic output formatting + +**Milestones:** +- Week 1: Complete calculation algorithm and unit tests +- Week 2: Implement user interface and input validation +- Week 3: Integrate components and perform initial testing + +### Phase 2: Testing Framework (Weeks 4-5) +**Deliverables:** +- Automated test harness +- Predefined test cases +- Result validation logic +- Test reporting functionality + +**Milestones:** +- Week 4: Design and implement test framework architecture +- Week 5: Add test cases and validation, perform integration testing + +### Phase 3: Enhancement and Polish (Week 6) +**Deliverables:** +- Contextual output messages +- Enhanced error handling +- User experience improvements +- Documentation + +**Milestones:** +- Week 6 Day 1-2: Implement contextual messages and fun facts +- Week 6 Day 3-4: Enhance error messages and user guidance +- Week 6 Day 5: Complete documentation and user guide + +### Phase 4: Quality Assurance (Week 7) +**Deliverables:** +- Comprehensive test coverage +- Performance benchmarking +- Edge case validation +- Bug fixes + +**Milestones:** +- Week 7 Day 1-2: Execute full test suite and boundary testing +- Week 7 Day 3-4: Performance testing and optimization +- Week 7 Day 5: Final bug fixes and validation + +### Phase 5: Release Preparation (Week 8) +**Deliverables:** +- Final testing and validation +- Release documentation +- Deployment package +- User training materials + +**Milestones:** +- Week 8 Day 1-2: Final regression testing +- Week 8 Day 3-4: Documentation review and finalization +- Week 8 Day 5: Release approval and deployment + +**Total Duration:** 8 weeks from project kickoff to production release + +--- + +## Dependencies + +### Technical Dependencies + +#### TD1: Date Calculation Libraries +- **Dependency**: Standard library functions for date manipulation (e.g., intrinsic date functions, date conversion utilities) +- **Criticality**: HIGH +- **Mitigation**: If unavailable, implement custom algorithm based on Zeller's Congruence or similar proven method + +#### TD2: User Interface Framework +- **Dependency**: Console I/O capabilities or GUI framework (depending on platform) +- **Criticality**: MEDIUM +- **Mitigation**: System can be implemented as command-line tool, desktop application, or web service + +#### TD3: Testing Infrastructure +- **Dependency**: Unit testing framework or test runner +- **Criticality**: MEDIUM +- **Mitigation**: Can implement custom test harness if standard framework unavailable + +### Data Dependencies + +#### DD1: Day-of-Week Lookup Table +- **Dependency**: Accurate mapping of numeric day values (0-6 or 1-7) to day names +- **Criticality**: HIGH +- **Mitigation**: Table is defined within system; no external data source required + +#### DD2: Historical Calendar System +- **Dependency**: Gregorian calendar rules (used since October 1582 in Catholic countries) +- **Criticality**: HIGH +- **Mitigation**: Algorithm explicitly implements Gregorian calendar rules; documented assumption that all dates use Gregorian calendar + +### External Dependencies + +#### ED1: None Required for Core Functionality +- System is self-contained with no external service dependencies +- No database required +- No network connectivity required +- No external API calls required + +### Team Dependencies + +#### TM1: Development Team +- **Requirement**: 1 senior developer or 2 junior developers +- **Skills**: Proficiency in chosen implementation language, understanding of date algorithms +- **Duration**: Full 8-week timeline + +#### TM2: QA Team +- **Requirement**: 1 QA engineer +- **Skills**: Test automation, boundary testing, regression testing +- **Duration**: Weeks 4-8 (50% allocation) + +#### TM3: Technical Writer +- **Requirement**: 1 technical writer +- **Skills**: User documentation, API documentation +- **Duration**: Weeks 7-8 (25% allocation) + +--- + +## Risks + +### Technical Risks + +#### TR1: Date Algorithm Accuracy +- **Risk**: Calculation algorithm may have edge cases that produce incorrect results +- **Probability**: LOW +- **Impact**: HIGH +- **Mitigation Strategies**: + - Use proven, well-documented algorithms (Zeller's Congruence or standard library functions) + - Implement comprehensive test cases covering all century boundaries and leap year rules + - Validate results against multiple independent sources (astronomical databases, perpetual calendars) + - Include specific tests for known edge cases (1600, 1700, 1800, 1900, 2000, 2100) + +#### TR2: Platform-Specific Date Function Behavior +- **Risk**: Different platforms may interpret date functions differently +- **Probability**: MEDIUM +- **Impact**: MEDIUM +- **Mitigation Strategies**: + - Document which date functions are used and their expected behavior + - Implement custom algorithm if platform functions prove unreliable + - Test on multiple platforms during QA phase + - Maintain unit tests that verify specific date calculations + +#### TR3: Integer Overflow for Large/Small Years +- **Risk**: Date calculations involving years at boundaries (1600, 3000) may cause integer overflow +- **Probability**: LOW +- **Impact**: MEDIUM +- **Mitigation Strategies**: + - Use appropriate integer types (64-bit integers if available) + - Implement boundary tests specifically for years 1600 and 3000 + - Document numeric range limitations + - Add overflow detection and error handling + +### Functional Risks + +#### FR1: Incomplete Test Framework +- **Risk**: Test framework may be implemented as stub without full functionality +- **Probability**: MEDIUM +- **Impact**: MEDIUM +- **Mitigation Strategies**: + - Clearly define test framework requirements in Phase 2 + - Allocate sufficient time for test framework implementation + - Prioritize test framework completion before enhancement phase + - Ensure test framework can actually invoke calculation engine programmatically + +#### FR2: User Input Validation Gaps +- **Risk**: Unexpected input types may not be handled properly +- **Probability**: MEDIUM +- **Impact**: LOW +- **Mitigation Strategies**: + - Implement comprehensive input validation (type checking, range checking) + - Add try-catch blocks or equivalent error handling + - Test with fuzzing techniques (random inputs) + - Ensure graceful degradation for all invalid inputs + +### Usability Risks + +#### UR1: Unclear Error Messages +- **Risk**: Users may not understand error messages or how to correct errors +- **Probability**: MEDIUM +- **Impact**: LOW +- **Mitigation Strategies**: + - Review all error messages for clarity + - Include specific guidance in error messages (e.g., "Please enter a year between 1600 and 3000") + - Conduct usability testing with non-technical users + - Iterate on message wording based on feedback + +#### UR2: Output Format Not Meeting User Needs +- **Risk**: Output may be too technical or not provide enough context +- **Probability**: LOW +- **Impact**: LOW +- **Mitigation Strategies**: + - Include user representatives in design reviews + - Provide contextual "Fun Facts" to add value + - Format output with clear visual structure + - Gather feedback during beta testing + +### Schedule Risks + +#### SR1: Algorithm Implementation Complexity +- **Risk**: Date calculation algorithm may take longer to implement than estimated +- **Probability**: LOW +- **Impact**: MEDIUM +- **Mitigation Strategies**: + - Use standard library functions where possible (reduces implementation time) + - Allocate buffer time in Phase 1 + - Have fallback to simpler algorithm if complex implementation fails + - Consider using proven third-party libraries if permitted + +#### SR2: Test Framework Scope Creep +- **Risk**: Test framework requirements may expand beyond initial scope +- **Probability**: MEDIUM +- **Impact**: MEDIUM +- **Mitigation Strategies**: + - Clearly define MVP requirements for test framework + - Prioritize automated execution over advanced features + - Defer enhancements to future releases + - Maintain strict scope control during Phase 2 + +### Quality Risks + +#### QR1: Insufficient Test Coverage +- **Risk**: Test cases may not cover all scenarios, leading to undiscovered bugs +- **Probability**: MEDIUM +- **Impact**: HIGH +- **Mitigation Strategies**: + - Define comprehensive test matrix covering: + - All century boundaries (1600, 1700, 1800, 1900, 2000, 2100, 2200, 2300, 2400, 2500, 2600, 2700, 2800, 2900, 3000) + - All days of week for at least one year + - Leap years and non-leap years + - Special leap year rules (divisible by 100 but not 400) + - Allocate full week for QA (Phase 4) + - Implement automated regression testing + - Validate against external calendar sources + +#### QR2: Performance Degradation +- **Risk**: System may not meet performance targets on lower-end hardware +- **Probability**: LOW +- **Impact**: LOW +- **Mitigation Strategies**: + - Use efficient algorithms (O(1) complexity for calculations) + - Avoid unnecessary loops or data processing + - Test on minimum specification hardware + - Optimize hotspot code if necessary + +--- + +## Conclusion + +The Holiday Day-of-Week Calculator represents a focused solution to a common planning need: determining when national holidays fall on specific days of the week. By providing accurate calculations for Canada Day (July 1st) across a 1400-year span, the system supports diverse use cases from event planning to historical research. + +### Key Success Factors + +1. **Mathematical Accuracy**: The system's foundation on proven date calculation algorithms ensures reliable results across all boundary conditions and edge cases. + +2. **User-Centric Design**: The interactive interface prioritizes ease of use, clear communication, and helpful contextual information, making the tool accessible to non-technical users. + +3. **Quality Assurance**: The integrated automated testing framework ensures ongoing accuracy and supports future enhancements with confidence. + +4. **Modular Architecture**: The separation of calculation logic, user interface, and testing components enables future extensibility (additional holidays, output formats, internationalization). + +### Strategic Value + +This system serves as a prototype for a broader holiday calculation suite. The architecture and design patterns established here can be extended to support: +- Additional Canadian holidays (Victoria Day, Thanksgiving, Remembrance Day) +- International holidays (US Independence Day, UK Bank Holidays, etc.) +- Custom organizational holidays +- Multi-year planning reports +- Integration with calendar and scheduling systems + +### Next Steps + +Upon approval of this PRD: + +1. **Immediate**: Initiate Phase 1 development with focus on calculation engine +2. **Week 4**: Review progress and demonstrate working prototype +3. **Week 6**: Conduct user acceptance testing with stakeholder representatives +4. **Week 8**: Final approval and production release + +### Success Metrics + +The system will be considered successful when: +- ✅ 100% accuracy on comprehensive test suite (>500 test cases across date range) +- ✅ <100ms calculation time on standard hardware +- ✅ Zero crashes or errors during 1000+ consecutive operations +- ✅ 90%+ user satisfaction score on usability survey +- ✅ Successful integration with automated testing framework +- ✅ Complete documentation package for users and developers + +This PRD provides the foundation for building a reliable, maintainable, and extensible holiday calculation system that meets current needs while positioning for future growth. + +--- + +**Document Control** + +| Version | Date | Author | Changes | +|---------|------|--------|---------| +| 1.0 | 2025-01-XX | Product Team | Initial PRD based on existing system analysis | + +**Approval Required From:** +- [ ] Product Owner +- [ ] Technical Lead +- [ ] QA Manager +- [ ] Business Stakeholder + +**Related Documents:** +- COBOL Program Analysis Report (cobol_analyzer_report.md) +- COBOL Dependency Report (cobol_dependency_report.md) +- Technical Implementation Specification (TBD) +- User Guide (TBD) +- Test Plan (TBD) + +--- + +*This PRD is a living document and may be updated as requirements evolve. All changes must be approved through the formal change control process.* diff --git a/AS400/COBOL_examples/Holidays/QCBLLESRC/cobol_analyzer_report.md b/AS400/COBOL_examples/Holidays/QCBLLESRC/cobol_analyzer_report.md new file mode 100644 index 0000000..399cd2d --- /dev/null +++ b/AS400/COBOL_examples/Holidays/QCBLLESRC/cobol_analyzer_report.md @@ -0,0 +1,718 @@ +# COBOL Program Analysis Report + +**Analysis Date:** Generated by COBOL Analyzer +**Directory:** /home/runner/work/Cobol-Demo/Cobol-Demo/AS400/COBOL_examples/Holidays/QCBLLESRC +**Programs Analyzed:** 2 + +--- + +## Table of Contents +1. [Program Overview](#program-overview) +2. [CANDAY01.CBLLE - Canada Day Calculator](#canday01cblle---canada-day-calculator) +3. [TESTCDAY.CBLLE - Test Program](#testcdaycblle---test-program) +4. [Cross-Program Relationships](#cross-program-relationships) +5. [Summary](#summary) + +--- + +## Program Overview + +This directory contains two COBOL programs related to Canada Day calculation: +- **CANDAY01.CBLLE**: Main calculator program that determines what day of the week Canada Day (July 1st) falls on for any given year +- **TESTCDAY.CBLLE**: Automated test program designed to test CANDAY01 + +--- + +## CANDAY01.CBLLE - Canada Day Calculator + +### Program Identification +- **Program ID:** CANDAY01 +- **Author:** Development Team +- **Date Written:** July 21, 2025 +- **Purpose:** Determines what day of the week Canada Day (July 1st) falls on for any given year (historical or future) + +### Environment Division + +#### Configuration Section +- **Special Names:** DECIMAL-POINT IS COMMA + +### Data Division + +#### Working-Storage Section + +##### 1. Input Year Fields (Lines 22-23) +``` +01 WS-INPUT-YEAR PIC 9(4) VALUE ZEROS + - Level: 01 + - Type: Numeric + - Size: 4 digits + - Purpose: Stores the year input from user + - Initial Value: 0000 + +01 WS-INPUT-YEAR-DISPLAY PIC Z(4) + - Level: 01 + - Type: Numeric (Display format with leading zero suppression) + - Size: 4 characters + - Purpose: Formatted display of input year +``` + +##### 2. Date Calculation Fields (Lines 26-29) +``` +01 WS-CANADA-DATE (Group Level) + - Level: 01 + - Type: Group item + - Purpose: Holds the complete Canada Day date components + + 05 WS-YEAR PIC 9(4) + - Level: 05 (subordinate to WS-CANADA-DATE) + - Type: Numeric + - Size: 4 digits + - Purpose: Year component of Canada Day + + 05 WS-MONTH PIC 9(2) VALUE 07 + - Level: 05 + - Type: Numeric + - Size: 2 digits + - Purpose: Month component (always July = 07) + - Initial Value: 07 + + 05 WS-DAY PIC 9(2) VALUE 01 + - Level: 05 + - Type: Numeric + - Size: 2 digits + - Purpose: Day component (always 1st = 01) + - Initial Value: 01 +``` + +##### 3. Day of Week Calculation Fields (Lines 32-33) +``` +01 WS-DAY-OF-WEEK PIC 9(1) + - Level: 01 + - Type: Numeric + - Size: 1 digit + - Purpose: Numeric representation of day (1-7) + +01 WS-DAY-NAME PIC X(9) + - Level: 01 + - Type: Alphanumeric + - Size: 9 characters + - Purpose: Text name of the day of week +``` + +##### 4. Date Manipulation Fields (Lines 36-37) +``` +01 WS-DATE-NUMERIC PIC 9(8) + - Level: 01 + - Type: Numeric + - Size: 8 digits + - Purpose: Date in YYYYMMDD format for calculations + +01 WS-DATE-FORMATTED PIC X(10) + - Level: 01 + - Type: Alphanumeric + - Size: 10 characters + - Purpose: Formatted date string (currently unused in program) +``` + +##### 5. Day Name Table (Lines 40-50) +``` +01 WS-DAY-TABLE (Group Level - Table Definition) + - Level: 01 + - Type: Group item containing 7 FILLER entries + - Purpose: Stores day names for lookup + + 05 FILLER PIC X(9) VALUE 'Sunday ' + 05 FILLER PIC X(9) VALUE 'Monday ' + 05 FILLER PIC X(9) VALUE 'Tuesday ' + 05 FILLER PIC X(9) VALUE 'Wednesday' + 05 FILLER PIC X(9) VALUE 'Thursday ' + 05 FILLER PIC X(9) VALUE 'Friday ' + 05 FILLER PIC X(9) VALUE 'Saturday ' + +01 WS-DAY-NAMES REDEFINES WS-DAY-TABLE + - REDEFINES: WS-DAY-TABLE (same memory space) + - Purpose: Array accessor for day names + + 05 WS-DAY-ENTRY PIC X(9) OCCURS 7 TIMES + - Level: 05 + - Type: Alphanumeric array + - Size: 9 characters per entry + - Occurrences: 7 (one for each day) + - Purpose: Individual day name accessor +``` + +##### 6. Error Handling Fields (Lines 53-54) +``` +01 WS-ERROR-FLAG PIC X(1) VALUE 'N' + - Level: 01 + - Type: Alphanumeric + - Size: 1 character + - Purpose: Indicates validation errors ('Y'/'N') + - Initial Value: 'N' + +01 WS-CONTINUE-FLAG PIC X(1) VALUE 'Y' + - Level: 01 + - Type: Alphanumeric + - Size: 1 character + - Purpose: Controls program loop continuation ('Y'/'N') + - Initial Value: 'Y' +``` + +##### 7. Display Formatting Fields (Line 57) +``` +01 WS-DISPLAY-LINE PIC X(80) + - Level: 01 + - Type: Alphanumeric + - Size: 80 characters + - Purpose: Formatted output line buffer +``` + +### Procedure Division + +#### Main Control Flow + +##### MAIN-PROCEDURE (Lines 61-80) +**Purpose:** Primary program entry point and control loop + +**Logic Flow:** +1. Display program header and title +2. Enter main processing loop (PERFORM UNTIL WS-CONTINUE-FLAG = 'N') + - Get year input from user + - If no errors, calculate day of week + - Display results + - Ask user to continue +3. Display exit message +4. GOBACK to calling program + +**Calls/Performs:** +- `PERFORM GET-YEAR-INPUT` (Line 70) +- `PERFORM CALCULATE-DAY-OF-WEEK` (Line 72) +- `PERFORM DISPLAY-RESULT` (Line 73) +- `PERFORM ASK-CONTINUE` (Line 75) + +**Exit:** GOBACK (Line 80) + +--- + +#### GET-YEAR-INPUT SECTION (Lines 82-94) +**Purpose:** Accept and validate year input from user + +**Logic Flow:** +1. Reset error flag to 'N' +2. Prompt user for year input (1600-3000) +3. Accept year from user input +4. Validate year range: + - If year < 1600 OR year > 3000: + - Display error message + - Set error flag to 'Y' + - Else: + - Move input year to WS-YEAR + +**Variables Modified:** +- WS-ERROR-FLAG +- WS-INPUT-YEAR (via ACCEPT) +- WS-YEAR + +**Input Validation:** +- Range: 1600 to 3000 (inclusive) +- Error handling via WS-ERROR-FLAG + +--- + +#### CALCULATE-DAY-OF-WEEK SECTION (Lines 96-116) +**Purpose:** Calculate which day of the week Canada Day falls on for given year + +**Logic Flow:** +1. Build date in YYYYMMDD format: + - Move WS-YEAR to positions 1-4 of WS-DATE-NUMERIC + - Move WS-MONTH (07) to positions 5-6 + - Move WS-DAY (01) to positions 7-8 +2. Calculate day of week using intrinsic functions: + - Use FUNCTION INTEGER-OF-DATE to convert date to integer + - Apply MOD 7 to get day of week (0-6) + - Add 1 to adjust to 1-7 range +3. Adjust for table indexing (Sunday=1, Monday=2, etc.): + - If result = 7, set to 1 (Sunday) + - Else add 1 to result +4. Retrieve day name from WS-DAY-ENTRY array + +**Variables Modified:** +- WS-DATE-NUMERIC (Lines 98-100) +- WS-DAY-OF-WEEK (Lines 104-112) +- WS-DAY-NAME (Line 116) + +**COBOL Intrinsic Functions Used:** +- `FUNCTION INTEGER-OF-DATE(WS-DATE-NUMERIC)` - Converts date to integer days since base date +- `FUNCTION MOD(value, 7)` - Returns remainder of division by 7 + +**Algorithm:** +- Uses Zeller's congruence-style calculation via COBOL intrinsic functions +- INTEGER-OF-DATE returns days since a base date (implementation-specific) +- MOD 7 gives day of week (0-6) +- Adjustment logic maps to table index (1-7) + +--- + +#### DISPLAY-RESULT SECTION (Lines 118-147) +**Purpose:** Format and display the calculated result with additional information + +**Logic Flow:** +1. Format input year for display (with leading zero suppression) +2. Display result header +3. Build and display main result message using STRING verb: + - "Canada Day (July 1, [YEAR]) falls on a [DAY NAME]" +4. Display fun facts based on day of week: + - If Saturday or Sunday: weekend celebration message + - If weekday: long weekend message + - If Monday: special Monday message + - If Friday: special Friday message + +**Variables Modified:** +- WS-INPUT-YEAR-DISPLAY (Line 119) +- WS-DISPLAY-LINE (Lines 123-128) + +**String Operations:** +- Uses STRING verb with DELIMITED BY SIZE (Lines 123-128) +- Concatenates multiple string literals with variable values + +**Conditional Logic:** +- Weekend detection: Lines 135-139 +- Monday special case: Lines 141-143 +- Friday special case: Lines 145-147 + +--- + +#### ASK-CONTINUE SECTION (Lines 149-158) +**Purpose:** Prompt user to continue or exit program + +**Logic Flow:** +1. Prompt user for continue response (Y/N) +2. Accept user input +3. Normalize input: + - If 'y' or 'Y': set WS-CONTINUE-FLAG to 'Y' + - Otherwise: set WS-CONTINUE-FLAG to 'N' + +**Variables Modified:** +- WS-CONTINUE-FLAG (Lines 152-157) + +**Input Handling:** +- Case-insensitive (accepts both 'y' and 'Y') +- Any value other than 'y'/'Y' treated as 'N' + +--- + +### Paragraph/Section Call Relationships + +``` +MAIN-PROCEDURE (Entry Point) +│ +├── PERFORM GET-YEAR-INPUT +│ └── Validates user input (1600-3000) +│ +├── PERFORM CALCULATE-DAY-OF-WEEK (conditional on no errors) +│ └── Uses intrinsic date functions +│ +├── PERFORM DISPLAY-RESULT (conditional on no errors) +│ └── Formats and displays results +│ +└── PERFORM ASK-CONTINUE + └── Controls loop continuation + +GOBACK (Exit Point) +``` + +### Embedded SQL/DB2 Statements +**None found** - This program does not use embedded SQL or database access. + +### File Access Patterns +**None found** - This program does not use file I/O. +- No FILE-CONTROL section defined +- No FD (File Description) entries +- No OPEN, READ, WRITE, CLOSE statements +- Uses ACCEPT/DISPLAY for user interaction only + +### Key Features & Algorithms + +1. **Date Calculation Algorithm:** + - Uses COBOL intrinsic function INTEGER-OF-DATE + - Converts date to integer representation + - Applies modulo 7 to determine day of week + - Maps result to day name lookup table + +2. **Input Validation:** + - Year range: 1600-3000 + - Error flag pattern for flow control + +3. **User Interface:** + - Interactive console-based + - Loop-until-exit pattern + - Case-insensitive input handling + +4. **Data Structure Techniques:** + - REDEFINES clause for array access + - OCCURS clause for table definition + - Group items for logical data organization + +5. **COBOL Language Features Demonstrated:** + - PERFORM UNTIL loop + - PERFORM VARYING loop structure (not used, but structure present) + - STRING verb for formatted output + - Intrinsic functions (INTEGER-OF-DATE, MOD) + - REDEFINES and OCCURS for table handling + - Reference modification for substring operations + +--- + +## TESTCDAY.CBLLE - Test Program + +### Program Identification +- **Program ID:** TESTCDAY +- **Author:** Development Team +- **Date Written:** July 21, 2025 +- **Purpose:** Demonstrates automated testing of CANDAY01 (Note: actual calling mechanism not implemented) + +### Data Division + +#### Working-Storage Section + +##### 1. Test Years Array (Lines 15-23) +``` +01 WS-TEST-YEARS (Group Level - Data Definition) + - Level: 01 + - Type: Group item containing test year values + - Purpose: Stores predefined test years + + 05 FILLER PIC 9(4) VALUE 2024 + 05 FILLER PIC 9(4) VALUE 2025 + 05 FILLER PIC 9(4) VALUE 2026 + 05 FILLER PIC 9(4) VALUE 1867 (Confederation year) + 05 FILLER PIC 9(4) VALUE 2030 + +01 WS-TEST-ARRAY REDEFINES WS-TEST-YEARS + - REDEFINES: WS-TEST-YEARS (same memory space) + - Purpose: Array accessor for test years + + 05 WS-TEST-YEAR PIC 9(4) OCCURS 5 TIMES + - Level: 05 + - Type: Numeric array + - Size: 4 digits per entry + - Occurrences: 5 test cases + - Purpose: Individual test year accessor +``` + +##### 2. Loop Control (Line 25) +``` +01 WS-INDEX PIC 9(2) VALUE 1 + - Level: 01 + - Type: Numeric + - Size: 2 digits + - Purpose: Loop counter for PERFORM VARYING + - Initial Value: 1 +``` + +### Procedure Division + +#### MAIN-PROCEDURE (Lines 29-40) +**Purpose:** Entry point and test execution controller + +**Logic Flow:** +1. Display test header +2. Execute PERFORM VARYING loop: + - Iterate from 1 to 5 (WS-INDEX) + - For each iteration, PERFORM TEST-YEAR +3. Display completion message +4. GOBACK + +**Loop Structure:** +- Type: PERFORM VARYING +- Control Variable: WS-INDEX +- Range: 1 to 5 +- Increment: BY 1 + +**Calls/Performs:** +- `PERFORM TEST-YEAR` (Line 35) + +**Exit:** GOBACK (Line 40) + +--- + +#### TEST-YEAR SECTION (Lines 42-45) +**Purpose:** Process each test year (stub implementation) + +**Logic Flow:** +1. Display current test year being processed +2. Display note about implementation status + +**Variables Referenced:** +- WS-TEST-YEAR(WS-INDEX) - subscripted array access + +**Note:** This is a stub implementation. The comment on line 45 indicates that in a production version, this would call CANDAY01 to perform actual testing. + +--- + +### Paragraph/Section Call Relationships + +``` +MAIN-PROCEDURE (Entry Point) +│ +└── PERFORM VARYING (loop 5 times) + └── PERFORM TEST-YEAR + └── Display test year (stub) + +GOBACK (Exit Point) +``` + +### Embedded SQL/DB2 Statements +**None found** - This program does not use embedded SQL or database access. + +### File Access Patterns +**None found** - This program does not use file I/O. +- No FILE-CONTROL section defined +- No FD (File Description) entries +- Uses DISPLAY for output only + +### Key Features + +1. **Test Data Structure:** + - Hardcoded test years in array + - Includes historical year (1867 - Canadian Confederation) + - Includes recent and future years (2024-2030) + +2. **Array Processing:** + - REDEFINES for array access + - OCCURS 5 TIMES for array definition + - Subscripted array reference: WS-TEST-YEAR(WS-INDEX) + +3. **Loop Control:** + - PERFORM VARYING for indexed iteration + - Counter-controlled loop (1 to 5) + +4. **Design Pattern:** + - Test driver pattern + - Stub implementation for demonstration + +--- + +## Cross-Program Relationships + +### Program Dependencies + +``` +TESTCDAY.CBLLE + │ + └── [Intended] CANDAY01.CBLLE + (Not implemented - noted in comments) +``` + +### Integration Notes + +1. **Current Implementation:** + - TESTCDAY is a standalone stub + - Does not actually call CANDAY01 + - Serves as framework/template for future integration + +2. **Intended Design:** + - TESTCDAY should invoke CANDAY01 for each test year + - Would require one of the following mechanisms: + - CALL statement to invoke CANDAY01 as subprogram + - Shared data area for passing parameters + - File-based or queue-based communication + +3. **Potential Integration Methods:** + ```cobol + * Method 1: Static Call + CALL 'CANDAY01' USING WS-TEST-YEAR(WS-INDEX) + + * Method 2: Dynamic Call + CALL WS-PROGRAM-NAME USING WS-PARAMETERS + + * Method 3: Modify CANDAY01 for batch processing + ``` + +4. **Data Flow (Proposed):** + ``` + TESTCDAY → [Year Input] → CANDAY01 → [Day Result] → Validation + ``` + +### Test Coverage + +**Test Cases Defined:** +1. 2024 - Recent past/current year +2. 2025 - Current/near future year +3. 2026 - Future year +4. 1867 - Historical significant year (Canadian Confederation) +5. 2030 - Future year for long-term planning + +**Test Characteristics:** +- Mix of historical and future dates +- Includes significant historical year +- Covers reasonable range for business use cases +- Does not test boundary conditions (1600, 3000) + +--- + +## Summary + +### Program Statistics + +| Metric | CANDAY01 | TESTCDAY | +|--------|----------|----------| +| Total Lines | 161 | 48 | +| Divisions | 4 | 2 | +| Sections | 4 | 2 | +| Working-Storage Variables (01 level) | 11 | 3 | +| Group Items | 3 | 2 | +| Elementary Items | 8 | 1 | +| PERFORM Statements | 5 | 2 | +| Conditional Statements | 7 | 0 | +| DISPLAY Statements | 28 | 7 | +| ACCEPT Statements | 2 | 0 | + +### Data Structures Summary + +**CANDAY01 Data Organization:** +- Input/Output: 2 items (WS-INPUT-YEAR, WS-INPUT-YEAR-DISPLAY) +- Date Structures: 3 items (WS-CANADA-DATE group, WS-DATE-NUMERIC, WS-DATE-FORMATTED) +- Day Calculation: 2 items (WS-DAY-OF-WEEK, WS-DAY-NAME) +- Lookup Table: 2 items (WS-DAY-TABLE, WS-DAY-NAMES with 7 entries) +- Control Flags: 2 items (WS-ERROR-FLAG, WS-CONTINUE-FLAG) +- Formatting: 1 item (WS-DISPLAY-LINE) + +**TESTCDAY Data Organization:** +- Test Data: 2 items (WS-TEST-YEARS group, WS-TEST-ARRAY with 5 entries) +- Loop Control: 1 item (WS-INDEX) + +### Logic Complexity + +**CANDAY01:** +- Complexity: Medium +- Control Structures: PERFORM UNTIL, nested IF statements, PERFORM VARYING (structure) +- Algorithm Complexity: Low (uses intrinsic functions) +- User Interaction: High (interactive console program) + +**TESTCDAY:** +- Complexity: Low +- Control Structures: PERFORM VARYING +- Algorithm Complexity: Minimal (stub implementation) +- User Interaction: Low (display only) + +### SQL/Database Usage +- **None** in either program +- Both programs are self-contained +- No external data dependencies +- No file I/O operations + +### File Operations +- **None** in either program +- CANDAY01 uses ACCEPT/DISPLAY for console I/O +- TESTCDAY uses DISPLAY for output +- No file definitions or file processing + +### Code Quality Observations + +**Strengths:** +1. Clear, descriptive variable names with prefixes (WS-) +2. Well-structured with logical sections +3. Good use of COBOL features (REDEFINES, OCCURS, intrinsic functions) +4. Comprehensive comments and documentation +5. Input validation with error handling +6. User-friendly interface with formatted output +7. Modular design with separate sections for each function + +**Areas for Enhancement:** +1. TESTCDAY is incomplete (stub only) +2. WS-DATE-FORMATTED defined but unused in CANDAY01 +3. Error handling could include invalid input type handling +4. No logging or audit trail +5. Could benefit from parameterized entry point for batch processing +6. Test program could include expected results for validation + +### Platform Considerations + +**AS/400 Specific Features:** +- .CBLLE extension indicates ILE COBOL for AS/400 +- DECIMAL-POINT IS COMMA configuration (European numeric format) +- Uses standard COBOL intrinsic functions (portable) +- GOBACK for program termination (AS/400 standard) + +**Portability:** +- Most code is standard COBOL and portable +- INTEGER-OF-DATE function is standard COBOL intrinsic +- DECIMAL-POINT IS COMMA would need adjustment for other locales +- Interactive ACCEPT/DISPLAY works on most platforms + +### Maintenance Recommendations + +1. **Complete TESTCDAY Implementation:** + - Add actual CALL to CANDAY01 + - Implement result validation + - Add expected results table for comparison + +2. **Enhanced Error Handling:** + - Add input type validation + - Handle non-numeric input gracefully + - Add error logging + +3. **Documentation:** + - Add inline comments for complex calculations + - Document the day-of-week algorithm more explicitly + - Add examples of expected output + +4. **Testing:** + - Add boundary condition tests (1600, 3000) + - Test leap year handling + - Test century transitions + - Add regression test suite + +5. **Code Cleanup:** + - Remove or utilize WS-DATE-FORMATTED + - Consider parameterized version for batch use + - Add return code for success/failure indication + +--- + +## Detailed Variable Cross-Reference + +### CANDAY01 Variables + +| Variable Name | Type | Level | Size | Usage Count | Sections Used | +|---------------|------|-------|------|-------------|---------------| +| WS-INPUT-YEAR | 9(4) | 01 | 4 | 4 | GET-YEAR-INPUT (2), DISPLAY-RESULT (1), MAIN-PROCEDURE (1) | +| WS-INPUT-YEAR-DISPLAY | Z(4) | 01 | 4 | 2 | DISPLAY-RESULT | +| WS-CANADA-DATE | Group | 01 | - | 0 | (group only) | +| WS-YEAR | 9(4) | 05 | 4 | 3 | GET-YEAR-INPUT (1), CALCULATE-DAY-OF-WEEK (2) | +| WS-MONTH | 9(2) | 05 | 2 | 1 | CALCULATE-DAY-OF-WEEK | +| WS-DAY | 9(2) | 05 | 2 | 1 | CALCULATE-DAY-OF-WEEK | +| WS-DAY-OF-WEEK | 9(1) | 01 | 1 | 4 | CALCULATE-DAY-OF-WEEK | +| WS-DAY-NAME | X(9) | 01 | 9 | 4 | CALCULATE-DAY-OF-WEEK (1), DISPLAY-RESULT (3) | +| WS-DATE-NUMERIC | 9(8) | 01 | 8 | 2 | CALCULATE-DAY-OF-WEEK | +| WS-DATE-FORMATTED | X(10) | 01 | 10 | 0 | (unused) | +| WS-DAY-TABLE | Group | 01 | 63 | 0 | (table definition) | +| WS-DAY-NAMES | Group | 01 | 63 | 0 | (REDEFINES) | +| WS-DAY-ENTRY | X(9) | 05 | 9 | 1 | CALCULATE-DAY-OF-WEEK | +| WS-ERROR-FLAG | X(1) | 01 | 1 | 4 | GET-YEAR-INPUT (2), MAIN-PROCEDURE (1) | +| WS-CONTINUE-FLAG | X(1) | 01 | 1 | 5 | MAIN-PROCEDURE (1), ASK-CONTINUE (4) | +| WS-DISPLAY-LINE | X(80) | 01 | 80 | 2 | DISPLAY-RESULT | + +### TESTCDAY Variables + +| Variable Name | Type | Level | Size | Usage Count | Sections Used | +|---------------|------|-------|------|-------------|---------------| +| WS-TEST-YEARS | Group | 01 | 20 | 0 | (group only) | +| WS-TEST-ARRAY | Group | 01 | 20 | 0 | (REDEFINES) | +| WS-TEST-YEAR | 9(4) | 05 | 4 | 1 | TEST-YEAR | +| WS-INDEX | 9(2) | 01 | 2 | 2 | MAIN-PROCEDURE | + +--- + +## End of Analysis Report + +**Report Generated For:** +- CANDAY01.CBLLE (161 lines) +- TESTCDAY.CBLLE (48 lines) + +**Total Programs Analyzed:** 2 +**Total Lines of Code:** 209 +**Analysis Completion:** Successful + +--- diff --git a/AS400/COBOL_examples/Holidays/QCBLLESRC/cobol_dependency_report.md b/AS400/COBOL_examples/Holidays/QCBLLESRC/cobol_dependency_report.md new file mode 100644 index 0000000..e6b038f --- /dev/null +++ b/AS400/COBOL_examples/Holidays/QCBLLESRC/cobol_dependency_report.md @@ -0,0 +1,469 @@ +# COBOL Dependency Analysis Report + +**Analysis Date:** 2025-07-21 +**Directory:** `/home/runner/work/Cobol-Demo/Cobol-Demo/AS400/COBOL_examples/Holidays/QCBLLESRC` +**Analyzer:** COBOL Dependency Subagent + +--- + +## Executive Summary + +This analysis examines the dependency structure of two COBOL programs in the Holidays module: +- **CANDAY01.CBLLE** - Canada Day Calculator (main program) +- **TESTCDAY.CBLLE** - Test program for CANDAY01 + +The codebase demonstrates a **simple, loosely-coupled architecture** with minimal dependencies, representing a well-structured modular design suitable for AS400 ILE COBOL. + +--- + +## 1. Program Inventory + +### CANDAY01.CBLLE (Canada Day Calculator) +- **Type:** Main program / Callable module +- **Lines of Code:** 161 +- **Purpose:** Calculates the day of the week for Canada Day (July 1st) for any given year +- **Complexity:** Low-Medium +- **Entry Points:** 1 (MAIN-PROCEDURE) + +### TESTCDAY.CBLLE (Test Program) +- **Type:** Test harness / Driver program +- **Lines of Code:** 48 +- **Purpose:** Automated testing framework for CANDAY01 +- **Complexity:** Low +- **Entry Points:** 1 (MAIN-PROCEDURE) + +--- + +## 2. Dependency Analysis + +### 2.1 External Dependencies + +#### CANDAY01.CBLLE Dependencies: +``` +External Dependencies: NONE +├── No COPY statements +├── No CALL statements +└── No external file access (files, databases) + +Intrinsic Functions Used: +├── FUNCTION MOD +├── FUNCTION INTEGER-OF-DATE +└── Built-in ACCEPT/DISPLAY for I/O +``` + +**Analysis:** CANDAY01 is a **self-contained module** with zero external dependencies. This represents excellent modularity and portability. + +#### TESTCDAY.CBLLE Dependencies: +``` +External Dependencies: CANDAY01 (intended, not implemented) +├── No COPY statements +├── No CALL statements (commented as future implementation) +└── No external file access + +Current State: STUB IMPLEMENTATION +``` + +**Analysis:** TESTCDAY is designed to test CANDAY01 but currently only provides a test framework stub. The intended dependency on CANDAY01 is documented but not yet implemented via CALL statement. + +### 2.2 Dependency Graph + +``` +┌─────────────────┐ +│ TESTCDAY │ +│ (Test Driver) │ +└────────┬────────┘ + │ + │ (Intended CALL - Not Implemented) + ↓ +┌─────────────────┐ +│ CANDAY01 │ +│ (Calculator) │ +└─────────────────┘ + │ + ↓ + [No Dependencies] +``` + +**Dependency Type:** One-way, hierarchical (test → application) +**Coupling Level:** Loose (currently none; intended to be procedural CALL) + +### 2.3 Data Flow Analysis + +#### CANDAY01 Data Flow: +``` +Input Sources: +├── WS-INPUT-YEAR (ACCEPT from user) +└── WS-CONTINUE-FLAG (ACCEPT from user) + +Internal Data Transformations: +├── WS-INPUT-YEAR → WS-YEAR → WS-DATE-NUMERIC +├── WS-DATE-NUMERIC → FUNCTION INTEGER-OF-DATE → WS-DAY-OF-WEEK +└── WS-DAY-OF-WEEK → WS-DAY-ENTRY(index) → WS-DAY-NAME + +Output Destinations: +└── DISPLAY statements (screen output only) +``` + +**Data Isolation:** All data is contained within WORKING-STORAGE SECTION. No LINKAGE SECTION exists, indicating the program is not currently designed to be called with parameters. + +#### TESTCDAY Data Flow: +``` +Input Sources: +└── Hard-coded test data (WS-TEST-YEARS array) + +Data Processing: +└── WS-TEST-YEAR array iteration via WS-INDEX + +Output Destinations: +└── DISPLAY statements (informational only) +``` + +--- + +## 3. Copybook Analysis + +### 3.1 Current State +**No copybooks are used** in either program. + +### 3.2 Potential Copybook Opportunities + +The following data structures could be extracted into reusable copybooks: + +1. **Day-of-Week Table** (from CANDAY01) + ```cobol + Suggested Copybook: DAYNAMES.CPY + Contains: WS-DAY-TABLE and WS-DAY-NAMES structures + Reusability: HIGH (useful for any date-related program) + ``` + +2. **Date Calculation Fields** (from CANDAY01) + ```cobol + Suggested Copybook: DATEUTIL.CPY + Contains: WS-CANADA-DATE, WS-DATE-NUMERIC, WS-DATE-FORMATTED + Reusability: MEDIUM (date manipulation programs) + ``` + +3. **Error Handling Fields** (from CANDAY01) + ```cobol + Suggested Copybook: ERRFLAGS.CPY + Contains: WS-ERROR-FLAG, WS-CONTINUE-FLAG + Reusability: MEDIUM (interactive programs) + ``` + +--- + +## 4. Circular Dependency Analysis + +### Finding: **NO CIRCULAR DEPENDENCIES** + +**Rationale:** +- Only two programs exist in the module +- TESTCDAY is designed to call CANDAY01 (one-way dependency) +- CANDAY01 has no dependencies on TESTCDAY or any other module +- No COPY chains exist (no copybooks used) + +**Risk Level:** ✅ **NONE** - No circular dependency risk detected. + +--- + +## 5. Modularity Assessment + +### 5.1 CANDAY01 Modularity + +| Aspect | Rating | Comments | +|--------|--------|----------| +| Single Responsibility | ⭐⭐⭐⭐⭐ | Excellent - does one thing well | +| Cohesion | ⭐⭐⭐⭐⭐ | High - all code relates to Canada Day calculation | +| Coupling | ⭐⭐⭐⭐⭐ | Zero external coupling | +| Reusability | ⭐⭐⭐ | Medium - hardcoded for interactive use | +| Testability | ⭐⭐⭐ | Medium - requires refactoring for automated testing | + +**Strengths:** +- Well-structured with clear section divisions +- Excellent use of PERFORM for procedural flow +- Good error handling and input validation +- Self-documenting code with meaningful variable names + +**Weaknesses:** +- Not designed for programmatic calling (no LINKAGE SECTION) +- Interactive I/O makes automated testing difficult +- Tightly coupled to ACCEPT/DISPLAY paradigm + +### 5.2 TESTCDAY Modularity + +| Aspect | Rating | Comments | +|--------|--------|----------| +| Single Responsibility | ⭐⭐⭐⭐ | Clear purpose as test driver | +| Cohesion | ⭐⭐⭐ | Medium - stub implementation incomplete | +| Coupling | ⭐⭐⭐⭐ | Low - minimal dependencies (by design) | +| Reusability | ⭐⭐ | Low - specific to CANDAY01 testing | +| Testability | N/A | This IS the test program | + +--- + +## 6. Legacy Patterns Identified + +### 6.1 Patterns Affecting Dependencies + +#### ✅ **Good Legacy Patterns:** + +1. **Self-Contained Modules** + - Location: Both programs + - Impact: Positive - reduces dependency complexity + - Pattern: Monolithic but functional + +2. **Sectioned Procedures** + - Location: CANDAY01 (GET-YEAR-INPUT, CALCULATE-DAY-OF-WEEK, etc.) + - Impact: Positive - enables internal modularity + - Pattern: Classic COBOL structured programming + +3. **Intrinsic Functions** + - Location: CANDAY01 (FUNCTION INTEGER-OF-DATE, MOD) + - Impact: Positive - uses modern COBOL features instead of external routines + - Pattern: ILE COBOL best practice + +#### ⚠️ **Legacy Anti-Patterns:** + +1. **Interactive I/O in Business Logic** + - Location: CANDAY01 (ACCEPT/DISPLAY throughout) + - Impact: Prevents reusability and automated testing + - Recommendation: Separate I/O from calculation logic + + **Suggested Refactoring:** + ```cobol + Create two programs: + - CANDAY01C (Calculator - uses LINKAGE SECTION) + - CANDAY01I (Interactive wrapper - calls CANDAY01C) + ``` + +2. **No Parameter Passing Interface** + - Location: CANDAY01 (missing LINKAGE SECTION) + - Impact: Cannot be called by other programs + - Recommendation: Add USING clause support + + **Suggested Enhancement:** + ```cobol + PROCEDURE DIVISION USING WS-INPUT-YEAR WS-DAY-NAME. + ``` + +3. **Hard-coded Test Data** + - Location: TESTCDAY (WS-TEST-YEARS with FILLER values) + - Impact: Limited test coverage flexibility + - Recommendation: Read test data from external file or database + +4. **Stub Test Implementation** + - Location: TESTCDAY (TEST-YEAR section) + - Impact: No actual testing occurs + - Recommendation: Implement actual CALL to CANDAY01C + +--- + +## 7. Recommendations + +### 7.1 Immediate Actions (Priority: HIGH) + +1. **Refactor CANDAY01 for Testability** + ``` + Action: Split into two programs + - CANDAY01C.CBLLE (Calculator core with LINKAGE SECTION) + - CANDAY01I.CBLLE (Interactive interface) + + Benefits: + - Enables automated testing via TESTCDAY + - Improves reusability for batch processing + - Maintains backward compatibility via wrapper + ``` + +2. **Complete TESTCDAY Implementation** + ``` + Action: Add CALL statement to invoke CANDAY01C + Example: + CALL 'CANDAY01C' USING WS-TEST-YEAR(WS-INDEX), WS-RESULT-DAY + + Benefits: + - Enables true automated testing + - Validates program behavior programmatically + ``` + +### 7.2 Medium-Term Enhancements (Priority: MEDIUM) + +3. **Create Shared Copybooks** + ``` + Copybooks to Create: + - DAYNAMES.CPY (day-of-week table) + - DATEUTIL.CPY (date calculation fields) + + Benefits: + - Promotes code reuse across holiday programs + - Standardizes date handling + - Reduces maintenance burden + ``` + +4. **Add Error Code Standardization** + ``` + Action: Create ERRCODES.CPY with standard return codes + + Benefits: + - Consistent error handling across modules + - Better integration with calling programs + ``` + +### 7.3 Long-Term Strategy (Priority: LOW) + +5. **Build Holiday Calculation Library** + ``` + Suggested Programs: + - CANDAY01C (Canada Day - already exists) + - USAIND01C (US Independence Day) + - UKTHNKS01C (UK Thanksgiving) + - HOLIDAY-LIB (Service program wrapper) + + Benefits: + - Centralized holiday logic + - Shared by multiple applications + - ILE service program integration + ``` + +6. **External Test Data Management** + ``` + Action: Replace hard-coded test data with file/DB table + + Benefits: + - Flexible test case management + - Easier test maintenance + - Support for regression testing + ``` + +--- + +## 8. Dependency Risk Assessment + +### Risk Matrix + +| Risk Category | Level | Mitigation Status | +|---------------|-------|-------------------| +| Circular Dependencies | 🟢 NONE | N/A - No risk present | +| Missing Dependencies | 🟢 NONE | All intrinsic functions available | +| Tight Coupling | 🟢 LOW | Programs are independent | +| Copybook Chains | 🟢 NONE | No copybooks used | +| Version Conflicts | 🟢 NONE | No shared resources | +| Unreachable Code | 🟢 NONE | All sections are called | + +**Overall Risk Level:** 🟢 **LOW** + +--- + +## 9. Code Quality Metrics + +### Dependency Metrics + +| Metric | CANDAY01 | TESTCDAY | Ideal Range | +|--------|----------|----------|-------------| +| External CALL count | 0 | 0 (should be 1) | 0-3 | +| COPY statement count | 0 | 0 | 2-5 | +| Intrinsic function count | 2 | 0 | 1-5 | +| Afferent coupling (Ca) | 1* | 0 | Varies | +| Efferent coupling (Ce) | 0 | 1* | Varies | +| Instability (Ce/(Ce+Ca)) | 0.0 | 1.0 | 0.3-0.7 | + +\* = Intended dependency, not yet implemented + +### Analysis: +- **CANDAY01** is maximally stable (I=0.0) - good for library module +- **TESTCDAY** is maximally unstable (I=1.0) - appropriate for test driver +- Both programs show healthy separation of concerns + +--- + +## 10. Conclusion + +The Canada Day Calculator module demonstrates **excellent independence** with minimal dependency complexity. The architecture follows a simple test-driven approach with clear separation between the calculator logic (CANDAY01) and test harness (TESTCDAY). + +### Key Strengths: +✅ Zero circular dependencies +✅ Self-contained modules with clear purposes +✅ Modern COBOL intrinsic function usage +✅ Good internal structure with sectioned procedures +✅ Low coupling, high cohesion design + +### Key Opportunities: +⚠️ CANDAY01 needs LINKAGE SECTION for testability +⚠️ TESTCDAY requires implementation of actual CALL logic +⚠️ Potential for copybook creation to support future holiday modules +⚠️ Interactive I/O should be separated from business logic + +### Dependency Health Score: **8.5/10** + +The codebase is in excellent shape from a dependency perspective, with straightforward opportunities for enhancement that would support growth of the holiday calculation subsystem. + +--- + +## Appendix A: Dependency Tree (Full Detail) + +``` +Holiday Calculation Module +│ +├── CANDAY01.CBLLE (Canada Day Calculator) +│ ├── Dependencies: NONE +│ ├── Uses: FUNCTION MOD, FUNCTION INTEGER-OF-DATE +│ ├── I/O: ACCEPT (keyboard), DISPLAY (screen) +│ └── Called By: TESTCDAY (intended) +│ +└── TESTCDAY.CBLLE (Test Program) + ├── Dependencies: CANDAY01 (intended, not implemented) + ├── Uses: None + ├── I/O: DISPLAY (screen) + └── Called By: None (top-level test driver) +``` + +--- + +## Appendix B: Refactoring Example + +### Current State (CANDAY01): +```cobol +PROCEDURE DIVISION. +MAIN-PROCEDURE. + PERFORM GET-YEAR-INPUT. + PERFORM CALCULATE-DAY-OF-WEEK. +``` + +### Recommended State (CANDAY01C - Callable Version): +```cobol +LINKAGE SECTION. +01 LK-INPUT-YEAR PIC 9(4). +01 LK-DAY-NAME PIC X(9). +01 LK-RETURN-CODE PIC S9(4) COMP. + +PROCEDURE DIVISION USING LK-INPUT-YEAR + LK-DAY-NAME + LK-RETURN-CODE. +MAIN-PROCEDURE. + MOVE LK-INPUT-YEAR TO WS-YEAR. + PERFORM CALCULATE-DAY-OF-WEEK. + MOVE WS-DAY-NAME TO LK-DAY-NAME. + MOVE 0 TO LK-RETURN-CODE. + GOBACK. +``` + +### Recommended Test Call (TESTCDAY): +```cobol +01 WS-RETURN-CODE PIC S9(4) COMP. +01 WS-RESULT-DAY PIC X(9). + +PROCEDURE DIVISION. +TEST-YEAR SECTION. + CALL 'CANDAY01C' USING WS-TEST-YEAR(WS-INDEX) + WS-RESULT-DAY + WS-RETURN-CODE. + IF WS-RETURN-CODE = 0 + DISPLAY 'Test passed: ' WS-RESULT-DAY + ELSE + DISPLAY 'Test failed with code: ' WS-RETURN-CODE. +``` + +--- + +**Report Generated By:** COBOL Dependency Analysis Subagent +**Report Version:** 1.0 +**Last Updated:** 2025-07-21