Skip to content

The call stack consists of two programs: the RPGLE program SA717P and the CLP program SA717C, which work together to build a sales analysis file based on user input. Below, I will identify the use cases implemented by this call stack and then provide a concise function requirement document for a non-interactive version of the primary use case, focusing on business requirements and calculations.

Use Cases Implemented by the Call Stack

The call stack implements the following use cases, derived from the functionality of SA717P and SA717C:

  1. Interactive Sales Analysis Report Generation:
  2. Description: Allows a user to interactively specify a date range and data type ('S' for sales or 'P' for product moves) via a display file (SLS1 format), validates the input, constructs a query selection string, and generates a sales analysis report by calling SA717C to process and query the data.
  3. Inputs:
    • Group identifier (p$fgrp: 'G' or 'Z').
    • Transaction from date (c$trfd).
    • Transaction to date (c$trtd).
    • Data type (c$type: 'S' or 'P').
  4. Process:
    • Validates dates and data type, builds a query string, and calls SA717C to join files and run the SA717Q query.
  5. Output: A sales analysis report generated via the SA717Q query, stored in SA717QRYF.

  6. Key Features:

    • Interactive screen input with error handling for invalid dates or data types.
    • Dynamic file overrides based on group (G or Z).
    • Message subfile for error display.
    • Support for sales or product movement data.

  7. Field Prompting for User Input:

  8. Description: Provides field-level prompting when the user presses F04, allowing them to get assistance with input fields on the SLS1 screen.
  9. Inputs: Cursor location (csrloc) to determine the field being prompted.
  10. Process: Captures cursor position for return after prompting (minimal logic implemented, likely a placeholder for a window or help function).
  11. Output: Updated cursor position for the next screen display.

  12. Key Features:

    • Supports user interaction for field-level assistance.
    • Limited implementation, suggesting future expansion.

  13. Batch Sales Analysis File Creation:

  14. Description: Processes sales or product movement data in a batch mode by joining multiple files (SA5FILD/SA5MOVD, SA5SHP, SHIPTO) based on a query selection string, creating a temporary work file, and running a predefined query (SA717Q) to generate the sales analysis report.
  15. Inputs (from SA717P to SA717C):
    • Group identifier (&P$FGRP: 'G' or 'Z').
    • Query selection string (&QRYSLT).
    • Data type (&P$TYPE: 'S' or 'P').
  16. Process:
    • Selects appropriate files based on group and data type.
    • Copies query format file to QTEMP.
    • Joins files using OPNQRYF, applies the query selection, and outputs results to SA717QRYF.
    • Runs the SA717Q query to produce the report.
  17. Output: Sales analysis report in SA717QRYF.
  18. Key Features:
    • Dynamic file selection based on group and data type.
    • Multi-file join with outer join support (JDFTVAL(*YES)).
    • Error handling for file copy operations.

Function Requirement Document: Batch Sales Analysis File Creation

This function requirement document assumes the primary use case (Batch Sales Analysis File Creation) is implemented as a non-interactive function that takes all required inputs programmatically, rather than through a screen. The document focuses on business requirements, process steps, and necessary calculations.

Function Requirement Document: Batch Sales Analysis File Creation

Overview

The Batch Sales Analysis File Creation function generates a sales analysis report by processing sales or product movement data based on provided inputs. It joins multiple database files, applies a query selection string, and produces a report using a predefined query (SA717Q). The function operates non-interactively, taking all inputs as parameters.

Business Requirements

  1. Input Parameters:
  2. Group Identifier (group_id, 1 character): Specifies the dataset group ('G' for production, 'Z' for development).
  3. Query Selection String (query_selection, 1024 characters): Defines the data filter (e.g., excluding deleted records, specific freight/carrier codes, date range).
  4. Data Type (data_type, 1 character): Specifies the data to process ('S' for sales, 'P' for product moves).
  5. Transaction From Date (tran_from_date, 8 digits, CCYYMMDD): Start date of the transaction range.

  6. Transaction To Date (tran_to_date, 8 digits, CCYYMMDD): End date of the transaction range.

  7. Output:

  8. A sales analysis report stored in the SA717QRYF file, accessible via the library list (*LIBL).

  9. The report is generated by the SA717Q query in the GSSQRY library.

  10. Business Rules:

  11. The function must support two datasets:
    • G group: Uses files in the DATA library (GSA5FILD, GSA5SHP, GSHIPTO).
    • Z group: Uses files in the DATADEV library (ZSA5FILD, ZSA5SHP, ZSHIPTO).
  12. Data type determines the primary file:
    • S: Uses SA5FILD (sales data).
    • P: Uses SA5MOVD (product movement data).
  13. The query selection string must include conditions to:
    • Exclude deleted records (SADEL *NE "D").
    • Filter by freight codes (SHFRCD *NE "C") and carrier codes (SHCACD *EQ %VALUES("TT" "RC" "MC" "SL")).
    • Apply a date range on SAIND8 if provided.
  14. Dates must be valid (CCYYMMDD format) and tran_from_date must not be greater than tran_to_date.
  15. Joins must match records across files on company (SACO/SHCO/CSCO), customer (SACUST/SHCUST/CSCUST), invoice (SAINV/SHINV), order (SAORD/SHORD), and ship-to (SASHIP/CSSHIP).
  16. Use outer joins (JDFTVAL(*YES)) to include records with missing join matches.
  17. Overwrite the output file SA717QRYF with each execution.

Process Steps

  1. Validate Inputs:
  2. Ensure group_id is 'G' or 'Z'. If invalid, return error code ERR_INVALID_GROUP.
  3. Ensure data_type is 'S' or 'P'. If invalid, return error code ERR_INVALID_TYPE.
  4. Validate tran_from_date and tran_to_date using a date validation routine (e.g., equivalent to GSDTEDIT).
    • Dates must be in CCYYMMDD format.
    • If tran_from_date > tran_to_date, return error code ERR_INVALID_DATE_RANGE.

  5. Verify query_selection is non-empty and properly formatted for OPNQRYF.

  6. Determine File Names:

  7. Set primary file (file01):
    • If data_type = 'S', file01 = group_id + SA5FILD (e.g., GSA5FILD).
    • If data_type = 'P', file01 = group_id + SA5MOVD (e.g., GSA5MOVD).
  8. Set secondary file (file02): group_id + SA5SHP (e.g., GSA5SHP).

  9. Set tertiary file (file03): group_id + SHIPTO (e.g., GSHIPTO).

  10. Copy Query Format File:

  11. Copy SA717QF to QTEMP/SA717QF:
    • If group_id = 'G', source from DATA/SA717QF.
    • If group_id = 'Z', source from DATADEV/SA717QF.
  12. Use MBROPT(*REPLACE) and CRTFILE(*YES).

  13. Handle copy errors (e.g., CPF2817) gracefully.

  14. Execute Query:

  15. Override SA717QF to file01 with SHARE(*YES).
  16. Perform an open query (OPNQRYF) joining file01, file02, and file03:
    • Use query_selection for filtering.
    • Sort by SACO (company), SACUST (customer), SASHIP (ship-to).
    • Apply join conditions (see Business Rules).
    • Output to format SA717QF with JDFTVAL(*YES).

  17. Copy query results to SA717QRYF using CPYFRMQRYF with MBROPT(*REPLACE).

  18. Run Report Query:

  19. Execute the GSSQRY/SA717Q query to process SA717QRYF and generate the sales analysis report.

  20. Cleanup:

  21. Close the open query file.
  22. Delete all file overrides.

Calculations

  • Date Validation:
  • Use a date validation routine (e.g., equivalent to GSDTEDIT) to convert and validate tran_from_date and tran_to_date from CCYYMMDD format.
  • Ensure tran_from_date ≤ tran_to_date to form a valid range.
  • Query Selection String:
  • If tran_from_date and tran_to_date are non-zero, append a date range condition to query_selection: SAIND8 *EQ %RANGE(tran_from_date tran_to_date).
  • Combine with static conditions: (SADEL *NE "D") *AND (SHFRCD *NE "C") *AND (SHCACD *EQ %VALUES("TT" "RC" "MC" "SL")).
  • File Name Construction:
  • Concatenate group_id with file suffixes (SA5FILD, SA5MOVD, SA5SHP, SHIPTO) to form file names.

Error Handling

  • Return error codes for invalid inputs (ERR_INVALID_GROUP, ERR_INVALID_TYPE, ERR_INVALID_DATE_RANGE).
  • Handle file copy errors (CPF2817) by logging and continuing execution.
  • Ensure cleanup (file close, override deletion) even if errors occur.

Dependencies

  • Files:
  • SA717QF (format file in DATA or DATADEV).
  • GSA5FILD, ZSA5FILD, GSA5MOVD, ZSA5MOVD (primary data files).
  • GSA5SHP, ZSA5SHP (shipment files).
  • GSHIPTO, ZSHIPTO (ship-to files).
  • SA717QRYF (output file in *LIBL).
  • Query: GSSQRY/SA717Q.
  • System APIs: CPYF, OPNQRYF, CPYFRMQRYF, RUNQRY, CLOF, DLTOVR.

Assumptions

  • The SA717Q query is predefined and correctly configured to process SA717QRYF.
  • Input dates are in CCYYMMDD format.
  • The library list (*LIBL) contains the necessary libraries for output files.

Notes

  • The primary use case (Batch Sales Analysis File Creation) was chosen for the function requirement document because it encapsulates the core functionality of SA717C and the data processing initiated by SA717P. The interactive use case was not selected, as the requirement specifies a non-interactive function.
  • The field prompting use case is minor and underdeveloped in the original code, so it was not prioritized for the function requirements.
  • The document is concise, focusing on business requirements and necessary calculations, while maintaining technical accuracy for the IBM i environment. If you need a function requirement document for another use case or additional details, let me know!