Tutorial: Define Database Access

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.

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.