Skip to content

AR915 RPGLE

The RPGLE program AR915 is a customer form type contacts maintenance and inquiry program within the Customer Master Information system. It is called from the main program AR915P (as seen in the previous document) to handle the creation, updating, or displaying of individual customer form type contact records. The program supports both maintenance (MNT) and inquiry (INQ) modes, providing a user interface to manage contact details such as form type, contact name, email, and various flags. Below is a detailed explanation of the process steps, business rules, database tables used, and external programs called.

Process Steps of the AR915 Program

The AR915 program follows a structured flow to manage a single customer form type contact record through a display file interface. The process steps are organized by the main subroutines:

  1. Program Initialization (*inzsr):
  2. Purpose: Initializes variables, defines key lists, and processes input parameters.

  3. Actions:

    • Defines the parameter list for receiving input parameters: p$cono (company), p$seq# (sequence number), p$cust (customer), p$mode (run mode: 'MNT' or 'INQ'), p$fgrp (file group: 'Z' or 'G'), and p$flag (return flag).
    • Moves input parameters to display file fields (f$cono, f$seq#) and initializes output parameters (o$fgrp, o$mode, o$flag).
    • Defines key lists (klcufm, klcust, klfrmtyp) for database operations.
    • Initializes work fields, message handling fields, and date validation parameters.
    • Sets up the display file fields and headers based on the mode (MNT or INQ).

  4. Open Database Tables (opntbl):

  5. Purpose: Opens the required database files with appropriate overrides based on the file group (p$fgrp).

  6. Actions:

    • Checks if p$fgrp is 'G' or 'Z' to apply the correct file overrides (ovg or ovz) using the QCMDEXC command.
    • Opens files arcust, gstabl, arcufm, and bicont with user-controlled open (usropn).

  7. Retrieve Data for Passed Parameters (rtvdta):

  8. Purpose: Retrieves data for the provided company, sequence number, and customer to populate the display file fields.

  9. Actions:

    • Chains to arcufm using klcufm (company, sequence number) to retrieve the contact record; if not found (*in99), clears the record and sets fmcust to p$cust.
    • Sets w$exists to indicate whether the record exists.
    • Chains to bicont to validate the company code (f$cono); clears bcname if not found.
    • Chains to arcust to validate the customer code (fmcust); clears arname if not found.
    • Sets the display header (c$hdr1) and protection indicator (*in70) based on p$mode ('MNT' for maintenance, 'INQ' for inquiry).

  10. Process Panel Formats (srfmt):

  11. Purpose: Manages the main loop for displaying and processing the panel format (fmt01).

  12. Actions:

    • Clears the screen (clrscr).
    • Initializes the panel format (f01mov) and sets the format name to FMT01.
    • Enters a loop (fmtagn) that:
    • Displays the message subfile if needed (wrtmsg) or clears the screen.
    • Displays the fmt01 format using exfmt and clears error indicators (*in50-*in69).
    • Processes user input via f01sr.
    • Clears the message subfile (clrmsg) if displayed.
    • Continues until fmtagn is turned off (e.g., via F12 or inquiry mode completion).

  13. Process Format (f01sr):

  14. Purpose: Handles user input for the fmt01 format based on function keys or ENTER.

  15. Actions:

    • Processes function keys:
    • F04: Calls the prompt subroutine for field prompting.
    • F10: Resets the cursor position (row, col) to home.
    • F12: Exits the program by setting fmtagn to off.
    • In inquiry mode (p$mode = 'INQ'), determines the next format (f01nxt) and exits.
    • For ENTER, validates input (f01edt) and, if no errors (*in50 = *off), updates the database (upddbf) in maintenance mode and determines the next format (f01nxt).

  16. Determine Next Format (f01nxt):

  17. Purpose: Decides whether to continue or exit the panel loop.

  18. Actions:

    • If no input change occurred (*in19 = *off), sets fmtagn to off to exit the loop.
    • Note: The subroutine is prepared to handle a second format (FMT02), but it is commented out, so the program only uses FMT01.

  19. Edit Format Input (f01edt):

  20. Purpose: Validates user input fields in maintenance mode.

  21. Actions:

    • Validates form type code (fmfmty) by chaining to gstabl using klfrmtyp; if valid and not deleted, sets f$fmty to the description; else, adds error message ERR0010 and sets *in50, *in51.
    • Checks if contact name (fmcntc) is non-blank; if blank, adds error message ERR0012 and sets *in50, *in52.
    • Validates send original flag (fmfmyn), reprint flag (fmrpyn), mail flag (fmmlyn), and back terms flag (fmbkyn); each must be 'Y' or 'N', else adds error message ERR0014 and sets *in50, *in55-*in58 as appropriate.
    • Validates email address (fmemla):
    • As of the 08/30/22 revision (JK01), fax number validation is removed.
    • If fmemla is non-blank, calls VALMAILID to validate the email; if invalid (p$valid = 'N'), adds error message ERR0000 with com(02) ("Invalid Email Address Entered") and sets *in50, *in53.
    • Allows blank email if fmfmyn = 'N' (no original sent).
    • In inquiry mode (p$mode = 'INQ'), clears error indicators and messages.

  22. Initialize Format Field Values (f01mov):

  23. Purpose: Initializes the fmt01 format fields and clears any prior errors.

  24. Actions:

    • Calls f01edt to validate fields.
    • If errors exist (*in50), clears error indicators and messages (clrmsg).

  25. Format Protection Schemes (f01pro):

  26. Purpose: Sets field protection indicators based on the mode.

  27. Actions:

    • Clears protection indicators (*in70-*in74).
    • In inquiry mode (p$mode != 'MNT'), sets *in70-*in73 to protect fields.
    • Note: Protection for existing records (w$exists) is commented out, so key fields are not protected based on record existence.

  28. Update Database Files (upddbf):

    • Purpose: Updates or creates a record in arcufm in maintenance mode.
    • Actions:
    • If f$seq# is zero, retrieves the next sequence number (rtvnxtseq).
    • Saves the current arcufm record fields to svds.
    • Chains to arcufm using klcufm:
      • If found (*in80 = *off), updates the record if changes exist (svds != wkds01) and sets p$flag = '1'.
      • If not found, creates a new record with f$cono and f$seq#, writes to arcufm, and sets p$flag = '1'.
    • Sets w$exists to indicate the record now exists.

  29. Retrieve Next Sequence Number (rtvnxtseq):

    • Purpose: Generates the next sequence number for a new arcufm record.
    • Actions:
    • Chains to bicont to get the current sequence number (bcseqn).
    • Increments f$seq# until a unique value is found by checking arcufm with klcufm.
    • Increments bcseqn in bicont and updates the record.

  30. Field Prompting (prompt):

    • Purpose: Provides lookup functionality for the form type field.
    • Actions:
    • If the cursor is on FMFMTY and input is not protected (*in70), calls LGSTABL to prompt for a form type code.
    • Updates fmfmty with the selected value if non-blank.
    • Sets *in19 to indicate a panel format change.

  31. Message Handling (addmsg, wrtmsg, clrmsg):

    • Purpose: Manages error and confirmation messages displayed in the message subfile.
    • Actions:
    • addmsg: Sends messages to the program message queue using QMHSNDPM with message ID, file, data, and type.
    • wrtmsg: Writes the message subfile control (msgctl) with *in49 on.
    • clrmsg: Clears the message subfile using QMHRMVPM and restores the current record format and page number.

  32. Program Termination:

    • Purpose: Closes files and exits.
    • Actions:
    • Closes all open files (close *all).
    • Sets *inlr to *on and returns control to the calling program (AR915P).

Business Rules

The program enforces the following business rules during input validation and processing: 1. Form Type Code (fmfmty): - Must exist in the gstabl file with type FRMTYP and not be marked deleted (tbdel != 'D'). - If invalid, displays error ERR0010 and sets error indicators.

  1. Contact Name (fmcntc):
  2. Must be non-blank.

  3. If blank, displays error ERR0012 and sets error indicators.

  4. Email Address (fmemla):

  5. As of the 08/30/22 revision, fax number validation is removed, and email is the primary contact method.
  6. If non-blank, must be valid as determined by the VALMAILID program (p$valid = 'Y').
  7. If invalid, displays error ERR0000 with message "Invalid Email Address Entered".

  8. Can be blank if fmfmyn = 'N' (no original sent); otherwise, a non-blank email is required if fmfmyn is 'Y' or blank.

  9. Flags (fmfmyn, fmrpyn, fmmlyn, fmbkyn):

  10. Each flag (send original, reprint, mail, back terms) must be 'Y' or 'N'.

  11. If invalid, displays error ERR0014 and sets corresponding error indicators (*in55-*in58).

  12. Mode-Based Behavior:

  13. In maintenance mode (p$mode = 'MNT'), fields are editable, and updates are written to arcufm.
  14. In inquiry mode (p$mode = 'INQ'), fields are protected (*in70-*in73), errors are cleared, and no database updates occur.

  15. The display header changes based on the mode: "Customer Form Type Contacts Maintenance" for MNT, "Customer Form Type Contacts Inquiry" for INQ.

  16. Sequence Number Generation:

  17. For new records (f$seq# = 0), the next sequence number is retrieved from bicont (bcseqn) and incremented until a unique value is found in arcufm.

  18. The bicont record is updated with the new sequence number.

  19. Database Updates:

  20. In maintenance mode, updates or creates records in arcufm only if input validation passes.

  21. Sets p$flag = '1' to indicate a successful update or creation.

  22. Field Prompting:

  23. The form type code (fmfmty) can be prompted via F04, calling LGSTABL to select a valid value.

Database Tables Used

The program uses the following database files, all opened with usropn: 1. arcust: - Purpose: Customer master file for validating customer codes. - Usage: Chained to using klcust (company, customer) to retrieve arname (customer name). - Access: Input only, keyed (k disk). - Override: garcust (for 'G' file group) or zarcust (for 'Z' file group).

  1. gstabl:
  2. Purpose: General table file for validating form type codes.
  3. Usage: Chained to using klfrmtyp (type FRMTYP, code fmfmty) to retrieve tbdesc (description).
  4. Access: Input only, keyed (k disk).

  5. Override: ggstabl (for 'G') or zgstabl (for 'Z').

  6. arcufm:

  7. Purpose: Primary file for customer form type contact records.
  8. Usage: Chained to for retrieving records (klcufm), updated, or written to in maintenance mode.
  9. Access: Update and add, keyed (uf a e k disk).

  10. Override: garcufm (for 'G') or zarcufm (for 'Z').

  11. bicont:

  12. Purpose: Company master file for validating company codes and managing sequence numbers.
  13. Usage: Chained to for validating f$cono and retrieving bcname; updated to increment bcseqn for new records.
  14. Access: Update, keyed (uf e k disk).

  15. Override: gbicont (for 'G') or zbicont (for 'Z').

  16. ar915d:

  17. Purpose: Display file for the user interface.
  18. Usage: Contains the fmt01 format and message subfile control (msgctl) for interactive display and input.
  19. Access: Work station file (cf e workstn).

External Programs Called

The program interacts with the following external programs: 1. LGSTABL: - Called in subroutine prompt. - Parameters: k$ft (table type, set to FRMTYP), k$fmty (form type code), o$fgrp (file group). - Purpose: Provides a lookup window for selecting a valid form type code.

  1. VALMAILID:
  2. Called in subroutine f01edt (added in 08/30/22 revision).
  3. Parameters: p$email (email address, 100 characters), p$valid (validity flag, 'Y' or 'N').

  4. Purpose: Validates the email address entered in fmemla.

  5. QCMDEXC:

  6. Called in subroutine opntbl.
  7. Parameters: dbov## (override command), dbol## (command length).

  8. Purpose: Executes file override commands for arcust, gstabl, arcufm, and bicont.

  9. QMHSNDPM:

  10. Called in subroutine addmsg.
  11. Parameters: m@id (message ID), m@msgf (message file), m@data (message data), m@l (message length), m@type (message type), m@pgmq (program message queue), m@scnt (stack counter), m@key (message key), m@errc (error code).

  12. Purpose: Sends messages to the program message queue.

  13. QMHRMVPM:

  14. Called in subroutine clrmsg.
  15. Parameters: m@pgmq (program message queue), m@scnt (stack counter), m@rmvk (message key), m@rmv (remove option), m@errc (error code).
  16. Purpose: Removes messages from the program message queue.

Summary

The AR915 program, called by AR915P, provides a detailed interface for maintaining or inquiring about customer form type contact records. It supports creating new records, updating existing ones, and displaying details in a single-panel format (fmt01). The program enforces strict validation rules for form type, contact name, email, and flags, with email validation introduced in the 08/30/22 revision. It uses four database files (arcust, gstabl, arcufm, bicont) with dynamic overrides and interacts with external programs for field prompting and email validation. The program ensures data integrity through comprehensive input validation and provides user feedback via a message subfile.