Ensuring Transaction Integrity for FOCUS Data Sources

Each database management system (DBMS) supports transaction integrity in its own way. The FOCUS DBMS manages concurrent access to FOCUS data sources using the FOCUS Database Server, and uses certain commands to identify transaction integrity attributes. The FOCUS Database Server was formerly known as a sink machine, or Simultaneous Usage (SU) facility on some platforms.

To ensure transaction integrity for FOCUS data sources, perform the following tasks:

• Install the FOCUS Database Server. When installing each WebFOCUS Reporting Server that will host FOCUS data sources, select the FOCUS Database Server option.
• Set COMMIT. Set the COMMIT server parameter to ON. This enables the COMMIT and ROLLBACK commands for FOCUS data sources, and enables the use of the FOCUS Database Server. For more information, see Ensuring Transaction Integrity for FOCUS Data Sources.
• Select which segments will be verified for changes. Set the PATHCHECK server parameter to specify the type of segments for which the FOCUS Database Server will verify change. This is optional. You can accept the default setting. For more information, see Ensuring Transaction Integrity for FOCUS Data Sources.
• Identify the FOCUS Database Server. Identify which FOCUS Database Server will manage concurrent access to each FOCUS data source. For more information, see Ensuring Transaction Integrity for FOCUS Data Sources.
• Start the FOCUS Database Server. Under Windows and UNIX, when you start the WebFOCUS Reporting Server, it automatically starts the FOCUS Database Server. When you stop the WebFOCUS Reporting Server, it automatically stops the FOCUS Database Server. For information about starting and stopping the FOCUS Database Server under MVS and OS/390, see the ibi™ WebFOCUS® Simultaneous Usage Reference Manual for z/OS guide.

Setting COMMIT

You must set the COMMIT server parameter to ON before using the COMMIT and ROLLBACK commands for FOCUS data sources, and before using the FOCUS Database Server. You must set COMMIT on all WebFOCUS Reporting Servers hosting procedures that read or write to FOCUS data sources in a logical transaction. In most applications, this will mean setting COMMIT on all WebFOCUS Reporting Servers that host procedures with data source commands.

You can set COMMIT:

• Comprehensively for all users on a WebFOCUS Reporting Servers. Issue the SET COMMIT command in the WebFOCUS Reporting Server global profile (EDASPROF).
• Comprehensively for a group of users on a WebFOCUS Reporting Server. Issue the SET COMMIT command in one or more of the group profiles of the server. Group profiles are supported under UNIX, OS/390, and MVS.
• Individually for each user on a WebFOCUS Reporting Server. Issue the SET COMMIT command in one or more of the group profiles of the server (PROFILE). The user in this case is the user account that launches the application.

If you set COMMIT in a user profile or group profile, you must set it in the profile of the user or group that runs the application.

You can also set COMMIT directly from a Maintain Data procedure.

Set COMMIT

SET COMMIT={ON|OFF}

SYS_MGR.FOCSET("COMMIT" "{ON|OFF})"

Sharing Access to FOCUS Data Sources

The FOCUS DBMS ensures transaction integrity when multiple users are trying to access the same data source concurrently. If you are processing a transaction and, in the interval between beginning your transaction and completing it, the segments updated by your application have been changed and committed to the data source by another user, Maintain Data will roll back your transaction. This coordination is performed by the FOCUS Database Server. You can test if your transaction was rolled back by checking the value of the FocCurrent transaction variable, and then branch accordingly.

This strategy, where FOCUS verifies that the records to which you wish to write have not been written to by another user in the interim, is called change verification. It enables many users to share write access to a data source, and grants update privileges for a given record to the first user that attempts the update.

Change verification takes advantage of the fact that two users rarely try to update the same record at the same time. Some DBMSs use strategies that lock out all but one user. Others grant update privileges to the first user that retrieves a record, even if he or she is the last one ready to update it, resulting in a performance bottleneck. In contrast, the FOCUS DBMS strategy of change verification enables the maximum number of users to access the same data concurrently, and makes it possible to write the maximum number of transactions in the shortest time. The FOCUS Database Server and change verification strategy are designed for high-performance transaction processing.

How the FOCUS Database Server and Change Verification Work

The change verification strategy of the FOCUS Database Server is an extension of basic transaction processing. Each application user who accesses the FOCUS Database Server is known as a client. To ensure transaction integrity follow this simple change verify protocol:

1. As always, use the NEXT or MATCH commands to retrieve the data source records you need for the current transaction. When the application issues these commands, the server sends the application a private client copy of the records.
   Note: Do not retrieve data from a data source by running a report procedure. The FOCUS Database Server does not check this data for changes when you attempt to commit a transaction.
2. When the application issues a data source write command (such as INCLUDE, UPDATE, REVISE, or DELETE) against the retrieved records, it updates its private copy of the records.
3. When the application issues a COMMIT command to indicate the end of the transaction, the application session sends a log of the transaction back to the server. The server now checks to see if any of the segments that the transaction changed have, in the interim, been changed and committed to the data source by other clients, and if any segments that the transaction added have, in the interim, been added by other clients. You can customize which segments the FOCUS Database Server checks for changes by setting the PATHCHECK server parameter, as described in Ensuring Transaction Integrity for FOCUS Data Sources.

   The server takes one of the following actions:

   • No conflict. If none of the records have been changed or added in the interim, then the transaction is consistent with the current state of the data source. The server writes the transaction to the data source and sets the FocCurrent transaction variable of the application to zero (0) to confirm the update.
   • Conflict. If any records have been changed in the interim, then the transaction might be inconsistent with the current state of the data source. The server ignores the transaction changes to the data source, rolls back the transaction, and alerts the application by setting FocCurrent to a non-zero (0) number.
4. The application evaluates FocCurrent and branches to the appropriate function.

Selecting Which Segments Will Be Verified for Changes

When you use a FOCUS Database Server, you can customize the change verification process by defining the segments for which the FOCUS Database Server will verify changes. You define this, using the server parameter described in Ensuring Transaction Integrity for FOCUS Data Sources.

You can choose between:

• All segments in the path. The FOCUS Database Server verifies that all segments in the path extending from the root segment to the target segment have not been changed and committed in the interim by other users.
• Modified segments only. The FOCUS Database Server determines which segments you are updating or deleting, and verifies that those segments have not been changed and committed in the interim by other users.

You can set PATHCHECK for each FOCUS Database Server, which affects all applications that access FOCUS data sources managed by that FOCUS Database Server. To set it under:

• Windows and UNIX, issue the SET PATHCHECK command in the batch file (EDASTART.BAT) that starts the FOCUS Database Server.
• OS/390 and MVS, issue the SET PATHCHECK command in the FOCUS Database Server profile (HLIPROF).

Set PATHCHECK

SET PATHCHECK={ON|OFF}

Identifying the FOCUS Database Server

To identify which FOCUS Database Server will manage access to a given FOCUS data source, you must issue a command that associates the server with the data source, as described in Ensuring Transaction Integrity for FOCUS Data Sources.

You can issue this command:

• Comprehensively, for all users on a WebFOCUS Reporting Server. Issue the USE command in the server profile (EDASPROF).
• Individually, for each user on a WebFOCUS Reporting Server. Issue the USE command in the user server profile (PROFILE). The user in this case is the user account that launches the application.

Identify a FOCUS Database Server With USE

USE 
datafile ON server_id 
[datafile ON server_id]
.
.
.
END

Using Report Procedures and a FOCUS Database Server

When a FOCUS Database Server manages access to a FOCUS data source, each logical transaction that accesses that data source works with its own private copy of the data source records. This ensures that the transaction sees a consistent image of the data source that is isolated from changes being attempted by other users.

App Studio procedures, such as report procedures, are not part of a logical transaction. When control passes from a Maintain Data procedure to an App Studio procedure, the open transaction is suspended for the duration of the App Studio procedure. Therefore, if the App Studio procedure reports against a FOCUS data source, it accesses the live data source. It does not open the private copy of the transaction. Changes made by the open transaction are not seen by the report, and changes committed by other users since the open transaction began are seen by the report, though not necessarily by the open transaction.

For similar reasons, you should not use a report procedure to retrieve data for use in a transaction. The FOCUS Database Server does not check this data for changes when you attempt to commit a transaction. Always use the NEXT or MATCH commands to retrieve transaction data.

If you wish to deploy App Studio procedures containing report requests to a WebFOCUS Reporting Server that also hosts Maintain Data procedures, you must represent the server as two different outbound nodes, and deploy App Studio reporting procedures to one node and Maintain Data procedures to the other node, as described in Ensuring Transaction Integrity for FOCUS Data Sources. Otherwise, the App Studio procedures may interfere with your transaction logic.

Accessing Report Procedures When Using a FOCUS Database Server

If you are using a FOCUS Database Server and you wish to access Maintain Data procedures and App Studio report procedures that are located on the same WebFOCUS Reporting Server (referred to here as the target server), you must:

1. Represent the target server as two different outbound nodes:
   • Each WebFOCUS Reporting Server that executes Maintain Data procedures or App Studio procedures that are located on the target server.

   This requirement also applies to the target server itself. If it executes Maintain Data procedures or App Studio procedures that are deployed on itself, it must be represented to itself as two outbound nodes.

2. Of the procedures that you will be deploying to the target server, deploy the App Studio report procedures to one of these outbound nodes, and deploy the Maintain Data procedures to the other outbound node.

This is necessary because deploying both types of procedures to the same outbound node can cause report logic to corrupt transaction integrity.

Access Maintain Data and ibi WebFOCUS App Studio Report Procedures on the Same Server

Procedure
1. Represent the target server as two outbound nodes that have different remote server names but the same protocol options (for the TCP/IP protocol, this means specifying the two nodes with the same IP address, port number, and compression setting).
2. Represent the target server to WebFOCUS Reporting Servers as two outbound nodes. Perform this step for each WebFOCUS Reporting Server that executes Maintain Data procedures or App Studio procedures that are deployed on the target server. This requirement also applies to the target server itself. If it executes Maintain Data procedures or App Studio procedures that are deployed on itself, it must be represented to itself as two outbound nodes.

   As in step 1, define the two outbound nodes as having different remote server names but the same protocol options (for the TCP/IP protocol, this means specifying the same IP address, port number, and compression setting). You can do this by copying the target server node block, as described in the WebFOCUS Reporting Server Ensuring Transaction Integrity for FOCUS Data Sources, and paste it just below the end of the original block. The node block begins with the NODE keyword and continues through the END keyword. Edit the pasted block to provide a new eight-character node name, but leave the other values unchanged.

   If the WebFOCUS Reporting Server is the target server, then copy the target server node block from the App Studio odin.cfg file and paste it twice, into the communications configuration file of the target server. Edit the second pasted block to provide a new eight-character node name, but leave the other values of the block unchanged.

   For information about the name and location of the communications configuration server file, see Ensuring Transaction Integrity for FOCUS Data Sources.

3. Deploy the application.

Communications Configuration File Location and Name

Sharing Data Sources With Legacy MODIFY Applications

A FOCUS data source being managed by a FOCUS Database Server can be accessed by both Maintain Data applications and legacy MODIFY applications. Note that while MODIFY allows creating records with duplicate keys, Maintain Data does not support FOCUS data sources that have duplicate keys.