EDREC—specify edit recovery handling

The EDREC service initializes an edit recovery table, determines whether recovery is pending, and takes the action specified by the first argument.

Note: Dialogs that invoke the EDIT service should invoke the EDREC service first to start edit recovery, because the EDIT service does not perform edit recovery.

When you invoke the EDREC service, EDREC displays a special panel. Using this panel you can recover data, cancel recovery, defer recovery until a later time, or enter the END command to return to the next sequential command in your command invocation or to return to the next sequential instruction in your program.

The EDREC service attempts to use the panel that you specified in the EDIT service from which it is recovering. Make sure that this panel is available to the EDREC service. It must be in a library allocated to ISPPLIB or available through a LIBDEF.

Note: You can use the ZEDUSER variable to save LIBDEF information or the panel name when you invoke EDIT. This is different from edit recovery entered from option 2, because option 2 always uses its default panel.

Command invocation format


>>-ISPEXEC--EDREC----------------------------------------------->

>--+-INIT--+-------------------+----------------------------+--><
   |       '-CMD(command-name)-'                            |   
   +-QUERY--------------------------------------------------+   
   +-PROCESS--+----------------------+--+-----------------+-+   
   |          '-PASSWORD(pswd-value)-'  '-DATAID(data-id)-' |   
   +-CANCEL-------------------------------------------------+   
   '-DEFER--------------------------------------------------'

Call invocation format


>>-CALL--ISPLINK--('EDRECbbb'----------------------------------->

>--+-,'INIT--'--,-+-command-name-+---------------+--);---------><
   |              '-'b'----------'               |       
   +-,'QUERY--'----------------------------------+       
   +-,'PROCESSb'--,-+-pswd-value-+-,-+-data-id-+-+       
   |                '-'b'--------'   '-'b'-----' |       
   +-,'CANCELbb'---------------------------------+       
   '-,'DEFERbbb'---------------------------------'


>>-CALL--ISPEXEC--(buf-len,--buffer);--------------------------><

Parameters

INIT

Initializes an edit recovery table in your profile library if one does not already exist for the current application. The edit recovery table is saved in the data set allocated to ddname ISPPROF in member xxxxEDRT, where xxxx is the ISPF application ID.

command-name

A CLIST or REXX exec that starts the table. If you omit this parameter, the INIT option invokes an ISPF-supplied CLIST named ISREDRTI. ISREDRTI creates an eight-row edit recovery table, permitting eight levels of concurrent Edit sessions with recovery active. The Edit sessions can result from recursion or split-screen usage.

If you specify a command with the INIT option, the command should be patterned after ISREDRTI. It can create a different number of rows or use a different naming convention for the backup data sets, or specify "keep" instead of "delete" as the backup data set disposition. The format of the edit recovery table must be the same as that specified in ISREDRTI.

QUERY

Causes EDREC to search the edit recovery table for a pending recovery. When the QUERY option is specified, EDREC scans the edit recovery table for an entry containing a recovery pending condition. If the return code is 4, indicating an entry was found, the dialog must call EDREC with the PROCESS, CANCEL, or DEFER option.

EDREC QUERY is usually used in a loop, since there can be more than one pending recovery. Multiple recoveries can result from recursion or from split-screen usage of the dialog. Each subsequent call to EDREC with the QUERY option scans the table starting at the entry after the last one that was found. A typical loop, written in pseudo-code (showing the parameters themselves instead of sample values), is as follows:

SET DONE = NO
DO WHILE &DONE = NO
  ISPEXEC EDREC QUERY
  IF &LASTCC = 4 THEN -
    ISPEXEC EDREC PROCESS
  ELSE -
    SET DONE = YES
  END

As the preceding example shows, EDREC QUERY must be used before each invocation of any of these EDREC functions: PROCESS, CANCEL, or DEFER.

The variables shown are stored in the dialog function pool when EDREC is called with the QUERY option and the return code is 4, indicating that recovery is pending.

ZEDBDSN: Backup data set name.
ZEDTDSN: Target data set name.
ZEDTMEM: Target member name, if applicable.
ZEDTVOL: Volume serial of target data set, if a volume serial was specified on invocation of the EDIT service.
ZEDROW: Row number of entry in edit recovery table.

The dialog can check the preceding variables and use them to display information to the user. If EDREC QUERY shows that recovery is not pending, the previous variables are not meaningful.

ZEDUSER is an extension variable in the Edit Recovery Table that is provided to contain user data. Whatever data is in dialog variable ZEDUSER in the shared pool is saved to the ZEDUSER variable in the edit recovery table when the recovery data set is initialized. This is done if RECOVERY is ON when entering Edit or after using the SAVE command.

When EDREC is called with the QUERY option and the return code is 4, indicating that recovery is pending, or if ISPF option 2 edit recovery takes place, the data is read out of ZEDUSER in the table and returned to ZEDUSER in the shared and function pools. If recovery is not pending, this variable is not meaningful. The extension variable ZEDMODE indicates whether this is an edit session or a view session that is to be recovered.

PROCESS

Causes edit recovery to proceed.

pswd-value

The MVS™ password of the target data set. This parameter is valid only with the PROCESS option.

data-id

The data ID of the data set that will contain the recovered data. The recovered data should be saved in a data set other than the data set that was being edited when the system failure occurred. If you omit this parameter, EDREC attempts to save the recovered data in the original data set.

Before using the data ID parameter, the dialog must first invoke the LMINIT service to specify the target data set and then pass the data ID to the EDREC service. This procedure can also control the allocation of the target data set for recovery, even if it is not the original data set being edited. You must use this procedure if you originally specified the data set being edited to the EDIT service using the ddname interface.

CANCEL

Cancels edit recovery. The backup data set is erased and the corresponding entry in the edit recovery table is freed.

DEFER

Defers edit recovery. Recovery is canceled, but the backup data set is saved so that recovery can be processed in another Edit session.

Attention:

Use this parameter carefully. It can cause your original data set to be written over in the next Edit session.

buf-len

A fullword fixed binary integer containing the length of the buffer parameter.

buffer

A buffer containing the name of the service and its parameters in the same form as they would appear in an ISPEXEC invocation for a command invocation.

Return codes

These return codes are possible:

0

Normal return.

INIT: Edit recovery table was successfully created.
QUERY: Recovery is not pending.
PROCESS: Recovery was completed and the data was saved.

4

Normal return.

INIT: Edit recovery table already exists for current application.
QUERY: Entry found in edit recovery table; recovery is pending.
PROCESS: Recovery was completed, but user did not save data.

20

Severe error; unable to continue.

Examples

Here are some examples of the EDREC service:

Example 1:

This example invokes the EDREC service for INIT to create an edit recovery table if one does not exist.

Command invocation

ISPEXEC EDREC INIT

Call invocation

CALL ISPLINK ('EDREC   ', 'INIT    ');
OR

Set the program variable BUFFER to contain:

BUFFER = 'EDREC INIT';

Set the program variable BUFLEN to the length of the variable BUFFER. Issue the command:

CALL ISPEXEC (BUFLEN, BUFFER);

Example 2:

This REXX exec invokes the LMINIT service in preparation for the EDIT service call. Then, it invokes the EDREC service to create an edit recovery table if one does not exist. The exec then uses the QUERY parameter of the EDREC service to see if edit recovery is pending. If it is, then it displays the edit recovery panel, ISREDM02, and process the response. If recovery is requested from ISREDM02, the EDREC service is called with the PROCESS parameter; otherwise, the EDREC service is called with the DEFER parameter. The EDREC QUERY is invoked from within a loop so that all pending edit recovery sessions can be processed. After edit recovery processing is complete, the EDIT service is called, followed by an LMFREE to free the data ID set by the LMINIT service.

/* REXX exec to use edit recovery prior to edit */
address ispexec
'lminit dataid(data1) dataset(private.source)'
if rc = 0 then
  do
    'edrec init'                            /* create recovery table */
    do until edrc/=4 | edcon = 0
      'edrec query'                         /* check for recovery ds */
       edrc = rc
       if edrc=4 then
         do
           z1=zedtdsn                      /* set up panel variable  */
                                             /* and show recovery panel*
           'display panel(isredm02) cursor(zcmd)'
           if rc = 0 & substr(zedcmd,1,1)=' ' then
             do
               'edrec process'             /* process recovery       */
               edcon = 0                   /* and end loop           */
             end
           else if rc = 0 & substr(zedcmd,1,1)='c' then
             'edrec cancel'
           else
             'edrec defer'
         end
    end
    'edit dataid('data1') member(sample)'
    'lmfree dataid('data1')'
  end