Modifying Data

In this section:

With the FOCUS MODIFY and Maintain facilities, you can add new records to a data source, update field values for specific records, or delete specific records.

The data adapter processes a MODIFY or Maintain transaction with the following steps:

  1. FOCUS reads the transaction for incoming data values.
  2. The data adapter generates the appropriate calls to Adabas based on the MATCH or NEXT criteria.
  3. Adabas either returns an answer set consisting of one or more records that satisfy the request, or determines that the record does not exist.
  4. After Adabas returns the answer set and/or return code, the data adapter either
  5. Adabas changes the database appropriately.

In MODIFY, you must use the NEXT command to process a multi-record answer set one record at a time. Each NEXT command puts you physically at the next logical record in the answer set created by the most recent MATCH command for this segment. In Maintain, one NEXT command can process a multi-record answer set without a prior MATCH.


Top of page

x
The MATCH Command

In this section:

In response to a MATCH command, the data adapter selects the first record in the data source that meets the MATCH criteria.

The MATCH command compares incoming data with one or more field values and then performs actions that depend on whether or not a record with matching field values exists in the data source.

The syntax of the MATCH command in MODIFY is

MATCH  field1 [ field2...fieldn ]
  ON MATCH action_1 
  ON NOMATCH action_2

where:

fieldn

Are fields in any segment of the Master File. FOCUS compares incoming data values against existing field values. The fields can be any combination of key and/or non-key fields. Specify complete fieldnames; MATCH does not support truncated names.

action_1

Is the operation to perform when a record's values match the incoming data values.

action_2

Is the operation to perform when a record's existing values do not match the incoming data values.

The FOCUS for S/390 documentation discusses these actions in detail.

MATCH processing for multi-segment Master Files is the same as for a multi-segment FOCUS database.

Acceptable actions for MATCH commands fall into eight groups. They are operations that:



x
Data Adapter MATCH Behavior

In MODIFY requests, there are two major differences in the way MATCH commands function for the data adapter and for native FOCUS:

Note: In Maintain, MATCH functions identically for the data adapter and for native FOCUS.



Example: Using the MODIFY MATCH Command

Consider a MODIFY request that maintains the EMPWRITE data source. It prompts for an employee ID and for a new number of leave days; then it processes the incoming data. The annotated request contains the following MATCH commands:

   MODIFY FILE EMPWRITE
   PROMPT EMPLOYEE_ID LEAVE_DUE  
1.   MATCH EMPLOYEE_ID  
2.   ON MATCH UPDATE LEAVE_DUE  
3.   ON NOMATCH REJECT
   DATA

The incoming transaction contains the following values:

EMPLOYEE_ID = 12345678
LEAVE_DUE = 20

The request processes as follows:

  1. The MATCH command compares the value of the incoming EMPLOYEE_ID, 12345678, to the EMPLOYEE_ID values in the records of the EMPWRITE data source. Since EMPLOYEE_ID is the unique key of this data source, Adabas can return at most one record as a result of this MATCH.
  2. If a record exists for EMPLOYEE_ID 12345678, the MATCH command updates the LEAVE_DUE value of that record with the incoming value 20.
  3. If no record exists for EMPLOYEE_ID 12345678, the MATCH command rejects the transaction.

In Maintain, you do not have to include an ON NOMATCH command in order to reject a transaction; Maintain automatically rejects a transaction that does not satisfy the MATCH criteria.


Top of page

x
The NEXT Command

In this section:

In MODIFY, the NEXT command provides a flexible means of processing multi-record answer sets by moving the current position in the answer set from one record to the next.

The syntax is

NEXT field 
   ON NEXT action_1 
   ON NONEXT action_2

where:

field

Is any field in the current segment. This field does not affect subsequent actions.

action_1

Is the operation to perform when there is a subsequent record in the answer set. May be any of the acceptable actions listed for MATCH in The MATCH Command.

action_2

Is the operation to perform when no more records exist in the answer set.

The CALLTYPE parameter in the Access File controls the sort order for NEXT. It determines whether to retrieve records in physical order (CALLTYPE=FIND) or sorted by the unique key (CALLTYPE=RL).

Your choice of MATCH and NEXT command combinations determines the contents of the answer set. Subsequent sections explain these choices in more detail:

You can also use NEXT commands with multi-segment structures (FOCUS views) to modify or display data in either case logic or non-case logic requests. If your MATCH or NEXT specifies a record from a parent segment in a multi-segment structure, that record becomes the current position in the parent segment. A subsequent NEXT on a field in a descendant of that segment retrieves the first descendant record in the related segment. In MODIFY:

You can trace case logic with the FOCUS trace facility. To invoke the trace facility, include the TRACE command on a separate line after the MODIFY FILE command. You can also use the data adapter trace facilities, described in Technical Memo 7966, Adabas Interface: Using Traces.

The following sections illustrate different combinations of MATCH and NEXT command with annotated examples. The MODIFY requests have been kept simple for purposes of illustration; you can create more sophisticated procedures.

Note: In Maintain:

For complete details, see the FOCUS for S/390 Maintaining Databases manual.



x
NEXT Processing Without MATCH

If you use a NEXT command without a previous MATCH command in a MODIFY request, Adabas returns an answer set consisting of all records in the data source in physical order (CALLTYPE=FIND) or sorted by the unique key (CALLTYPE=RL). Use the ON NEXT command to view each record in the order determined by the CALLTYPE attribute. In a Maintain request, the FOR and WHERE phrases in the NEXT command determine the number of records retrieved, in the order determined by the CALLTYPE attribute.



Example: Using NEXT Without MATCH in MODIFY

In this MODIFY example, the NEXT command retrieves each record in physical order because the Access File contains the attribute CALLTYPE=FIND:

MODIFY FILE EMPWRITE
NEXT EMPLOYEE_ID
  ON NEXT TYPE "EMPLOYEE ID: <D.EMPLOYEE_ID LAST NAME: <D.LAST_NAME "
  ON NONEXT GOTO EXIT 
DATA 
END 

The TYPE commands display the following on the screen:

EMPLOYEE ID: 50005800 LAST NAME: GUENTER 
EMPLOYEE ID: 50005500 LAST NAME: BRAUN   
EMPLOYEE ID: 50004900 LAST NAME: CAOUDAL 
EMPLOYEE ID: 50004600 LAST NAME: VERDIE  
EMPLOYEE ID: 50004300 LAST NAME: GUERIN  
EMPLOYEE ID: 50004200 LAST NAME: VAUZELLE
EMPLOYEE ID: 50004100 LAST NAME: CHAPUIS 
EMPLOYEE ID: 50004000 LAST NAME: MONTASSIER 
EMPLOYEE ID: 50003800 LAST NAME: JOUSSELIN 
EMPLOYEE ID: 50006900 LAST NAME: BAILLET   
   .
   .
   .  

If the Access File contained the attribute CALLTYPE=RL, the records would be retrieved in order of employee ID number.



Example: Using NEXT in Maintain

The following Maintain procedure retrieves the same answer set into a stack named INSTACK and displays the retrieved values on a Winform named WIN1 (consult the FOCUS for S/390 Maintaining Databases manual for instructions on creating Winforms):

MAINTAIN FILE EMPWRITE
INFER EMPLOYEE_ID LAST_NAME INTO INSTACK
FOR ALL NEXT EMPLOYEE_ID INTO INSTACK
WINFORM SHOW WIN1
END

The following Winform displays as a result of this procedure:



x
NEXT Processing After MATCH on a Unique Key

In MODIFY, NEXT processing is identical for either MATCH on a full unique key or MATCH on a superset (full unique key plus a non-key field).

When the initial MATCH is successful, Adabas retrieves one record. This establishes the logical position in the data source. The subsequent NEXT command causes Adabas to retrieve all records following the matched record in physical order (CALLTYPE=FIND) or key sequence (CALLTYPE=RL).



Example: Using NEXT After MATCH on a Full Unique Key in MODIFY

The following is an example of NEXT processing after a MATCH on a full unique key, the EMPLOYEE_ID field:

   MODIFY FILE EMPWRITE
   CRTFORM LINE 1
   " PLEASE ENTER VALID EMPLOYEE ID </1" 
1. " EMP: <EMPLOYEE_ID  " 
2. MATCH EMPLOYEE_ID
      ON NOMATCH REJECT  
3.    ON MATCH GOTO GETREST
   CASE GETREST  
4. NEXT EMPLOYEE_ID
      ON NEXT CRTFORM LINE 10
      " EMPLOYEE_ID: <D.EMPLOYEE_ID   LAST_NAME: <D.LAST_NAME  "
      ON NEXT GOTO GETREST 
5.    ON NONEXT GOTO EXIT
   ENDCASE
   DATA
   END

The MODIFY procedure processes as follows:

  1. The user enters the employee ID for the search, 20009000.
  2. The MATCH command causes Adabas to search the data source for the entered value. If no such record exists, the transaction is rejected.
  3. If the specified value matches a value in the EMPLOYEE_ID field of the data source, the procedure branches to the GETREST case; it contains the NEXT command.
  4. The NEXT command retrieves the next record based on physical order, if the Access File contains the attribute CALLTYPE=FIND, or based on the sequence of EMPLOYEE_ID, if the Access File specifies CALLTYPE=RL. If such a record exists, the procedure displays the values of the EMPLOYEE_ID and LAST_NAME fields. It continues to display each record in the order determined by the CALLTYPE attribute of the key field, EMPLOYEE_ID.
  5. If there are no more records, the procedure ends.

The output after executing this MODIFY procedure with CALLTYPE=FIND is:

PLEASE ENTER VALID EMPLOYEE ID                               (line 1)
EMP: 20009000                                                (line 3)
EMPLOYEE_ID:  50005800   LAST_NAME:  GUENTER                 (line 10)
EMPLOYEE_ID:  50005500   LAST_NAME:  BRAUN                   (line 10)
EMPLOYEE_ID:  50004900   LAST_NAME:  CAOUDAL                 (line 10)
EMPLOYEE_ID:  50004600   LAST_NAME:  VERDIE                  (line 10)
EMPLOYEE_ID:  50004300   LAST_NAME:  GUERIN                  (line 10)

Because of the NEXT command, all employees whose records are physically after 20009000 display one at a time on the screen.

The output after executing this MODIFY procedure with CALLTYPE=RL is:

PLEASE ENTER VALID EMPLOYEE ID                               (line 1)
EMP: 20009000                                                (line 3)
EMPLOYEE_ID:  20009100   LAST_NAME:  JENSON                  (line 10)
EMPLOYEE_ID:  20009200   LAST_NAME:  MEYER                   (line 10)
EMPLOYEE_ID:  20009300   LAST_NAME:  SMITH                   (line 10)
EMPLOYEE_ID:  20009400   LAST_NAME:  OLLE                    (line 10)
EMPLOYEE_ID:  20009500   LAST_NAME:  RAY                     (line 10)

Notice that the employee ids after 20009000 are retrieved in key sequence.



Example: Using NEXT on a Full Unique Key in Maintain

The following Maintain procedure retrieves the same answer set into a stack named EMPSTACK. Assume that when Maintain displays the Winform called WIN1, the user enters the transaction value, 20009000, into a stack named TRANS and clicks the NextRecs button to invoke the NEXTRECS case:

MAINTAIN FILE EMPWRITE
INFER EMPLOYEE_ID LAST_NAME INTO EMPSTACK
WINFORM SHOW WIN1
CASE NEXTRECS
 FOR ALL NEXT EMPLOYEE_ID INTO EMPSTACK WHERE EMPLOYEE_ID GT TRANS.EMPLOYEE_ID
ENDCASE
END

The following Winform displays when 20009000 is entered in the EMPLOYEE_ID field with CALLTYPE=FIND:



x
NEXT Processing After MATCH on a Non-Unique Key

In a MODIFY request processed by the data adapter, you do not have to MATCH on the full set of unique key fields. You can match on a non-key field or non-unique key. (Maintain always matches on the full unique key, regardless of which fields you specify in the MATCH command.)

When you MATCH on a non-unique key, multiple records may satisfy the MATCH condition. The MATCH operation retrieves the first record of the answer set, and the NEXT command makes the remaining records in the answer set available to the program in physical order. In this case, the order of retrieval for NEXT is always the physical sequence. MATCH on a non-key field should always be processed using CALLTYPE=FIND to prevent the data adapter from issuing an inefficient Read Physical call. For more information see the FOCUS for IBM Mainframe ADABAS Interface User's Manual and Installation Guide.



Example: Using MATCH on a Non-Unique Key in MODIFY

This annotated procedure is the same procedure described in NEXT Processing After MATCH on a Unique Key, altered to MATCH on the non-unique key field LAST_NAME. The NEXT operation retrieves the subsequent records from the answer set in physical sequence:

   MODIFY FILE EMPWRITE
   CRTFORM LINE 1
   "  PLEASE ENTER A LAST NAME </1 "  
1. "  LAST NAME: <LAST_NAME </1"  
2. MATCH LAST_NAME
      ON NOMATCH REJECT  
3.    ON MATCH CRTFORM LINE 5
      " EMPLOYEE_ID: <D.EMPLOYEE_ID   LAST_NAME: <D.LAST_NAME "  
4.    ON MATCH GOTO GETSAME
   CASE GETSAME  
5. NEXT LAST_NAME
      ON NEXT CRTFORM LINE 10
      " EMPLOYEE_ID: <D.EMPLOYEE_ID   LAST_NAME: <D.LAST_NAME "
      ON NEXT GOTO GETSAME  
6.    ON NONEXT GOTO EXIT
   ENDCASE
   DATA
   END 

The MODIFY procedure processes as follows:

  1. The user enters the last name (LAST_NAME) for the search, SMITH.
  2. The MATCH command causes Adabas to search the data source for all records with the value SMITH and return them in physical order. If the value SMITH does not exist, the transaction is rejected.
  3. If the incoming value matches a value in the data source, the procedure displays the employee ID and last name. (This is the first record of the answer set.)
  4. After displaying the record, the procedure goes to the GETSAME case; it uses NEXT to loop through the remaining records in the answer set.
  5. Instead of retrieving the next logical record with a higher key value as in the previous example, the procedure retrieves the next record in the answer set (all records in the answer set have the last name SMITH). If any exist, they display on the screen in physical order.
  6. When no more records exist with the value SMITH, the procedure ends.

The output from this MODIFY procedure follows:

PLEASE ENTER A LAST NAME
LAST_NAME  smith
EMPLOYEE_ID  40000311 LAST_NAME:  SMITH 
EMPLOYEE_ID:  20009300   LAST_NAME:  SMITH 
EMPLOYEE_ID:  20014100   LAST_NAME:  SMITH
   .
   .
   .
EMPLOYEE_ID:  30038013   LAST_NAME:  SMITH 

A line displays on the screen for each employee with the last name SMITH. Employee ID 40000311 is the result of the MATCH operation; employee ID 20009300 is the result of the NEXT operation, employee ID 30038013 is the result of the last NEXT operation. Notice that the records are retrieved in physical sequence, and order is not dependent on the CALLTYPE attribute.



Example: Using NEXT on a Non-Unique Key Field in Maintain

The following Maintain procedure retrieves the entire answer set into a stack named EMPSTACK. Assume that when Maintain displays the Winform named WINA, the user enters the transaction value (SMITH) into the first record of a stack named TRANS and clicks the NextRecs button to invoke the NEXTRECS case:

MAINTAIN FILE EMPWRITE	
INFER EMPLOYEE_ID LAST_NAME INTO EMPSTACK
WINFORM SHOW WINA
CASE NEXTRECS
  FOR ALL NEXT EMPLOYEE_ID INTO EMPSTACK WHERE LAST_NAME EQ TRANS.LAST_NAME
ENDCASE
END

The following Winform displays when the NexRecs button is pressed with SMITH entered in the Last_Name field:


Top of page

x
INCLUDE, UPDATE, and DELETE Processing

In this section:

Reference:

While MATCH and NEXT operations in MODIFY can operate on unique key or non-unique key fields and return single or multi-record answer sets, the MODIFY commands INCLUDE, UPDATE, and DELETE must always identify the target records by their unique key. Therefore, in MODIFY, each update operation affects at most one record. (In Maintain, the FOR phrase in the update command determines the number of records affected.)



x
Reference: Rules for Inserting Records Into an Adabas Data Source

Note: The Master File does not identify the level of an MU field because if the MU field belongs to a simple group, the Master File does not describe this group. (However, if AUTOADBS created the Master File, there will be a commented declaration for the group.) Therefore, FOCUS cannot determine whether Adabas will add an empty occurrence for the corresponding segment. You must be aware of the options in the Adabas FDT to understand the behavior that occurs in response to an INCLUDE command for an MU segment.



x
Effect of UNQKEYNAME on INCLUDE Actions for Segments With ACCESS=ADBS

The UNQKEYNAME attribute in the Access File determines how the data adapter presents an INCLUDE command to Adabas. The option UQ in the Adabas FDT and the specific fields used in the MATCH command determine whether Adabas actually inserts the segment instance. The following table describes how these factors affect the result of the INCLUDE command. Assume that the Access File specifies UNQKEYNAME=EMPLOYEE_ID and that the employee id value EMPID005 already exists in the data source:

Result of INCLUDE Command for Existing EMPLOYEE_ID EMPID005

EMPLOYEE_ID has option UQ in FDT

Fields in MATCH command

Instance Inserted(ON NOMATCH)

No

EMPLOYEE_ID only

ON MATCH case performed

Yes

EMPLOYEE_ID only

ON MATCH case performed

No

EMPLOYEE_ID plus fields with values that do not already exist

Yes

Yes

EMPLOYEE_ID plus fields with values that do not already exist

No - error (FOC4561), RC=198

This table describes INCLUDE actions when EMPLOYEE_ID is not in the MATCH field list:

Result of INCLUDE Command Without Matching on Field EMPLOYEE_ID

UNQKEYNAME = EMPLOYEE_ID?

Instance Inserted

Yes

No - error (FOC4563)

No

Yes



x
Reference: Rules for Deleting Records From an Adabas Data Source
  • For a segment with a unique key, the key field value is used to delete the target segment.
  • For a segment with a non-unique key, you must supply the key field. If the MATCH criteria for this type of segment, in the path or target, do not identify a unique occurrence, the first occurrence found will be deleted. The use of Adabas descriptors for this type of segment is highly recommended for efficiency.
  • For a segment with no key, you must supply at least one MATCH condition. If the MATCH criteria for this type of segment, in the path or target, do not identify a unique occurrence, the first occurrence found will be deleted.
  • A segment occurrence with ACCESS=PE or MU is deleted from the data source except if it is the last occurrence for an ACCESS=PE segment. Adabas will only delete the last occurrence if all fields have the NU option in the FDT; if they do not all have this option, the occurrence will have empty values in all fields.
  • When you delete segments that have dependent segments, the DELETED counter for the session may have an incorrect value. For a first level segment with descendants, this counter will always be incorrect. For a second level segment, this counter will be incorrect if there are multiple descendant segments. For a third level segment, this counter is always correct.


x
Reference: Rules for Updating Records in an Adabas Data Source
  • For a segment with a unique key, the key field value and any additional MATCH criteria are used to qualify the target segment for update.
  • For a segment with a non-unique key, you must supply the key field. If the MATCH criteria for this type of segment, in the path or target, do not identify a unique occurrence, the first occurrence found will be updated. The use of Adabas descriptors for this type of segment is highly recommended for efficiency.
  • For a segment with no key, you must supply at least one MATCH condition. If the MATCH criteria for this type of segment, in the path or target, do not identify a unique occurrence, the first occurrence found will be updated.


Example: Updating Adabas Records With MODIFY

Suppose you want to display all the employees in a department and update the amount of leave they have taken:

   MODIFY FILE EMPWRITE
   CRTFORM LINE 1
   " PLEASE ENTER A VALID DEPARTMENT </1" 
1. " DEPARTMENT: <DEPARTMENT " 
2. MATCH DEPARTMENT
     ON NOMATCH REJECT
     ON MATCH CRTFORM LINE 10 
3.   "ID: <D.EMPLOYEE_ID LEAVE DUE: <D.LEAVE_DUE> TAKEN <T.LEAVE_TAKEN> 
" 
4.   ON MATCH UPDATE LEAVE_TAKEN 
     ON MATCH GOTO GETREST
   CASE GETREST 
5.   NEXT EMPLOYEE_ID
     ON NEXT CRTFORM LINE 10
     "ID: <D.EMPLOYEE_ID LEAVE DUE: <D.LEAVE_DUE> TAKEN <T.LEAVE_TAKEN> "
     ON NEXT UPDATE LEAVE_TAKEN
     ON NEXT GOTO GETREST 
6.   ON NONEXT GOTO EXIT
   ENDCASE
   DATA
   END

The MODIFY procedure processes as follows:

  1. The user enters the department (DEPARTMENT) for the search, PROD.
  2. The MATCH command causes Adabas to search the data source for the first record with the value PROD and return them in physical sequence. If none exists, the transaction is rejected.
  3. If the supplied value matches a database value, the procedure displays it.
  4. The procedure updates the LEAVE_TAKEN field for the first retrieved record using the turnaround value from the CRTFORM. EMPLOYEE_ID establishes the target record for the update.
  5. Each time it executes the NEXT, the procedure retrieves the next record with the same department, PROD. It displays each one in physical order. It updates the LEAVE_TAKEN field for each retrieved record with the turnaround value.
  6. When no more records exist for department PROD, the procedure ends.


Example: Updating Adabas Records With Maintain

In Maintain, you can use stack columns as turnaround values to update a data source. The following annotated Maintain request updates the same records as the preceding MODIFY request:

   MAINTAIN FILE EMPWRITE
   INFER EMPLOYEE_ID LEAVE_DUE LEAVE_TAKEN INTO EMPSTACK 
1. WINFORM SHOW WIN1 
2. CASE MATCHREC
     FOR ALL NEXT EMPLOYEE_ID INTO EMPSTACK
    WHERE DEPARTMENT EQ VALSTACK.DEPARTMENT
   ENDCASE 
3. CASE UPDLV
      FOR ALL UPDATE LEAVE_TAKEN FROM EMPSTACK
   ENDCASE
   END

The Maintain procedure processes as follows:

  1. A Winform named WIN1 displays. Assume that it displays an entry field labeled DEPARTMENT (whose source and destination stack is called VALSTACK) and a grid (scrollable data source) with columns EMPLOYEE_ID, LEAVE_DUE and LEAVE_TAKEN. See the manual for instructions on creating Winforms.
  2. The user enters a DEPARTMENT value for the search and clicks the GetEmps button to invoke case MATCHREC. Case MATCHREC retrieves the records that satisfy the NEXT criteria and stores them in a stack named EMPSTACK. The Winform displays the retrieved records on the grid.
  3. The user edits all the necessary leaves taken directly on the Winform grid and then clicks the Update button to invoke case UPDLV, which updates all leaves taken.

The following Winform displays when the GetEmp button (or PF4) is pressed with PROD entered in the Department field:

The user can update the LEAVE_TAKEN field for all of the listed employees and update them all in one step with the Update button (or PF6).


Top of page

x
Adabas Transaction Control Within MODIFY

In this section:

The data adapter supports the Logical Unit of Work (LUW) concept. An LUW consists of one or more FOCUS maintenance actions (UPDATE, INCLUDE, or DELETE) that process as a single unit. The maintenance operations within the LUW can operate on the same or separate data sources.

In MODIFY, all records read by MATCH and NEXT commands are held by Adabas in a user's hold record queue. To prevent overflow of this queue, the user should periodically issue the SQL COMMIT WORK command to propagate the changes to the Adabas data source and clear the queue.

In Maintain, records are not held when they are read into a stack. They are held only in response to an updating command.

A transaction is defined as all actions taken since the application first accessed Adabas, last issued an SQL COMMIT WORK in MODIFY or COMMIT command in Maintain, or last issued an SQL ROLLBACK WORK in MODIFY or ROLLBACK command in Maintain.

Within a Logical Unit of Work, Adabas either executes all commands completely, or else it executes none of them. If Adabas detects no errors in any of the commands within the LUW:

In response to unsuccessful execution of any command in the transaction, the data adapter:

Adabas and the data adapter provide a level of automatic transaction management but, in many cases, this level of management alone is not sufficient. FOCUS supports explicit control of Adabas transactions with the commands SQL COMMIT WORK and SQL ROLLBACK WORK in MODIFY, and with the commands COMMIT and ROLLBACK in Maintain.

Note: SQL COMMIT WORK and SQL ROLLBACK WORK are data adapter commands. Do not confuse these commands with the FOCUS COMMIT WORK and ROLLBACK WORK commands that apply to FOCUS databases only. The data adapter ignores COMMIT WORK and ROLLBACK WORK without the SQL qualifier.

Unless you specify SQL COMMIT WORK and/or SQL ROLLBACK WORK in your MODIFY procedure (or COMMIT and/or ROLLBACK in your Maintain procedure), all FOCUS maintenance actions until the END command constitute a single LUW. If the procedure completes successfully, the data adapter automatically transmits an ET command to Adabas, and the changes become permanent. If the procedure terminates abnormally, the data adapter issues a BT command to Adabas, and the database remains untouched. Since locks are not released until the end of the program, a long MODIFY or Maintain procedure that relies on the default, end-of-program ET can interfere with concurrent access to data. In addition:



x
Transaction Termination (COMMIT WORK)

The SQL COMMIT WORK command signals the successful completion of a transaction at the request of the procedure. Execution of a COMMIT command makes changes to the data sources permanent. The syntax in a MODIFY request is:

SQL COMMIT WORK

You can issue a COMMIT WORK as an ON MATCH, ON NOMATCH, ON NEXT, or ON NONEXT condition, after an update operation (INCLUDE, UPDATE, DELETE), or within cases of a case logic request.

Note: In Maintain, you must use the Maintain facility's COMMIT command to transmit an ET (End of Transaction) command to Adabas.



Example: Using COMMIT WORK in a MODIFY Procedure

A COMMIT WORK example using Case Logic follows:

CASE PROCESS
   CRTFORM
   MATCH field1 ... 
     ON MATCH insert, update, delete, ...
   GOTO EXACT
ENDCASE
CASE EXACT
   SQL COMMIT WORK 
   GOTO TOP 
ENDCASE

The PROCESS case handles the MATCH, ON MATCH, ON NOMATCH processing. Then it transfers to CASE EXACT, which commits the data instructing Adabas to write the entire Logical Unit of Work to the database.



x
Transaction Termination (ROLLBACK WORK)

The SQL ROLLBACK WORK command signals the unsuccessful completion of a transaction at the request of the procedure. Execution of a ROLLBACK command backs out all changes made to the data sources since the last COMMIT command. The syntax in a MODIFY request is:

SQL ROLLBACK WORK

You can design a MODIFY procedure to issue a ROLLBACK WORK command if you detect an error. For example, if a FOCUS VALIDATE test finds an inaccurate input value, you may choose to exit the transaction, backing out all changes since the last COMMIT. You can issue ROLLBACK WORK as an ON MATCH, ON NOMATCH, ON NEXT, or ON NONEXT condition, or within cases of a case logic request.

Note: In Maintain, you must use the Maintain facility's ROLLBACK command to transmit a BT command (Back out Transaction) to Adabas.

The data adapter automatically executes an SQL ROLLBACK WORK command when you exit from a transaction early. For example, if you exit a CRTFORM without specifying some action, the data adapter automatically issues a ROLLBACK WORK command on your behalf.

The data adapter automatically issues a BT command in case of system failure or when it detects a fatal data error, such as a reference to a field or data source that does not exist.



Example: Using ROLLBACK WORK in a MODIFY Procedure

The following is an example of the ROLLBACK WORK command using Case Logic:

ON NOMATCH CRTFORM ... 
ON NOMATCH VALIDATE ...   
   ON INVALID GOTO ROLLCASE    
      .
      .
      .
CASE ROLLCASE  
   SQL ROLLBACK WORK 
   GOTO TOP 
ENDCASE

Code the ROLLBACK WORK command before a REJECT command. FOCUS ignores any action following the rejection of a transaction, except for GOTO or PERFORM.

For example:

ON MATCH SQL ROLLBACK WORK 
ON MATCH REJECT


Example: Transaction Control in Adabas

Each time an employee takes leave days, the following example updates the LEAVE_TAKEN field in the root segment of the EMPWRITE data source and posts a record for the leave start and end dates in the related AW0401 segment. To ensure that both updates complete or neither one does, the MODIFY procedure places both actions prior to a COMMIT WORK command. If the descendant data source is not processed, ROLLBACK WORK discards the whole logical transaction.

MODIFY FILE EMPWRITE                                            
CRTFORM LINE 1                                                  
"</2 <25 MODIFY FOR LEAVE TAKEN </2 "                         
"<20 ENTER THE EMPLOYEE ID <EMPLOYEE_ID "                       
MATCH EMPLOYEE_ID                                               
  ON MATCH CRTFORM LINE 7                                       
  "<D.FIRST_NAME <D.LAST_NAME> LEAVE TAKEN <T.LEAVE_TAKEN> </1 "
  ON MATCH UPDATE LEAVE_TAKEN                 
  ON MATCH COMPUTE AW0401_OCC =0;                               
  ON NOMATCH REJECT                                             
MATCH AW0401_OCC                                                
  ON NOMATCH CRTFORM LINE 10                                    
  "PLEASE ENTER LEAVE DATES"                                   
  "LEAVE_START: <T.LEAVE_START> "                                         
  "LEAVE_END:   <T.LEAVE_END> "                                         
  ON NOMATCH INCLUDE                                            
  ON NOMATCH SQL COMMIT WORK                                    
  ON MATCH SQL ROLLBACK WORK                                    
  ON MATCH REJECT                                               
DATA  
END

Top of page

x
Using the Return Code Variable: FOCERROR

FOCUS stores the return code from the updating commands INCLUDE, DELETE, and UPDATE in the variable FOCERROR:

A return code of zero indicates successful completion of the last updating command issued.

You can test the FOCERROR variable and take appropriate action if you encounter a non-fatal error. This condition might indicate the need to ROLLBACK the transaction or re-prompt the user for new input values. In Maintain, all errors after updating commands are non-fatal, and you should always test FOCERROR after issuing an updating command. In MODIFY, you can issue the SQL SET ERRORRUN ON command to make these errors non-fatal. If you do not issue this command, all errors after updating commands in MODIFY will be fatal.

All errors that result from retrieval commands such as MATCH or NEXT are fatal errors. An example of a command that causes a retrieval error is attempting to read a record held by another user. These errors terminate MODIFY and Maintain procedures.

For a list of common Adabas response codes, see Adabas Response Codes.


Top of page

x
Using the Data Adapter SET ERRORRUN Command

How to:

With SET ERRORRUN ON, MODIFY processing continues even when a serious error occurs, allowing applications to handle their own errors in the event that an Adabas error is part of the normal application flow. Code this command explicitly within the MODIFY procedure, preferably in CASE AT START, where it executes once.

Note: Maintain does not support the SET ERRORRUN command. All errors after updating commands are non-fatal.

When SET ERRORRUN is ON, the MODIFY procedure reports the error but continues execution. The MODIFY code can then test the value of FOCERROR to determine the cause of the error and take appropriate action. Be careful in evaluating the contents of FOCERROR, to prevent unpredictable errors in subsequent MODIFY processing.

SET ERRORRUN returns to its default setting of OFF at the end of the MODIFY procedure.



x
Syntax: How to Issue the SET ERRORRUN Command in a MODIFY Procedure
CASE AT START
    SQL SET ERRORRUN {OFF|ON}
ENDCASE

where:

OFF

Stops MODIFY processing when the Data Adapter detects a fatal error. OFF is the default.

ON

Enables MODIFY processing to continue despite fatal errors. Test the value of FOCERROR to determine the desired action after an updating command fails. After the procedure ends, ERRORRUN returns to its default value of OFF.


Top of page

x
Modifying Data sources Without Unique Keys

Adabas permits data sources with duplicate records. Such data sources cannot possibly have a unique key, since no combination of field values can make a given record unique.

The data adapter provides a way of maintaining data sources with duplicate records. However, only the first record encountered will be affected by data maintenance commands.

Note:


Information Builders