Modifying Data

The MATCH Command

In this section:

Adapter MATCH Behavior

In response to a MATCH command, the 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:

field1 ... 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 field names; MATCH does not support truncated names.
action_1: Is the operation to perform when the values in a record match the incoming data values.
action_2: Is the operation to perform when the existing values in a record do not match the incoming data values.

The FOCUS Maintaining Databases manual discusses these actions in detail.

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

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

Include, change, or delete records.
Control MATCH processing, such as rejecting the current transaction.
Read incoming data fields.
Perform computations and validations, or type messages to the terminal.
Control case logic.
Control multiple-record processing.
Activate and deactivate fields in MODIFY.
Permanently store data in the Adabas data source.

Top of page

Adapter MATCH Behavior

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

With the adapter, you can change the value of the unique key in a data source (subject to Adabas limitations) using the UPDATE command. When modifying a FOCUS data source, you cannot change key field values.
You can MATCH on any field or combination of fields in the record. However, if the full unique key is not included in the MATCH criteria, the adapter may retrieve more than one record as a result of the MATCH.

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

Top of page

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:

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.
If a record exists for EMPLOYEE_ID 12345678, the MATCH command updates the LEAVE_DUE value of that record with the incoming value 20.
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.

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:

NEXT command without a MATCH command. The adapter requests the retrieval of all records in the data source in physical order (CALLTYPE=FIND) or sorted by the unique key (CALLTYPE=RL).
MATCH on the unique key. The MATCH returns the single record that is the starting point for any subsequent NEXT commands, which retrieve the remaining records in the answer set in physical order (CALLTYPE=FIND) or sorted by the unique key (CALLTYPE=RL).
MATCH on a non-unique key field. Adabas returns a multi-record answer set in which each record satisfies the MATCH criteria. The adapter requests the retrieval of these records in physical order.

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:

Without case logic, you can retrieve all parent records in the segment and only the first descendant record of any specified related segment.
With case logic, you can retrieve all records for each segment defined in a multi-segment Master File. To do so, first MATCH on the parent. Then, in another case, use NEXT to loop through the related segments (at the lowest level) until there are no more related instances. On NONEXT, return to the parent case for the next parent instance.

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 adapter trace facilities, described in Technical Memo 7966, Adabas Interface: Using Traces.

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

Note: In Maintain:

The syntax of the NEXT command includes optional FOR and WHERE phrases that control the number of records retrieved into a stack. As in MODIFY, the CALLTYPE attribute in the Access File determines whether NEXT returns records in physical order or unique key order.
NEXT always starts its retrieval at the current database position; it will not retrieve a record it has already passed in its retrieval path unless you use the REPOSITION command to reset the current position.

The UPDATE, DELETE, and INCLUDE commands also incorporate the optional FOR phrase to process multiple records from a stack.

For complete details, see the Maintaining Databases manual.

Top of page

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.

Top of page

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.

Top of page

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 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:

Top of page

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).

Top of page

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:

The user enters the employee ID for the search, 20009000.
The MATCH command causes Adabas to search the data source for the entered value. If no such record exists, the transaction is rejected.
If the specified value matches a value in the EMPLOYEE_ID field of the data source, the procedure branches to the GETREST case which contains the NEXT command.
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.
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.

Top of page

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:

Top of page

NEXT Processing After MATCH on a Non-Unique Key

In a MODIFY request processed by the 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 adapter from issuing an inefficient Read Physical call. For more information see the Adapter for ADABAS Installation Guide.

Top of page

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:

The user enters the last name (LAST_NAME) for the search, SMITH.
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.
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.)
After displaying the record, the procedure goes to the GETSAME case. That case uses NEXT to loop through the remaining records in the answer set.
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.
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.

Top of page

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:

INCLUDE, UPDATE, and DELETE Processing

In this section:

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

Reference:

Rules for Inserting Records Into an Adabas Data Source

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.)

Top of page

Reference: Rules for Inserting Records Into an Adabas Data Source

For a segment with a unique key:
The unique key field value is used to insert the target segment. If any additional MATCH criteria are supplied for a segment in the path, they will be used to qualify that path segment.

An attempt to use MATCH on a non-unique key before an INCLUDE command generates the following error message:
```
(FOC4563) INCORRECT INCLUDE REQUEST FOR NON UNIQUE KEY
```
For a segment with a non-unique key or no key:
If you want to insert an additional record for an existing key field, you must MATCH on the key field and specify ON MATCH INCLUDE.
For segments with ACCESS=PE or MU, if a new occurrence is inserted, you must set the occurrence number (ORDER field) to 0 (zero indicates the next occurrence) or to a value greater than the number of existing occurrences. This new occurrence is always inserted after the last existing occurrence. For example, if a PE or MU segment has two existing occurrences, the next occurrence added will always be the third. If the occurrence with the given number already exists, processing will terminate with the following message:
```
(FOC4564)  THIS OCCURRENCE ALREADY EXISTS. USE UPDATE COMMAND.
```
You should use the UPDATE command instead of INCLUDE in this case.
For segments with ACCESS=MU, if the corresponding field with the MU option is defined without the NU option on the second level of the Adabas FDT (that is, it is part of a periodic group (PE) or simple group (GR)):
- If an INCLUDE command is issued for the root segment alone, Adabas automatically inserts an empty child (MU) segment and, if this child segment has a parent with ACCESS=PE, an empty parent segment.
- If an INCLUDE command is issued for the root and a parent (PE) of the MU segment simultaneously, but without values for the child (MU) segment, Adabas automatically inserts an empty child (MU) segment. The adapter automatically inserts the first occurrence of the parent (PE) segment using the values from the INCLUDE command.
- If an INCLUDE command is issued for the root, parent (PE), and child (MU) segments simultaneously, the adapter inserts the first occurrence of both the child and parent segments using the values from the INCLUDE command.
For segments with ACCESS=MU, if the corresponding field with the MU option is defined with the NU option on any level in the Adabas FDT, Adabas automatically suppresses the empty values. An INCLUDE command can be issued for the parent and child segments separately or simultaneously.

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.

Top of page

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

The UNQKEYNAME attribute in the Access File determines how the 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

Result of INCLUDE Command for Existing EMPLOYEE_ID EMPID005
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

Top of page

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.

Top of page

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.

Top of page

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:

The user enters the department (DEPARTMENT) for the search, PROD.
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.
If the supplied value matches a database value, the procedure displays it.
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.
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.
When no more records exist for department PROD, the procedure ends.

Top of page

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:

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 Maintaining Databases manual for instructions on creating Winforms.
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.
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).

Adabas Transaction Control Within MODIFY

In this section:

The 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 hold record queue for a user. 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 command in MODIFY or a COMMIT command in Maintain, or last issued an SQL ROLLBACK WORK command in MODIFY or a 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:

FOCUS issues a COMMIT WORK command. The adapter issues an ET (End of Transaction) command to Adabas. The changes indicated by the updates within the transaction are recorded in the data source.
Adabas releases locks on the target data.
Database changes become available for other tasks.

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

Issues a BT (Backout Transaction) command to Adabas. Target data returns to its state prior to the unsuccessful transaction. All changes attempted by the commands in the transaction are backed out.
Does not execute the remaining commands in the transaction.
Releases locks on the target data.
Discards partially accumulated results.

Adabas and the 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 adapter commands. Do not confuse these commands with the FOCUS COMMIT WORK and ROLLBACK WORK commands that apply to FOCUS data sources only. The 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 adapter automatically transmits an ET command to Adabas, and the changes become permanent. If the procedure terminates abnormally, the 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:

You may lose all updates in the event of a system failure.
You may fill up the hold queue Adabas establishes for records locked by a user. The number of ISNs that can be held in this queue is determined by the Adabas NISNHQ parameter. To avoid exceeding this number, keep a counter in your MODIFY or Maintain procedure, and commit or rollback the transaction to avoid holding too many records.

Top of page

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 COMMIT command to transmit an ET (End of Transaction) command to Adabas.

Top of page

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, and 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.

Top of page

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 ROLLBACK command to transmit a BT command (Back out Transaction) to Adabas.

The 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 adapter automatically issues a ROLLBACK WORK command on your behalf.

The 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.

Top of page

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

Top of page

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

Using the Return Code Variable: FOCERROR

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

In MODIFY, the return code value is the Adabas response code.
In Maintain, the value is
- 1 if an INCLUDE command failed.
- 2 if a DELETE command failed.
- 3 if an UPDATE command failed.

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.

Using the Adapter SET ERRORRUN Command

How to:

Issue the SET ERRORRUN Command in a MODIFY Procedure

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.

Top of page

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 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.

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 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: Maintain does not support modifying unkeyed data sources.

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