BRIF—Browse interface

The Browse Interface (BRIF) service provides browse 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, BRIF allows you to:

Browse data other than partitioned data sets or sequential files, such as subsystem data and in-storage data.
Do preprocessing of the data being browsed.

The invoking dialog provides addresses of routines that will:

Respond to a read request for a specific record by its relative position in the data.
Perform processing for the BROWSE primary command. If this routine is not provided, ISPF will process any request for the BROWSE primary command.

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

The dialog-supplied read, write, and command processing 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.

Command invocation format

Command procedures cannot be used to invoke this service.

Call invocation format


>>-CALL--ISPLINK--('BRIFbbbb'--,-+-data-name-+--,rec-format----->
                                 '-'b'-------'                

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

                        .-ISRBROBA---.                      
>--,-+-dialog-data-+--,-+-panel-name-+--,-+-format-name-+------->
     '-'b'---------'    '-'b'--------'    '-'b'---------'   

     .-'NObbbbb'-.      
>--,-+-'b'-------+-);------------------------------------------><
     '-'YESbbbb'-'

Parameters

data-name

This parameter allows you to specify a data name for the source data to be browsed. This name will be displayed in the Title line of the default Browse panel; if data-name is not specified, no name is displayed on the panel. This parameter must not have any embedded blanks, and its maximum length is 54 characters. This name is stored in ZDSNT in the function pool.

rec-format

The record format of the data to be browsed:

F - fixed
FA - fixed (ASA printer control characters)
FM - fixed (machine code printer control characters)
V - variable
VA - variable (ASA printer control characters)
VM - variable (machine code printer control characters)
U - undefined.

rec-len

The record length, in bytes, of the data to be browsed. For variable and undefined record formats, this is the maximum record length. This parameter must be a positive numeric value with a maximum value of 32,760 bytes.

The dialog can hide data during a Browse session by specifying the record length to be less than the actual data being browsed. By doing this, BRIF displays only the data up to the specified record length.

read-routine

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

If a read-routine displays its own panel, then a CONTROL DISPLAY SAVE should be done at the beginning of the panel and a CONTROL DISPLAY RESTORE should be done at the end.

cmd-routine

A fullword address indicating the entry point of a dialog-supplied routine that processes the BROWSE primary command or any dialog-specific primary commands. See Command routine for more information about this parameter. If this parameter is not specified, ISPF initiates a recursive Browse session to handle any request for the BROWSE primary command.

If a cmd-routine displays its own panel, then a CONTROL DISPLAY SAVE should be done at the beginning of the panel and a CONTROL DISPLAY RESTORE should be done at the end.

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.

panel-name

The name of the panel to use for displaying the data. The default is the standard Browse data display panel (ISRBROBA). Refer to z/OS ISPF Planning and Customizing for information about developing a customized panel.

format-name

The name of the format to be used to reformat the data. The default is no format. This parameter is provided to support the IBM® 5550 terminal using the Double-Byte Character Set (DBCS).

YES|NO

Specifies whether the data is treated as mixed-mode DBCS data. If YES is specified, the BRIF service treats the data as mixed-mode DBCS data. If NO 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).

Dialog-supplied routines

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

A BRIF read routine must have an assembler interface to be used in a call to BRIF.

The dialog-supplied read and command processing 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 and the read 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

The read routine is invoked with these parameters:

Fullword pointer to record data read (output from read routine)
Fullword fixed binary data length of the record read if the rec-format parameter is V, VA, VM, or U (output from read routine)
Fullword relative record number:
- Record-requested input to read routine
- Record-provided output from read routine when return code is 4 or 8.
Fullword dialog data area address.

BRIF calls the read routine as the data records are required to be displayed. Data not being displayed is not retained.

After the first screen of data is displayed, the first SCROLL DOWN MAX command results in a request to the dialog read routine for relative record number 99999999 (this is the maximum number of records allowed for browsing). The read routine is responsible for determining the relative record number of the last record in the data. It must return that last record number, and a pointer to the data with a return code of 4; the end of file is temporary, or 8, if the end of file is permanent. When BRIF receives this response, it uses the last record number to determine the relative record number of the first data record that should appear on the display (last record number minus the number of data lines on the display + 1). BRIF then calls the read routine requesting this first data display record, and subsequently requests all following records up to the last record in the data to fill the display.

The read routine should maintain the previous record number requested so that on the next read request a determination can be made whether the requested record is the next record in the data. This could save a considerable amount of processing time in the read routine, since data records are frequently requested in sequential order for partitions of data.

If an I/O error occurs while attempting to read to the end of data, the read routine returns the relative record number of the record causing the I/O error with a return code of 8. When BRIF requests this record number again to format the screen, the read routine then issues a return code of 16, indicating a read error.

The BRIF service requests and displays all additional records beyond the temporary end of data (return code 4) if you attempt to scroll down past the end of data or cause any interrupt (such as Enter) when the end-of-data line is present on the display.

If you decrease the number of records during the BRIF session, the read routine can set a new last record number that is smaller than the current value with return code 4.

When the BRIF service receives a return code 8, it sets the last record number as the permanent end of file. The BRIF service does not request any additional records beyond the permanent end of file.

Command routine

The dialog-supplied command routine, when specified, is called to process the BROWSE primary command or any dialog-specific primary commands. The Command Routine is invoked with two parameters:

A Fullword fixed binary function code indicating the type of command.
10

Recursive Browse

20

A command not recognized by browse. The command can be a dialog-specific command or an invalid command. The command routine is responsible for getting the command from the variable ZCMD and any necessary parsing of the command. If the command routine was not specified or if the command routine returns a return code of 4, BRIF issues an INVALID COMMAND message.
A 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 BRIF service will issue a default message.

Read Routine Return Codes

0: Normal completion.
4: Temporary end of file.
8: Record requested beyond end of data. The relative record number of the last data record and a pointer to the last data record are returned.
16: Read error. Browse data obtained up to the read error is formatted and displayed with an indication that a read error was encountered.
20: Severe error. (The BRIF service terminates immediately with a return code of 20.)

Command routine

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

Errors that the BRIF service cannot handle must be handled by the dialog; for example, environment-dependent errors would be processed by the dialog.

BRIF service

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

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

Example

This example invokes the BRIF service to browse data called SPOOL.DATA, which has a variable record format with a maximum record length of 132 characters. The READRTN read routine reads the data records. The CMDRTN command routine processes the BROWSE primary command and any dialog-specific primary commands.

Call invocation

CALL ISPLINK('BRIF    ','SPOOL.DATA ','V ',132,READRTN,CMDRTN,' ',
             ' ',' ','NO      ');

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