VIIF—View interface

The View Interface (VIIF) service provides view 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, closing, and freeing. The dialog is also responsible for any Enqueue/Dequeue serialization that is required. With the dialog providing the I/O routines, VIIF allows you to:

View 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 viewed.

The invoking dialog must provide addresses to routines that:

Read the data sequentially from beginning to end, returning to View one record on each invocation.
Perform processing for the MOVE, COPY, and VIEW primary commands (and CREATE and REPLACE commands when a write routine is specified). If this routine is not specified, ISPF processes these commands.
Write the records selected for the CREATE and REPLACE primary commands, accepting one record from Edit on each invocation.

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

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

Note: Dialogs that invoke the VIIF service may invoke the EDIREC service first to start view recovery. The VIIF service itself does not do view recovery.

A dialog using VIIF 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 View or after you use the CREATE or REPLACE commands. This data is then made available in dialog variable ZEIUSER at the time view recovery is processed.

Command invocation format

You cannot use command procedures to invoke this service.

Call invocation format

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


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

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

>--,-+-dialog-data-+--,-+-edit-len-+--,-+-panel-name-+---------->
     '-'b'---------'    '-'b'------'    '-'b'--------'   

                                          .-'NObbbbbb'-.   
>--,-+-macro-name-+--,-+-format-name-+--,-+-'b'--------+-------->
     '-'b'--------'    '-'b'---------'    '-'YESbbbbb'-'   

     .-'NObbbbbb'-.                                        
>--,-+-'b'--------+--,-+-parm-var-+--,-+-write-routine-+-------->
     '-'YESbbbbb'-'    '-'b'------'    '-'b'-----------'   

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

You must use the VIIF service to recover data viewed in a previous VIIF 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 VIIF, specifying YES for the recovery-request parameter:


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

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

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

>--,'b'--,'b'--,'YESbbbbb'--,'b'--,--+-write-routine-+--);-----><
                                     '-'b'-----------'

Parameters

data-name

This parameter allows you to specify a data name for the source data to be viewed. This name appears in the title line of the default View 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 is 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 is 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 32 760, inclusive. For variable record format, this is the maximum record length. This parameter is required when recovery-request is 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.

cmd-routine

A fullword address indicating the entry point of a dialog- supplied routine that processes the MOVE, COPY, and VIEW primary commands. This routine also processes the CREATE and REPLACE primary commands when the address of a write-routine is specified as a parameter on the VIIF call. 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 viewing. This parameter indicates that the data records should be considered to have a length shorter than rec-len during viewing. Thus, the dialog may include data in the record that is not accessible for viewing.

Edit-len must be a numeric value between 10 and 32 760, 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 bytes from (edit-len + 1) to rec-len are not displayed. That means the inaccessible record data is at the end of the record.

The edit-len parameter is optional when recovery-request is 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 is NO (or is not specified); otherwise, it is not allowed. The default is the standard View 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 is 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 is 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 is NO (or is not specified); otherwise, it is not allowed. If YES is specified, the VIIF 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 view recovery that was being viewed with the VIIF 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 view 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; VIIF views 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.

write-routine

A fullword address indicating the entry point of a dialog- supplied write routine used to handle the writing of records for the CREATE and REPLACE primary commands. If a write-routine is not supplied, ISPF handles the writing of records for the CREATE and REPLACE primary commands. See Write routine for more information about this parameter.

NO|YES (change warning)

Specifies whether a warning message is issued on the first change of data. If you specify YES, the VIIF service gives a warning when the first data change is made, indicating that data cannot be saved in View. If you specify NO, no data change warning is given.

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.

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

The dialog-supplied routines are called directly by ISPF at the same task level (TCB) that displays the 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 dialog-supplied routines can be written in languages that use the Language Environment® runtime environment. 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.

Read routine

VIIF calls the read routine repeatedly to obtain all of the data records to be viewed at the beginning of the View 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.

Command routine

The dialog-supplied command routine, when specified, processes the MOVE, COPY, and VIEW primary commands. If the address of a write-routine is specified as a parameter on the VIIF call, the command routine also processes the CREATE and REPLACE 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 view
where n is 0 (beginning of function), 1 (successful completion), or 2 (unsuccessful completion). This n value will always be 0 for a recursive View function; that is, the View 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, VIIF 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 VIEW 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 VIEW command to be an invalid command. The command routine is called only once for each VIEW command.

Write routine

VIIF 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 called repeatedly to write the data records selected for the CREATE or REPLACE command. Flags are passed to the write routine to 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).
Fullword dialog data area address.

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 VIIF 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 view display, the VIIF service terminates with a return code of 20. Otherwise, the view data is redisplayed.
20: Severe error. (The VIIF 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. View data is redisplayed.
20: Severe error. (The VIIF service terminates immediately with a return code of 20.)

VIIF service return codes

0: Normal completion, data not saved.
12: View has been disabled through the configuration table.
16: Unexpected return code received from a dialog-supplied routine. When an unexpected return code is received, the VIIF service terminates immediately with a return code of 16.
20: Severe error; unable to continue.

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

Write routine return codes

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

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

Example

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

Call invocation

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

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