gtpm1m3wTPF V4R1 Migration Guide: 3.1 to 4.1

Virtual-Equals-Real (VEQR) Operating Mode

This release supports an operating mode for testing that provides limited virtual function to help you convert from a nonvirtual to a virtual TPF system. This operating mode is called virtual-equals-real (VEQR) mode.

In VEQR mode, ECB virtual memory (EVM) addresses are the same as system virtual memory (SVM) addresses. This means that addresses used are the same for all ECBs. Because ECBs must see storage under 16 MB, all working storage is carved under 16 MB.

VEQR mode allows you to run E-type programs that are unchanged from the TPF 3.1 system, even though the programs share data using techniques that are no longer supported. When unsupported storage sharing is discovered, the TPF 4.1 system logs the incident using the snapshot dump facility. This allows you to locate and correct code that will not function in a production TPF 4.1 system. In the meantime, VEQR mode allows the program to function. You can activate and deactivate VEQR logging (which notifies you where the problems are) with the new ZSTRC command.

VEQR mode provides the following functions:

By using VEQR mode in a test environment, you can test individual programs as you make changes, before modifying your entire application program for the TPF 4.1 system. This allows you to migrate your application programs to the TPF 4.1 system gradually.

You can change a TPF 4.1 system to VEQR mode by issuing the ZSYSG command, and re-IPLing. See Testing the Migration (Virtual-Equals-Real (VEQR) Mode) for more information about VEQR mode.

Because VEQR mode has a substantial impact on performance and limits storage, it is not intended for production use.

Testing the Migration (Virtual-Equals-Real (VEQR) Mode)

The TPF 4.1 system provides a new operating mode, called virtual-equals-real (VEQR, pronounced V equals R) for testing. VEQR mode allows you to run your unchanged TPF 3.1 E-type programs, and identifies places where you need to change programs to run properly in a virtual (TPF 4.1) environment (if you want this information).

In the TPF 3.1 system, there was only one view of main storage and all addresses were real. All ECBs and all storage blocks used by the system shared working storage, which meant that ECBs could corrupt storage that other ECBs were using.

In the TPF 4.1 system, each and every ECB has a different view of main storage. The layout of storage is the same for both the system virtual memory (SVM) and the ECB virtual memory (EVM) except in two areas:

See Figure 6 for more information the virtual storage layout.

Each ECB has its own private areas that are not shared by other ECBs and, therefore, cannot be corrupted by other ECBs.

How Virtual-Equals-Real (VEQR) Mode Works

In virtual-equals-real (VEQR) mode, system virtual memory (SVM) addresses are the same as ECB virtual memory (EVM) addresses, so the SVM is identical to every EVM (except in the heap private area). In the TPF 3.1 system, 2 ECBs could share a storage block if one ECB created a second ECB and passed the address of the storage block to the second ECB. ECBs cannot do this in the TPF 4.1 system.

For example, imagine you have a program that creates an ECB and tries to pass an address to a second ECB. See Figure 11 for more information about VEQR addressing.

In Figure 11, the following occurs:

  1. A request for an ECB results in the creation of the first ECB, ECB1, and the first ECB virtual memory, which is EVM1. The new ECB, which is ECB1, is now in both the SVM and EVM1 at the same address.
  2. ECB1 requests data from a file (located in either virtual file access (VFA) or on DASD). The file service routine places the data into a 4 KB frame (labeled A in the figure) so that programs can access it. Data area A is now in both the SVM and EVM1 at the same address.
  3. ECB1 creates another ECB, ECB2 (and another EVM, which is EVM2) and passes the address of data area A to this new ECB.
  4. ECB2 attempts to access data area A but fails because, according to the page and segment tables for EVM2, this address is not valid. Data area A exists in EVM1 but not in EVM2, so ECB2 cannot access it. This type of data sharing, where two ECBs both use the same data area, is not supported in the TPF 4.1 system. The TPF 4.1 system, in VEQR mode, detects the error and takes a SNAPC dump to log the illegal storage reference.
  5. Because every data area has a unique address that remains constant across all EVMs and the SVM in VEQR mode, the TPF 4.1 system corrects the page and segment tables for EVM2 using the page and segment tables for the SVM, allowing ECB2 to access data area A and continue processing. At this point, both ECBs have data area A in their own ECB area.
    Note:
    This is not supported in normal TPF 4.1 mode, so the code that does the illegal storage referencing must be fixed before it will run successfully in a production (normal mode) TPF 4.1 system.

Figure 11. Virtual-Equals-Real (VEQR) Addressing Example




Starting and Stopping Virtual-Equals-Real (VEQR) Mode

If you want to run virtual-equals-real (VEQR) mode without being notified of the places where you need to change your programs to run properly in a virtual environment, you can turn off VEQR logging by using the ZSTRC command by entering ZSTRC ALTER NOVRLOG. VEQR will continue to correct bad page references without notifying you. To turn on VEQR logging again, enter ZSTRC ALTER VRLOG.

To Run in VEQR Mode

  1. Enter the ZSYSG ALTER VEQR command.
  2. Re-IPL the TPF 4.1 system.

To Stop in VEQR Mode

  1. Enter the ZXYSG ALTER NOVEQR command.
  2. Re-IPL the TPF 4.1 system.