Editor Work File

This document describes structure, use and maintenance of the editor work file under the various operating systems.

The section covers the following topics:

See also:


Editor Work File Structure

The editor work file is a relative record data set with fixed length records. It is divided into three parts:

Note:
If you use an editor auxiliary buffer pool defined by the profile parameter EDPSIZE, no editor work file is required.

Control Record

The control record contains buffer pool control information including the buffer pool parameters.

During the first initialization of the work file or during a buffer pool cold start (triggered by editor buffer pool subparameter COLD), the values defined in the editor buffer pool parameter EDBP and/or in the corresponding macro NTEDBP are saved in the work file control record. Moreover, the current operating system Id (system variable *HOSTNAME) and the global buffer pool name or the current job name are saved for subsequent verification.

You can modify the control record by using the Generation Parameters function of the SYSEDT Utility.

For buffer pool warm restarts, the buffer pool parameters are read from the control record.

Work Records

The work records contain logical file records which have been moved out of the buffer pool due to a lack of free buffer pool blocks.

Logical work file records are lost during a restart of the buffer pool or if a timeout occurs for the logical file.

Recovery Records

The recovery records hold checkpoint information of editor sessions. If the system terminates abnormally, this information can be used by the editor recovery facility to recover logical files. Recovery records are lost during a cold restart of the buffer pool.

The recovery facility is used by Natural ISPF only. If you do not intend to use this product, you can run without the recovery part by defining the editor buffer pool subparameter PWORK=100.

Editor Work File under z/OS, z/VSE and BS2000/OSD

One editor work file corresponds to one Editor Buffer Pool. If you intend to use a global editor buffer pool, the editor work file must be shared by all users using the same global editor buffer pool. The accessed editor work file can be used only by sessions within the same operating system (system variable *HOSTNAME) and with the same global buffer pool or the same job name for local buffer pools. This connection can be dropped by a buffer pool cold start only. Alternatively, the Software AG editor work file formatting utility can be used to reset the work file connection.

The editor work file must be large enough to contain the editor sessions of all users. A minimum number of 100 records per editor user is recommended. The record length of the work file must be fixed, can be defined from 504 to 16384 bytes, and must be a multiple of 8.

Note:
The record length of data sets or PDS members, which will be edited with Natural ISPF, cannot be larger as the record length of this editor work file.

The size of a work file record is specified either when allocating the editor work file (under z/OS and z/VSE; default size is 4088) or by definition in the buffer pool parameter macro (under BS2000/OSD; default size is 4096).

The total number of editor work file records depends on the allocated data set space for the editor work file.

There are two alternative ways of formatting the editor work file:

  • offline by using the Software AG editor work file formatting utility,

  • online during buffer pool initialization.

Using the Software AG Editor Work File Formatting Utility

This method is to be preferred, because no online user has to wait until formatting is finished. Optionally, the Natural parameter module may be assembled and linked to the Software AG editor work file formatting utility to specify editor buffer pool parameters by means of the macro NTEDBP. Otherwise, the default parameter values apply.

During reformatting, however, the work file must not be in use, which means that the system(s) using the corresponding buffer pool have been terminated before reformatting.

Formatting during Initialization

When the editor buffer pool is in uninitialized or terminated state, then during the first session which uses the Software AG editor, a "buffer pool cold start" is performed on one of the following conditions:

  1. if the work file has not been formatted yet,

  2. if the control record indicates "cold start" (which can also be specified by using the Editor Buffer Pool Administration utility SYSEDT),

  3. if the buffer pool subparameter COLD=ON was specified.

Otherwise, a buffer pool warm start is performed if a valid control record is found during buffer pool initialization. In this case, all buffer pool parameters are taken from the work file control record and no records are formatted.

Maintaining the Editor Work File under z/OS and z/VSE

If you want to change the size of the editor work file (for example, because it is too small), the COPY function of the Software AG editor work file formatting utility can be used to avoid a buffer pool cold start; that is, the loss of the recovery records.

To copy an existing editor work file, perform the following steps:

  1. Modify any buffer pool parameters by using the SYSEDT Utility, for example, PWORK if you want to change the percentage of work records in the file.

  2. Terminate the editor buffer pool by using the System Administration Facilities of the SYSEDT Utility and ensure that no Natural session is using the editor after the buffer pool termination.

  3. Close (if necessary) and deallocate the editor work file.

  4. Rename the editor work file by using the VSAM utility IDCAMS (ALTER command).

  5. Define a new editor work file with the original name and possibly a different size, but with the same record length.

  6. Perform the following steps:

    • In the EXEC JCL card, add PARM=COPY.

    • For the renamed editor work file CMCOPY to be copied into the new work file CMEDIT, add the following card:

      Under z/OS: //CMCOPY DD...
      Under z/VSE: //DLBL CMCOPY...
    • Run the Software AG editor work file formatting utility with the new file.

  7. Check the job log for potential errors.

  8. Reallocate and (if necessary) reopen the editor work file.

  9. Use the Editor Buffer Pool Administration utility SYSEDT to check that the buffer pool and the work file have been restarted successfully.

Important:
All Natural sessions must be restarted if you want them to use the editor after the buffer pool restart.

Maintaining the Editor Work File under BS2000/OSD

If you want to change the size of the editor work file, format a new editor work file and copy the recovery records from the old work file into the new one as follows:

  1. Shutdown all systems that use the editor.

  2. Terminate the editor buffer pool.

  3. Rename the current editor work file.

  4. Create a new editor work file with the original name.

  5. Execute the editor work file formatting program with the COPY instead of the FORMAT function after having added:

    Example:

    /CAT NATEDT.WORKFILE,NATEDT.COPYFILE
    /FILE NATEDT.WORKFILE,LINK=CMEDIT,SPACE=nnn
    /LOGON
    /FILE NATEDT.COPYFILE,LINK=CMCOPY
    /FILE NATEDT.WORKFILE,LINK=CMEDIT
    /SYSFILE SYSLST=LST.NATEDFM2
    /SYSFILE SYSDTA=(SYSCMD)
    /EXEC (NATEDFM2,NATvrs.MOD)
    COPY
    /LOGOFF N

    where vrs represents the relevant product version.

See also Installing the Software AG Editor on z/OS, Installing the Software AG Editor on z/VSE, Installing the Software AG Editor on BS2000/OSD)

Editor Work File under Complete/SMARTS

SMARTS work files are located in the SMARTS Portable File System. The path must be specified with the SMARTS environment variable $NAT_WORK_ROOT. The name of the editor work file is specified with the EDBP subparameter DDNAME.

Formatting of an editor work file is only possible during buffer pool initialization (online). There is currently no tool under SMARTS to format an editor work file offline.