For software that supports the MODIFY facility, note the following:

• The JOIN command allows you to read (but not to modify) data in a second FOCUS data source using the MODIFY LOOKUP function. To modify multiple FOCUS data sources in one request, use the COMBINE command.
• The LOOKUP function in MODIFY requests cannot be used on a DEFINE-based JOIN; DEFINE is not evaluated during a MODIFY procedure.
• The MODIFY LOOKUP function cannot retrieve data in a cross-referenced segment using concatenated fields (a multi-field join).

FOCUS offers a variety of other advanced features that facilitate use of the MODIFY command in more complex applications. These features are listed below and described in Advanced Facilities:

• The COMBINE command for modifying multiple FOCUS data sources in one MODIFY request.
• The COMPILE command for translating MODIFY requests into compiled code ready for execution.
• The ACTIVATE and DEACTIVATE statements for activating and deactivating fields.
• The Checkpoint and Absolute File Integrity facilities and the COMMIT and ROLLBACK Subcommands for protecting FOCUS data sources from system failures.
• The ECHO facility for displaying the logical structure of MODIFY requests.
• Dialogue Manager system variables that record execution statistics every time a MODIFY request is run.
• FOCUS query commands that display statistical information on MODIFY request executions and FOCUS data sources.

The rest of this introduction contains:

• The basic syntax of MODIFY requests.
• Instructions for executing MODIFY requests.
• A summary of facilities other than MODIFY that can be used to maintain FOCUS data sources.
• A short description of the parts of the EMPLOYEE data source most used in the examples.

Suppose you need to update a particular data source, but three other users have been assigned to work on the data source at the same time. How can you be sure that one user's changes will not override or overwrite another user's changes? MODIFY, used in conjunction with the Simultaneous Usage (SU) facility, ensures data integrity under those circumstances.

To enter SU mode, you initiate a background job process called a FOCUS Database Server. The user ids running FOCUS or Host Language Interface programs are called source machines. The users (using their source machines) send requests and transactions to the FOCUS Database Server, which processes the transactions and transmits the retrieved data or messages back to the source machine. The following diagram illustrates the process:

Under SU, when you run a MODIFY request

1. The request identifies the instance to be changed with MATCH or NEXT commands.
2. The source machine forwards the transaction values to the FOCUS Database Server, which uses the values to retrieve the correct instance.
3. The FOCUS Database Server retrieves the original data source instance, holds one copy, and sends another to the source (user id) that requested the data.
4. The source machine updates its copy of the instance with the new field values, or marks the copy for deletion and sends the updated copy back to the FOCUS Database Server. The FOCUS Database Server compares the copy of the instance that it saved with the instance stored in the data source to check whether the data source instance has since been updated by another user.

   At this point, two courses of action are possible:

   • If the copy and the current instance in the data source are the same, FOCUS changes the instance using the copy from the source machine.
   • If the original and the current instance in the data source are different, SU signals a conflict and rejects the source machine copy.

Notice that a source machine may work on separate, locally controlled data sources.

MODIFY FILE EMPLOYEE
PROMPT EMP_ID
GOTO NEWSAL
CASE NEWSAL
MATCH EMP_ID
    ON NOMATCH REJECT
    ON MATCH PROMPT CURR_SAL
    ON MATCH UPDATE CURR_SAL
    ON MATCH IF FOCURRENT EQ 0 GOTO TOP;
    ON MATCH TYPE
      "VALUE CHANGED. NEW VALUE <D.CURR_SAL>"
ENDCASE
DATA

In addition to the basic operations of the MODIFY facility, many other features are available to help you refine your MODIFY requests. This section describes them briefly.

The general syntax of the MODIFY command is

MODIFY FILE filename [ECHO|TRACE]
  .
  . 
statements  .
  .
DATA [ON ddname|VIA program]
  . 
incoming data  .
  .
[END]

where:

MODIFY FILE

Begins the request.

filename

Is the name of the FOCUS, relational, fixed format sequential, VSAM, or Adabas data source you are modifying. This name must be the same as the Master File of the data source. For information about modifying non-FOCUS data sources, see the appropriate data adapter documentation.

Note: Although you can use MODIFY to load a fixed format sequential file, the sequential data source must consist of a single segment, and data is loaded in the order in which it is input. Update and delete operations are not supported. To append data to an existing sequential data source with HiperFOCUS ON, the record format must be fixed.

ECHO

Invokes the ECHO facility, which displays the request logic (see Displaying MODIFY Request Logic: The ECHO Facility).

TRACE

Invokes the TRACE facility, which displays the name of each case that is entered during the execution of the request if the request uses Case Logic (see Tracing Case Logic: The TRACE Facility).

statements

Are the MODIFY statements in the request. Each statement must begin on a separate line.

DATA

Specifies the source of incoming data. Note that nothing should come between this statement and the END statement, unless you are supplying the incoming data in the request itself. In that case, place the data after the DATA statement.

ON ddname

Is a DATA statement parameter. See Specifying the Source of Data: The DATA Statement.

VIA program

Is a DATA statement parameter.

incoming data

Is the data you are using to modify the data source if you are supplying the data in the request itself.

END

Concludes the request. Do not add this statement if the request contains PROMPT statements (PROMPT statements are discussed in Prompting for Data One Field at a Time: The PROMPT Statement).

You can enter and run a MODIFY request either by entering it at the terminal or by running it as a stored procedure (stored procedures are discussed in the Developing Applications manual). When you start execution of the request, FOCUS executes the request for each transaction until:

• There is no more data to be read in the incoming transaction data source (the file containing the incoming data).
• The user signals a halt (if the request is prompting the user for data).
• The STOP statement signals a halt to the processing of transactions in an incoming data source (see Reading Selected Portions of Transaction Data Sources: The START and STOP Statements).
• The request encounters a GOTO EXIT statement.

EX focexec 

filename ON date AT time

TRANSACTIONS:  TOTAL  = n ACCEPTED  = n REJECTED = n 
SEGMENTS: INPUT       = n UPDATED   = n DELETED  = n

SET MESSAGE = OFF

MODIFY FILE filename 

filename ON date AT time 
ENTER SUBCOMMANDS:

START:

>
modify file employee 

 EMPLOYEEFOCUS A1 ON 08/15/85 AT 16.36.05 
 ENTER SUBCOMMANDS:
freeform emp_id curr_sal
match emp_id
on nomatch reject
on match update curr_sal
data 
 START:
emp_id=071382660, curr_sal=21400.50, $
emp_id=112847612, curr_sal=20350.00, $
emp_id=117593129, curr_sal=22600.34, $
end

TRANSACTIONS:  TOTAL= 3 ACCEPTED= 3 REJECTED= 0
SEGMENTS:      INPUT= 0 UPDATED=  3 DELETED=  0

Although the MODIFY command is one of the primary methods of maintaining FOCUS data sources, there are four other facilities for changing data in FOCUS data sources:

• The Maintain facility allows you to maintain data sources (including FOCUS, DB2, SQL/DS, Oracle, Teradata, and VSAM data sources) using event-driven and set-based processing in with a Graphical User Interface. The Maintain facility is described in Introduction to Maintain, through Expressions Reference.
• The FSCAN and SCAN facility allows you to edit FOCUS data sources interactively on a field-by-field basis. You enter a subcommand to make each change. The facility can update key fields. The FSCAN facility is the subject of Directly Editing FOCUS Databases With FSCAN. SCAN is the subject of Directly Editing FOCUS Databases With SCAN.
• The Host Language Interface (HLI) allows you to maintain FOCUS data sources from computer programs written in BAL, FORTRAN, COBOL, and PL/1. HLI is covered in the Host Language Interface Users Manual.

Unlike the FSCAN facility mentioned above, the MODIFY command allows you to make many changes with one execution. It can run in both interactive and batch modes. It will prompt you for the values it needs to make the changes, or it may read the values from a transaction data source. However, it cannot update key fields.

Note that although the FOCUS Report Writer can write reports from many kinds of non-FOCUS data sources (such as ISAM, VSAM, and IMS data sources), the MODIFY command maintains only FOCUS data sources, and with the proper interface, VSAM data sources, and SQL and Teradata tables.

You can only MODIFY one partition of a partitioned FOCUS data source at one time. You must explicitly allocate the partition to be modified. Alternatively, you can create separate Master Files for each partition for use in MODIFY procedures. For more information about partitioned FOCUS data sources, see the Describing Data manual.

The examples in this chapter use the EMPLOYEE data source, a data source used to record employee information for a company. The Master File and the diagram of the entire data source structure are shown in Master Files and Diagrams. Most of the examples use three segments in the EMPLOYEE data source:

• The EMPINFO segment contains information directly relating to employees in a company: employee ID, last name, first name, hire date, department assignment, current salary, job code, and classroom hours.
• The SALINFO segment contains information relating to employees' monthly pay: the pay date and the amount of pay.
• The DEDUCT segment contains information about the deductions taken off each monthly pay check: the type of deduction and the amount of the deduction.