Tutorial: Define Database Access

Define database calls and customize database access.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

An Online Express database call defines which record(s) or table(s) to read, and which database actions to perform on them. Each field action that you specify in the Action/Event Editor requires a corresponding database action that defines the field action.

Requirements

Before attempting this tutorial, you must complete:

If you have closed Enterprise Developer, start it; then open the AppMaster Builder perspective and, from the Project Explorer, double-click the BLDRUPD program to start Online Express.

Assign a database call
  1. From Online Express, click File > Database Access. The Database Access Summary dialog box appears. The dialog box is initially blank. From here you access other dialog boxes to define the database call specifications.
  2. Click Edit > Create. The Attributes dialog box appears. Here, you can view or override attributes of the call.
  3. Click OK to accept all default attributes. The Record Selection dialog box appears, showing the record name, PART-MASTER-REC, defined in the APSUPD data view.
  4. To define a call to the record that enables end users to obtain data, modify data, or delete data, check Obtain, Modify, and Erase.
  5. Click Next. The Add/Delete Fields for Qualification dialog box appears, showing PART-MASTER-REC in the Record Name field and PM-PART-NBR in the Cobol Name field.
  6. Click Select All to activate the PART-MASTER-REC record.
  7. Click Next. The Qualification dialog box appears with the Record and Field names supplied from the action just completed.
    Note: The = operator indicates that the values for the fields in the Field and Value fields must match. Therefore, the value that the end user enters into the PART-NBR field on the Parts Update screen must be equal to a part number in the database record.
  8. Click Finish. This returns you to the Database Access Summary window, which now shows the database access call defined for this program. The OME in the Actions field indicates that this program can Obtain, Modify, and Erase PART-MASTER-REC records.
Set database call generation options
We need to set the Online Express generation options to make sure that the MFG generates the database call and code to then clear the screen.
  1. Click File > Express Generation Options. The Express Generation Options dialog box appears.
  2. On the Express Generation Options dialog box, be sure the following options are checked or selected:
    Generate Control Point Comments
    Generates comments in programs identifying control events.
    Generate Database calls
    Generates your database access specifications into database calls. When testing the program teleprocessing functions without accessing a database, you can deactivate this option to suppress the generation of database calls.
    Clear Screen with Spaces
    Clears all screen entry fields with spaces.
  3. On the System Message Field drop-down list, click SYSTEM. This sets the SYSTEM field as the system message field.
  4. Click OK. This returns you to the Database Access Summary window.
Define Obtain normal status
We now need to customize the Obtain database call event to:
  • Move the information in the VSAM database record to the appropriate Working-Storage fields
  • Call the Customizer user rule we coded in a previous tutorial
  • Move the information calculated by the user rule to its appropriate screen field
  1. Click Database Access > Call Tailoring. The DB Call Tailoring Browser appears.
  2. On the Database Actions list, double-click Obtain. The DB Call Tailoring Editor appears.
  3. In the Events column, click Normal Status.
  4. On the Action drop-down list, click Local Code.
  5. Click Edit Code. The default editor appears.
    Note: If prompted to create a file, click No.
  6. Type in the following code, starting in column 12:
               MOVE PART-MASTER-REC TO WS-MASTER-RECORD
               CALC-INV-VALUE WS BASE-PRICE
               ... UNITS-INSTOCK
               MOVE WS-INVENTORY-VALUE TO BLDRCU-INV-VALUE

    The second and third lines of this code call the CALCINV Customizer rule and supply its three required parameters. CALC-INV-VALUE is the name of the rule, WS is the value for the &PRE parameter, and BASE-PRICE and UNITS-INSTOCK are the values for &PRICE-FIELD and &UNITS-FIELD respectively. This code expands into the following native COBOL:

               IF WS-BASE-PRICE = ZERO
                    OR WS-UNITS-INSTOCK = ZERO
                   MOVE ZERO TO WS-INVENTORY-VALUE
               ELSE
                   COMPUTE WS-INVENTORY-VALUE =
                       WS-BASE-PRICE
                       * WS-UNITS-INSTOCK
    
  7. To save your source code, click File > Save.
  8. Close the editor. The DB Call Tailoring Editor reappears, showing the value PAINTED in the Argument field.
  9. Click Apply.
  10. To close the Database Call Tailoring Editor, click the x icon in the upper right corner of the dialog box. This returns you to the Database Call Tailoring Browser.
Define Obtain error status
To further customize the Obtain call, we define its error status:
  • Override the standard error message for the Obtain call with a text message
  • Provide code that clears the screen fields when an error is encountered
  • Ensure that the program aborts when it encounters an error
  1. In the Events column of the DB Call Tailoring Editor, click Error Status.
  2. On the Action drop-down list, click Local Code.
  3. Click Edit Code. The default editor appears.
    Note: If prompted to create a file, click No.
  4. To clear the screen fields, type the following native COBOL code, starting each MOVE statement in column 12.
                MOVE SPACES TO BLDRCU-SHORT-DESC-INPT 
                MOVE SPACES TO BLDRCU-UNITS-INSTOCK-INPT
                MOVE SPACES TO BLDRCU-BASE-PRICE-INPT 
                MOVE SPACES TO BLDRCU-DIMENSIONS-INPT
    
  5. To save your source code, click File > Save.
  6. Close the editor. The DB Call Tailoring Editor reappears, showing the value PAINTED in the Argument field.
  7. In the Error Message entry field, type Part number entered not found.
  8. To indicate that the error message is text, click Text on the Error Message Type drop-down list.
  9. Ensure that Abort On Error is checked (default).
  10. Click Apply.
  11. To close the Database Call Tailoring Editor, click the x icon in the upper right corner of the dialog box. This returns you to the Database Call Tailoring Browser.
Define Modify before access
Here, we provide local code for the Modify call that ensures data is populated into the proper fields.
  1. On the Database Actions list, double-click Modify. The DB Call Tailoring Editor appears.
  2. In the Events column, click Before Access.
  3. On the Action drop-down list, click Local Code.
  4. Click Edit Code. The default editor appears.
    Note: If prompted to create a file, click No.
  5. Type in the following code, starting in column 12:
               PM-SHORT-DESC = WS-SHORT-DESC
               PM-UNITS-INSTOCK = WS-UNITS-INSTOCK
               PM-BASE-PRICE = WS-BASE-PRICE
               PM-DIMENSIONS = WS-DIMENSIONS
  6. To save your source code, click File > Save.
  7. Close the editor.
  8. On the DB Call Tailoring Editor, click Apply.
  9. Close the DB Call Tailoring Editor. The DB Call Tailoring Browser reappears, showing a summary of the database call customization.
  10. Close the Database Call Tailoring Browser and the Database Access Summary dialog box.
Note: The Erase call requires no tailoring because the default logic supplied by AMB for each is sufficient for the purposes of our sample application.
Assign a savekey
Finally, we define database access for the savekey field we painted on the BLDRCU screen.
  1. Click File > Savekey Specification. The Express Savekey Data dialog box appears.
  2. From the Non Repeated Savekey list box, click SAVEKEY.
  3. Click OK. This returns you to the Action/Event Browser.
  4. Close Online Express.
  5. Click Yes to save your changes. This returns you to the AppMaster Builder perspective.

This completes the tutorial. Next, please complete Tutorial: Generate and Compile the Application.