EDIF—Edit interface

The Edit Interface (EDIF) service provides edit functions for data accessed through dialog-supplied I/O routines. The invoking dialog must perform all environment-dependent functions such as file allocation, opening, reading, writing, closing, and freeing. The dialog is also responsible for any Enqueue/Dequeue serialization that is required. With the dialog providing the I/O routines, EDIF allows you to:

Edit data other than partitioned data sets or sequential files such as subsystem data, and in-storage data.
Do preprocessing and post-processing of the data being edited.

The invoking dialog must provide addresses to routines that:

Read the data sequentially from beginning to end, returning to Edit one record on each invocation.
Write the data sequentially from beginning to end, accepting one record from Edit on each invocation.
Perform processing for the MOVE, COPY, CREATE, REPLACE, and EDIT primary commands. If this routine is not specified, ISPF processes these commands.

All addresses must be 31-bit addresses, and the routines must have an addressing mode (AMODE) of 31.

When an Edit session is operating in recovery mode, a record of your interactions is automatically recorded in an ISPF-controlled data set. Following a system failure, you can use the record to recover the data you were editing.

Note: Dialogs that invoke the EDIF service may invoke the EDIREC service first to determine if a pending recovery condition exists.

A dialog using EDIF can place data into the ZEIUSER dialog variable in the shared pool. When the system initializes the recovery data set, the system also saves the data in ZEIUSER in the Edit recovery table as an extension variable. This is done if RECOVERY is ON when first entering Edit or after you use the SAVE command. This data is then made available in dialog variable ZEIUSER at the time edit recovery is processed.

Command invocation format

You cannot use command procedures to invoke this service.

Call invocation format

The format for invoking EDIF can be different depending on whether you want to process a pending edit recovery. If you do not want to process a pending edit recovery, the format is:


>>-CALL--ISPLINK--('EDIFbbbb'--,-+-data-name-+--,profile-name--->
                                 '-'b'-------'                  

>--,rec-format--,rec-len--,read-routine,--write-routine--------->

>--,-+-cmd-routine-+--,-+-dialog-data-+--,-+-edit-len-+--------->
     '-'b'---------'    '-'b'---------'    '-'b'------'   

>--,-+-panel-name-+--,-+-macro-name-+--,-+-format-name-+-------->
     '-'b'--------'    '-'b'--------'    '-'b'---------'   

     .-'NObbbbbb'-.    .-'NObbbbbb'-.                       
>--,-+-'b'--------+--,-+-'b'--------+--,-+-parm-var-+--);------><
     '-'YESbbbbb'-'    '-'YESbbbbb'-'    '-'b'------'

You must use the EDIF service to recover data edited in a previous EDIF session. You must invoke the EDIREC service first to see if a recovery is pending. If you want to process a pending recovery, use this format for EDIF, specifying YES for the recovery-request parameter:


>>-CALL--ISPLINK--('EDIFbbbb'--,--+-data-name-+--,'b'--,-------->
                                  '-'b'-------'            

>--+-rec-format-+--,--+-rec-len-+--,read-routine---------------->
   '-'b'--------'     '-'b'-----'                  

>--,write-routine--,--+-cmd-routine-+--,--+-dialog-data-+------->
                      '-'b'---------'     '-'b'---------'   

>--,'b'--,'b'--,'b'--,'b'--,'b'--,'YESbbbbb');-----------------><

Parameters

data-name

This parameter allows you to specify a data name for the source data to be edited. This name appears in the title line of the default Edit panel. It is also the target data name for an edit recovery table entry when edit recovery is active. This name must not have any embedded blanks, and its maximum length is 54 characters. This name is stored in ZDSNT in the function pool.

profile-name

The name of the edit profile to be used. This parameter is required when recovery-request = NO or is not specified; otherwise, it is not allowed.

rec-format

The record format: F - fixed, V - variable. This parameter is required when recovery-request = NO or is not specified; otherwise, it is optional, but it must be the same record format that was specified when recovery was initiated for the data.

rec-len

The record length, in bytes. It must be a positive numeric value between 10 and 32760, inclusive. For variable record format, this is the maximum record length. This parameter is required when recovery-request = NO or is not specified; otherwise, it is optional, but it must be the same record length that was specified when recovery was initiated for the data.

read-routine

A fullword address indicating the entry point of a dialog-supplied read routine (required). See Read routine for more information about this parameter.

write-routine

A fullword address indicating the entry point of a dialog-supplied write routine (required). See Write routine for more information about this parameter.

cmd-routine

A fullword address indicating the entry point of a dialog-supplied routine that processes the MOVE, COPY, CREATE, REPLACE, and EDIT primary commands. See Command routine for more information about this parameter. If this parameter is not specified, ISPF processes these commands.

dialog-data

A fullword address indicating the beginning of a dialog data area. This address is passed to the dialog-supplied routines. If no address is supplied, zeros are passed to the dialog routines. This data area provides a communication area for the dialog.

edit-len

The length, in bytes, of the data to be displayed for editing. This parameter indicates that the data records should be considered to have a length shorter than rec-len during editing. Thus, the dialog may include data in the record that is not accessible for editing.

Edit-len must be a numeric value between 10 and 32760, inclusive, and must be less than or equal to parameter rec-len. Rec-len is the default. If the edit-len parameter is specified, the data that is not displayed are the bytes from (edit-len +1) to rec-len. That means the inaccessible record data is at the end of the record.

The edit-len parameter is optional when recovery-request = NO or is not specified; otherwise, it is not allowed. The edit-len parameter is not allowed when format-name is specified.

panel-name

The name of the panel to use for displaying the data. This parameter is optional when recovery-request = NO or is not specified; otherwise, it is not allowed. The default is the standard Edit data display panel. See z/OS ISPF Planning and Customizing for information about developing a customized panel.

macro-name

The name of the initial macro to be executed. This parameter is optional when recovery-request = NO or is not specified; otherwise, it is not allowed. The default is no initial macro. See z/OS ISPF Edit and Edit Macros for more information on macros.

format-name

The name of the format to be used to reformat the data. This parameter is optional when recovery-request = NO or is not specified; otherwise, it is not allowed. The default is no format. This parameter is provided to support the IBM® 5550 terminal using the Double-Byte Character Set (DBCS). This parameter is not allowed when the edit-len parameter is specified.

YES|NO (mixed-mode)

Specifies whether the data is treated as mixed-mode DBCS data. This parameter is optional when recovery-request = NO or is not specified; otherwise, it is not allowed. If YES is specified, the EDIF service treats the data as mixed-mode DBCS data. If NO (the default) is specified, the data is treated as EBCDIC (single-byte) data. This parameter is provided to support the IBM 5550 terminal using the Double-Byte Character Set (DBCS).

YES|NO (recovery-request)

Specifies whether to process a pending edit recovery that was being edited with the EDIF service when a system failure occurred. If YES is specified, the edit recovery should proceed. This function is similar to the EDREC service with the PROCESS option. If YES is specified to process the edit recovery, you must specify the read routine and write routine, but you must not specify profile name, edit-len, panel-name, macro-name, format-name and mixed-mode. If NO is specified, no edit recovery is processed; EDIF edits the specified data.

parm-var

The name of an ISPF variable that contains parameters which are to be passed to the initial macro specified by macro-name. The variable value must not exceed 200 bytes in length. If no macro name is specified, parm-var must be blank or not specified.

Dialog-supplied routines

All dialog-supplied routines are invoked using standard linkage. All addresses must be 31-bit addresses, and the addressing mode (AMODE) of the routines must be AMODE=31.

An EDIF read or write routine must have an assembler interface to be used in a call to EDIF.

The dialog-supplied read, write, and command processing routines are called directly by ISPF at the same task level (TCB) that displays ISPF screens. If you need to ensure that your program runs at the same task level as the routines, use the SELECT PGM( ) service to start your program. This may be a factor if your program expects to create or share data spaces or other task-specific resources between the main program and the read, write, or command routines.

Note:

The read, write, and command exits can be written in languages that use the Language Environment® runtime environment, provided the runtime environment has the Language Environment TRAP(ON) option set. However, a mixture of Language Environment-conforming main dialog code and service routine code is not supported. Dialogs and service routines must either all be Language Environment-conforming or all be Language Environment-nonconforming.
Language Environment applications that use the ISPF BRIF or EDIF service must use the Language Environment OS_UPSTACK option. For ISPF to invoke the user routines with a valid LE dynamic save area, the Language Environment application must issue a CONTROL LE ON service request before each BRIF or EDIF service request and a CONTROL LE OFF service request after each BRIF or EDIF service request.

Read routine

EDIF calls the read routine repeatedly to obtain all of the data records to be edited at the beginning of the Edit session. This routine is also called to obtain data records for the MOVE and COPY commands when the dialog is handling the processing for these commands. The dialog-supplied read routine is invoked with these parameters:

Fullword pointer to record data read (output from read routine)
Fullword fixed binary data length of record read if rec-format is V
Fullword fixed binary request code. Request settings are as follows:
0 Read next record
1 First read request
Fullword dialog data area address.

Write routine

EDIF calls the write routine repeatedly to write the data records, for example, whenever data changes are to be saved with the SAVE, END, and RETURN commands, and the jump function. EDIF also calls the write routine to write data records for the CREATE and REPLACE commands when the dialog is handling the processing for these commands. The write routine is given flags that indicate the source and change status for each record.

The dialog-supplied write routine is invoked with these parameters:

Fullword pointer to record data to be written.
Fullword fixed binary data length of record to be written if rec-format is V. This is the length of the nonblank portion of the record. The entire record with trailing blanks up to the maximum rec-len is available.

Fullword of source and change bits for the record. The bit representation is as follows:

Source bits:
   1 = original record
   2 = internal move              (Move line command)
   3 = internal copy/repeat       (Copy/Repeat line commands)
   4 = external move              (MOVE primary command)
   5 = external copy              (COPY primary command)
   6 = text inserted              (TE line command)
   7 = typed inserted             (Insert line command)
 
Change bits:
   8 = record changed             (global bit; set for all changes)
   9 = data overtyped              
  10 = change command             (CHANGE primary command)
         or overlay change        (Overlay line command)
  11 = columns shifted            ((,((,),)) line commands)
  12 = data shifted               (<,<<,>,>> line commands)
  13 = text change                (TE, TF, TS line commands)
  14 = record renumbered
  15-32 = unused

Multiple bits may be set on, indicating that more than one modification has occurred for the record. For example, a data record that is inserted by using the INSERT line command and is later included in a text flow operation would have bits 7 (typed inserted), 8 (change), 9 (data overtyped) and 13 (text changed) turned on.

Records read in for the initial display are flagged as original records. Whenever there is hidden data, the inaccessible portion of inserted records contains blanks. Records are copied in their entirety; that is, including both the visible and hidden portions of the data. Deleted records are not presented to the write routine.

Fullword fixed binary request code. Request settings are as follows:
    0    Write the next record
    1    First write request
    2    Last write request (final data record provided)
    3    First and last write request (only one data record)
    4    No data records to write (all records have been deleted)
Fullword dialog data area address.

Command routine

The dialog-supplied command routine, when specified, processes the MOVE, COPY, CREATE, REPLACE, and EDIT primary commands. The command routine is invoked with these parameters:

Fullword fixed binary function code word. Decimal values of function settings are as follows:
     1n  Move
     2n  Copy
     3n  Create
     4n  Replace
     5n  Recursive edit
where n is 0 (beginning of function), 1 (successful completion), or 2 (unsuccessful completion). This n value will always be 0 for a recursive Edit function; that is, the Edit request code will be 50.
Fullword dialog data area address.

To access parameters that can follow the command, the command routine must access the ZCMD dialog variable from the SHARED variable pool.

For a MOVE, COPY, CREATE, or REPLACE, the command routine initiates the processing for the requested function. When the return code from the command routine is zero, EDIF calls the read or write routine to transfer the data. After the read or write is completed, the command routine is called once more to handle any termination processing that may be required for the requested function. For example, the MOVE function would need to delete the data that was moved.

For the EDIT command, the command routine must perform all processing required to effect the desired results for the purposes of the dialog. For example, the dialog can consider the EDIT command to be an invalid command. The command routine is called only once for each EDIT command.

Return codes

When a dialog routine terminates with a return code (12 or higher or an unexpected return code), the dialog can issue a SETMSG to generate a message on the next panel display. If the dialog does not set a message, the EDIF service will issue a default message.

Read routine

0: Normal completion.
8: End of data records (no data record returned).
16: Read error. If a read error is encountered when the system builds the initial edit display, the EDIF service terminates with a return code of 20. Otherwise, the edit data is redisplayed.
20: Severe error. (The EDIF service terminates immediately with a return code of 20.)

Write Routine Return Codes

0: Normal completion.
16: Output error, return to Edit mode.
20: Severe error. (The EDIF service terminates immediately with a return code of 20.)

Command Routine Return Codes

0: Normal completion.
4: ISPF should process the requested function.
12: Command deferred; retain the command on the Command line. Edit data is redisplayed.
20: Severe error. (The EDIF service terminates immediately with a return code of 20.)

EDIF Service Return Codes

0: Normal completion, data saved.
4: Normal completion, data not saved.
16: Unexpected return code received from a dialog-supplied routine. When an unexpected return code is received, the EDIF service terminates immediately with a return code of 16.
20: Severe error; unable to continue.

After the Edit session has been terminated, control is returned to the invoking dialog with a return code indicating the completion status.

Example

This example invokes the EDIF service to edit data called EDIFDSN, which has a fixed-record format with a record length of 80 characters. An edit profile (EDIFPROF), read routine (RDRTN), write routine (WRRTN), and command routine (CMDRTN) are supplied, as is a dialog data area (MYDATA).

Call invocation

CALL ISPLINK ('EDIF    ','EDIFDSN ','EDIFPROF ','F ',80,
     RDRTN,WRRTN,CMDRTN,MYDATA);

For a more complete example of using EDIF, including dialog-supplied I/O routines and source code, see the z/OS ISPF Dialog Developer's Guide and Reference.