How to Code an Update Application

Terminal Management › Using Pageable Maps › How to Code an Update Application

How to Code an Update Application

To write a pageable map application that allows the user to update map data fields, establish a retrieval program and an update program.

Retrieval Program

The retrieval program initiates the pageable map update session and retrieves and displays the data. This program can be similar to the one displayed in How to Code a Browse Application. You should make the following changes to the retrieval program:

Specify one of the following options of the STARTPAGE statement:
- WAIT causes your program to acquire control after every update paging request and after every nonpaging request.
- RETURN causes your program to acquire control after every paging request (update or nonupdate) and every nonpaging request.
Note: Because of editing and error-handling considerations, updating pageable maps by using a paging type of NOWAIT is not recommended.
Use the KEY IS parameter of the MAP OUT DETAIL statement to pass the db-key of each retrieved record:
```
MAP OUT USING DCTEST01
    DETAIL NEW
    KEY IS DBKEY.
```
Including the db-key in this manner allows for DB-KEY retrieval in subsequent tasks.
Code a DC RETURN statement that indicates the pageable map update program to be invoked when the user presses a control key.

Update Program

The update program retrieves modified detail occurrences and updates the database. In this program, perform the following steps:

Establish a switch in variable storage. This switch should be set on if your program encounters any invalid data in modified detail occurrences.
Issue mapping mode housekeeping statements, as explained in Housekeeping.
Issue a MAP IN HEADER statement that includes the PAGE option. You can use the PAGE value later in your program when determining the next page to map out.
Issue an INQUIRE MAP statement to determine what control key was pressed. The control key pressed by the user can specify:
- The flow of control. You can associate certain control keys with specific functions (for example, Clear might always exit the application).
- The next page to be displayed. The user can indicate the next page to be displayed by pressing a site-standard paging control key.
- A user error. If the user presses an invalid control key, you should redisplay the current page.
Perform the following steps iteratively until all modified detail occurrences have been mapped in:
1. Issue a MAP IN DETAIL statement that includes the RETURNKEY parameter.
2. Check for a status of 4668 (DC-NO-MORE-UPD-DETAILS). If 4668 is returned, all updated details have been returned and you should display the pageable map, as specified by the user. If 4668 is not returned, perform the IDMS-STATUS routine.
3. Perform error and range checking to ensure that the user entered valid data. If invalid data is found, set the error switch and issue a MAP OUT DETAIL CURRENT statement that includes a message that indicates the error.
4. Perform database retrieval to access the database record to be modified. Retrieve the record by using its db-key (acquired from the RETURNKEY parameter). If data cannot be retrieved, set the error switch and issue a MAP OUT DETAIL CURRENT statement that includes a message that indicates the error.
5. Move data from the work record to the database record.
6. Issue database modification statements.
7. After all modified detail occurrences have been successfully processed, issue a MAP OUT RESUME statement that specifies the page requested by the user. If errors were encountered in the MAP IN DETAIL processing, you should redisplay the current page so the operator can correct the invalid data.

Ending the Update Session

The next task specified in the DC RETURN NEXT TASK CODE statement should include logic that tests to see if the user has indicated the end of the map paging session. If so, issue an ENDPAGE SESSION statement.

Example of an Update Application

The program excerpt below shows a pageable map update application. The program contains paging logic that works with a paging type of either WAIT or RETURN.

After determining user specifications, the program issues MAP IN DETAIL statements iteratively, modifying the database as specified, until all modified detail occurrences are processed.

 DATA DIVISION
 WORKING-STORAGE SECTION.
 01  RETURN-DBKEY            PIC S9(8) COMP.
 01  DEPTMOD                 PIC X(8) VALUE 'DEPTMOD'.
 01  FIRST-PAGE-SW           PIC X    VALUE 'N'.
        88 LESS-THAN-A-PAGE  VALUE 'N'.
 01  MAP-IN-ERR-SW           PIC X    VALUE 'N'.
        88 MAP-IN-ERR        VALUE 'Y'.
 01  PAGE-INDICATOR.
     05 SPEC-PAGE            PIC S9(8) COMP.
 01  MESSAGES.
     05 EDIT-ERR-MESS           PIC X(21)
        VALUE 'CORRECT INVALID INPUT'.
     05 EDIT-ERR-MESS-END       PIC X.
*
     05 EMP-NOT-FOUND-MESS      PIC X(18)
        VALUE 'EMPLOYEE NOT FOUND'.
     05 EMP-NOT-FOUND-MESS-END  PIC X.
 01  DC-AID-CONDITION-NAMES.
      03  DC-AID-IND-V           PIC X.
                             88  ENTER-HIT VALUE QUOTE.
                             88  CLEAR-HIT VALUE '_'.
                             88  PF01-HIT VALUE '1'.
                             88  PF02-HIT VALUE '2'.
                             88  PF03-HIT VALUE '3'.
                             88  PF04-HIT VALUE '4'.
                             88  PF05-HIT VALUE '5'.
                             88  PF06-HIT VALUE '6'.
                             88  PF07-HIT VALUE '7'.
                             88  PF08-HIT VALUE '8'.
                             88  PF09-HIT VALUE '9'.
                             88  PF10-HIT VALUE ':'.
                             88  PF11-HIT VALUE '#'.
                             88  PF12-HIT VALUE '@'.
                             88  PF13-HIT VALUE 'A'.
                             88  PF14-HIT VALUE 'B'.
                             88  PF15-HIT VALUE 'C'.
                             88  PF16-HIT VALUE 'D'.
                             88  PF17-HIT VALUE 'E'.
                             88  PF18-HIT VALUE 'F'.
                             88  PF19-HIT VALUE 'G'.
                             88  PF20-HIT VALUE 'H'.
                             88  PF21-HIT VALUE 'I'.
                             88  PF22-HIT VALUE '_'.
                             88  PF23-HIT VALUE '.'.
                             88  PF24-HIT VALUE '>'.
                             88  PA01-HIT VALUE '%'.
                             88  PA02-HIT VALUE '<'.
                             88  PA03-HIT VALUE ','.
                             88  PEN-ATTN-SPACE-NULL VALUE '='.
                             88  PEN-ATTN VALUE QUOTE.
 01  MAP-WORK-REC.
     05 WORK-EMP-ID           PIC X(4).
     05 WORK-FIRST            PIC X(10).
     05 WORK-LAST             PIC X(15).

 PROCEDURE DIVISION.
     BIND MAP DCTEST01.
     BIND MAP DCTEST01 RECORD MAP-WORK-REC.
     MOVE 'N' TO MAP-IN-ERR-SW.
*** MAP IN HEADER AND PAGE FIELD ***
     MAP IN USING DCTEST01
         HEADER
         PAGE IS SPEC-PAGE
         ON DC-DETAIL-NOT-FOUND
            NEXT SENTENCE.
*** DETERMINE THE PF-KEY PRESSED ***
     INQUIRE MAP DCTEST01 MOVE AID TO DC-AID-IND-V.
     IF PA01-HIT
         ENDPAGE
         DC RETURN.
*** CHECK FOR HEADER ERRORS, MAP OUT IF ANY ARE FOUND ***
     INQUIRE MAP DCTEST01
        IF ANY EDIT IS ERROR
          THEN
            MODIFY MAP DCTEST01 TEMPORARY
                 FOR ALL ERROR FIELDS
                 ATTRIBUTES BRIGHT
            MAP OUT USING DCTEST01 RESUME
            DC RETURN NEXT TASK CODE DEPTMOD.
*
     COPY IDMS SUBSCHEMA-BINDS.
     READY ORG-DEMO-REGION USAGE-MODE IS UPDATE.
     READY EMP-DEMO-REGION USAGE-MODE IS UPDATE.
*
     PERFORM A100-MAP-IN-DETAILS THRU A100-EXIT
            UNTIL DC-NO-MORE-UPD-DETAILS.
     FINISH.
*** PAGING ROUTINES FOLLOW                         ***
*** IF ERROR SWITCH IS SET, REDISPLAY CURRENT PAGE ***
     IF MAP-IN-ERR
       THEN
         MAP OUT USING DCTEST01
             RESUME PAGE IS CURRENT
         DC RETURN NEXT TASK CODE DEPTMOD.
*** IF PF07, DISPLAY PRIOR PAGE ***
     IF PF07-HIT
       THEN
        MAP OUT USING DCTEST01
             RESUME PAGE IS PRIOR
        DC RETURN NEXT TASK CODE DEPTMOD.
.hr left right

*** IF PF08, DISPLAY NEXT PAGE ***
     IF PF08-HIT
       THEN
        MAP OUT USING DCTEST01
            RESUME PAGE IS NEXT
        DC RETURN NEXT TASK CODE DEPTMOD.
*** ELSE, USE PAGE VALUE FROM MAP IN HEADER ***
     MAP OUT USING DCTEST01
         RESUME PAGE IS SPEC-PAGE.
     DC RETURN NEXT TASK CODE DEPTMOD.
 A100-MAP-IN-DETAILS.
*** MAP IN EACH MODIFIED DETAIL.  EXIT   ***
*** WHEN NO MORE MODIFIED DETAILS REMAIN ***
     MAP IN USING DCTEST01
        DETAIL
        RETURNKEY IS RETURN-DBKEY
        ON DC-NO-MORE-UPD-DETAILS GO TO A100-EXIT.
*** IF ERROR, MAP OUT DETAIL WITH MESSAGE, SET SWITCH ***
     INQUIRE MAP DCTEST01
        IF ANY EDIT IS ERROR
          THEN
            MODIFY MAP DCTEST01 TEMPORARY
                 FOR ALL ERROR FIELDS
                 ATTRIBUTES BRIGHT
            MAP OUT USING DCTEST01
                MESSAGE IS EDIT-ERR-MESS
                        TO EDIT-ERR-MESS-END
                DETAIL CURRENT
                KEY IS RETURN-DBKEY
            MOVE 'Y' TO MAP-IN-ERR-SW
        GO TO A100-EXIT.
*** RETRIEVE EMPLOYEE, USING DBKEY FROM RETURNKEY ***
     OBTAIN EMPLOYEE DB-KEY IS RETURN-DBKEY
                 ON ANY-STATUS NEXT SENTENCE.
*** IF ERROR, MAP OUT DETAIL WITH MESSAGE, SET SWITCH ***
     IF DB-REC-NOT-FOUND
        MAP OUT USING DCTEST01
            MESSAGE IS EMP-NOT-FOUND-MESS
                    TO EMP-NOT-FOUND-MESS-END
                  DETAIL CURRENT
                  KEY IS RETURN-DBKEY
        MOVE 'Y' TO MAP-IN-ERR-SW
        GO TO A100-EXIT
     ELSE
        PERFORM IDMS-STATUS.
*
     MOVE WORK-FIRST  TO EMP-FIRST-NAME-0415.
     MOVE WORK-LAST   TO EMP-LAST-NAME-0415.
     MOVE WORK-EMP-ID TO EMP-ID-0415.
     MODIFY EMPLOYEE.
 A100-EXIT.
     EXIT.