23. Formatted screens

The following document is a brief description of the new Formatted Screen (FSS) feature. It allows to set up simple screen definitions within a BREXX script.

For detail take a closer look at the FSS samples in the delivered Installation library BREXX.V2R5M1.SAMPLES

23.1. Delivered Samples

The relevant FSS samples are prefixed with the #-sign:

Member

Description

#TSOAPPL

Shows in a detailed usage of all FSS functions how to set up a menu and “paint” a TK4 like design

#BROWSE

A pre-packed FSS application to display data in a List Buffer instead of using SAYs

#FSS1COL

A pre-packed FSS application to generate input requests (in one column)

#FSS2COL

A pre-packed FSS application to generate input requests (distributes in two columns)

#FSS3COL

A pre-packed FSS application to generate input requests (distributes in three columns)

#FSS4COL

A pre-packed FSS application to generate input requests (distributes in four columns)

#FSS4CLX

A pre-packed FSS application to generate input requests (distributes in four columns)

23.2. FSS Limitation

The FSS screen limitation has been dropped. Now large screen widths and heights are supported.

FSS supports just one FSS Screen definition at a time. If you need to display more than one FSS Screen in your REXX application, you must close the first and set up and display the next FSS definition. Using this method, you can easily switch between different FSS Screens. It is a good idea to separate the FSS definitions in different sub-procedures; this allows their display by calling it.

23.3. FSS Function Overview

To use FSS functions in BREXX, you must import the FSS API library from BREXX.RXLIB, address and initialise it by a call to FSSINIT, be aware that FSS is a host command application that requires an ADRESS FSS command, it is sufficient to use it once at the beginning. From this time on all host, commands are directed to FSS. If it happens to be and you have to switch to another host API (e.g. ADDRESS TSO or ADDRESS SYSTEM), you can do so, but you must make sure to switch back to the FSS API by re-issuing an ADDRESS FSS command:

1/* IMPORT THE API LIBRARY */
2CALL IMPORT FSSAPI
3/* ADDRESS THE FSS SUBSYSTEM */
4ADDRESS FSS
5/* SWITCH TO FULL-SCREEN MODE */
6CALL FSSINIT

23.3.1. FSSINIT Inits the FSS subsystem

Initialise the FSS environment; this must be performed before any other FSS call: CALL FSSINIT

23.3.2. Principles of Defining Formatted Screens

You can define your formatted screen by using a series of FSSTEXT and FSSFIELD and/or some wrapped FSS functions as FSSMESSAGE, FSSCOMMAND, etc. in your REXX script. Essential parameters are, in all cases, the ROW and COLUMN positions. Be aware that consistency validations are very basic and not bulletproof at all. It is, for example, possible to accidentally re-use occupied ranges, which may lead to unwanted behaviour or results. Performing just necessary validations increases the performance of the screen handling. It is, therefore, essential that you carefully design your Formatted Screens.

23.3.3. FSSTEXT

CALL FSSTEXT 'text',row,column,[text-length],attributes

Display a text field

Parameters

  • text – text to be displayed in the screen

  • row – row where text should be placed

  • column – column where text should be placed.

  • text-length – length occupied by the text, this is an optional parameter; it defaults to the text length.

  • attributes – screen attributes, like colours, protected, high-lighted etc. For details refer to the attributes section

23.3.4. FSSFIELD

CALL FSSFIELD 'field',row,column,[length],attributes[,init-value]

Display an input field and associate it with a BREXX Variable

Parameters

  • field – field-name of an input area to be displayed on the screen

  • row – row where text should be placed

  • column – column where text should be placed.

  • length – length occupied by the text, this is an optional parameter; it defaults to the text length.

  • attributes – screen attributes, like colours, protected, high-lighted etc. For details refer to the attributes section

  • init-value – what should be displayed as content of the input field. It defaults to blank.

Note

Important Notice on the Column Position

Each text or field definition starts with the defined attribute byte, which itself is invisible but tells how the text or field appears on the screen. Therefore the original text or field-definition start at column+1.

Note

Important Notice on Screen Definitions

Be aware that all definitions provided by FSSTEXT and FSSFIELD are stacked internally. They do not create a formatted screen on the fly.

23.3.5. Attribute Definition

The attribute definitions trigger the behaviour or colours of the Formatted Screen text or input elements.

Attribute

Description

#PROT

Definition is protected (default for fsstext)

#NUM

input field must be numeric

#HI

text is displayed high-lighted

#NON

text/field-input is invisible

#BLINK

text/field blinks

#REVERSE

background is set with defined colour text appears white

#USCORE

Underscore field

Colors:

Attribute

Description

#BLUE

text or input field is of blue colour

#RED

text or input field is of red colour

#PINK

text or input field is of pink colour

#GREEN

text or input field is of green colour

#TURQ

text or input field is of turquoise colour

#YELLOW

text or input field is of yellow colour

#WHITE

text or input field is of white colour

You can combine several attribute bytes by adding them. e.g. #PROT+#BLUE combining several colours is not allowed and may lead to unexpected errors.

23.3.6. FSSTITLE

Displays a centred Title in Screen line 1

CALL FSSTITLE title-text[,attributes]

Besides the title definition the right hand 25 bytes may contain a short message in case of errors, it overwrites the title part in error situations and automatically resets it, if the enter key is used.

The error field is named ZERRSM and maybe set also by your program.

23.3.7. FSSOPTION

CALL FSSOPTION [row[,option-length[,attribute1,[attribute2]]]

Creates an OPTIONs line, typically used in a menu to select a menu option:

OPTION ===> ________________________________________________
Parameters

  • row – defaults to 2

  • option-length – defines the line length to proved the option input, default is length of the remaining line

  • attribute1 – Attribute of “OPTION”, default is #PROT+#WHITE

  • attribute2 – Attribute of the option line,default is #HI+#RED+#USCORE

23.3.8. FSSCOMMAND

CALL FSSCOMMAND [row[,option-length[,attribute1,[attribute2]]]

Creates an input line for entering menu options or commands, it appears with the “COMMAND ===>” prefix and is typically located in row 2.:

COMMAND ===> ________________________________________________
Parameters

  • row – defaults to 2

  • option-length – defines the line length to provide the command input, default is length of the remaining line

  • attribute1 – Attribute of “COMMAND”, default is #PROT+#WHITE

  • attribute2 – Attribute of the command line,default is #HI+#RED+#USCORE

23.3.9. FSSTOPLINE

CALL FSSTOPLINE prefix,[row[,option-length[,attribute1,[attribute2]]]

Create an Option/Command Line. FSSTOPLINE is a variation of FSSCOMMAND which allows the free definition of the input line prefix. It is typically located in row 2.:

MY-OPTION ===> ________________________________________________
Prefix

String which should appear in front of the input line. In the example above it is “MY-OPTION”

Row

defaults to 2

Option-length

defines the line length to provide the command input; default is the length of the remaining line

Attribute1

Attribute of “COMMAND”, default is #PROT+#WHITE

Attribute2

Attribute of the command line, default is #HI+#RED+#USCORE

23.3.10. FSSMESSAGE

CALL FSSMESSAGE [row[,attribute]]

Creates a message line to display messages. The message line occupies a full-screen line.

param row

defaults to 3

param attribute

attribute of message line, default is #PROT+#HI+#RED

A call to FSSZERRLM sets the Message

23.3.11. FSSZERRSM

Set Error/Warning/Info Short Message. The message is set in Field ZERRSM. ZERRSM is automatically created by using an FSSTITLE definition; otherwise, it must be defined explicitly. If implicitly used with the FSSTITLE definitions, it starts on the right-hand side after the end of the message; its length is dependant on the length of the title.

CALL FSSZERRSM 'message'

23.3.12. FSSZERRLM

Set Error/Warning/Info Long Message. The message is set in Field ZERRLM, which has been defined on the screen by a CALL FSSMESSAGE.

CALL FSSZERRLM 'message'

23.3.13. FSSFSET

Set Field Content

CALL FSSFSET 'field',content

Make sure the field-name is enclosed in quotes; otherwise, there is a chance of unwanted substitution by its value!

23.3.14. FSSFGET

Get current Field Content .. function:: Value=FSSFGET(‘field’)

Make sure the field-name is enclosed in quotes; otherwise, there is a chance of unwanted substitution by its value!

23.3.15. FSSFGETALL

Get Contents of all Fields

Number=FSSFGETALL()

All field contents of the screen are fetched and stored in the associated BREXX fields defined by FSSFIELD(…)

23.3.16. FSSCURSOR

Set Cursor to a Field .. function:: CALL FSSCURSOR ‘field’

23.3.17. FSSCOLOUR

Change Colour of a Field

CALL FSSCOLOUR 'field',colour-attribute alternatively
CALL FSSCOLOR 'field' ,colour-attribute

23.3.18. FSSKEY

Return Key entered. When the user presses an action-key on a screen the used key value to return control can be accessed by FSSKEY. The optional parameter CHAR returns it in a translated readable form if not set the value returned is the decimal value assigned to the action key.

key=FSSKEY([CHAR])

By FSS supported keys:

REXX Variable

Numeric Value

Translated Value

#ENTER

125

ENTER

#PFK01

241

PF01

#PFK02

242

PF02

#PFK03

243

PF03

#PFK04

244

PF03

#PFK05

245

PF05

#PFK06

246

PF06

#PFK07

247

PF07

#PFK08

248

PF08

#PFK09

249

PF09

#PFK10

122

PF10

#PFK11

123

PF11

#PFK12

124

PF12

#PFK13

193

PF13

#PFK14

194

PF14

#PFK15

195

PF15

#PFK16

196

PF16

#PFK17

197

PF17

#PFK18

198

PF18

#PFK19

199

PF19

#PFK20

200

PF20

#PFK21

201

PF21

#PFK22

74

PF22

#PFK23

75

PF23

#PFK24

76

PF24

#CLEAR

109

CLEAR

#RESHOW

110

RESHOW

23.3.19. FSSDISPLAY

Displays or Re-Displays the active screen.

CALL FSSDISPLAY
CALL FSSREFRESH

23.3.20. Get Screen Dimensions

width=FSSWidth()
Returns

number of available columns defined by Emulation

height=FSSHeight()
Returns

number of available rows defined by Emulation

23.3.21. Close FSS Environment

Once the Screen Handling is finished it is recommended to terminate the FSS environment with one of:

CALL FSSTERM
CALL FSSTERMINATE
CALL FSSCLOSE

23.4. Creating a Dialog Manager

To handle user’s action-keys, you can set up a simple Dialog Manager, as shown in this example:

 1/* ---------------------------------------------------------------------
 2* Display screen in primitive Dialog Manager and handle User's Input
 3* ---------------------------------------------------------------------
 4*/
 5do forever
 6    fsreturn=fssDisplay()           /* Display Screen */
 7    if fsreturn='PFK03' then leave  /* QUIT requested */
 8    if fsreturn='PFK04' then leave  /* CANCEL requested */
 9    if fsreturn='PFK15' then leave  /* QUIT requested */
10    if fsreturn='PFK16' then leave  /* CANCEL requested */
11    if fsreturn<>'ENTER' then iterate
12    call fSSgetD()                  /* Read Input Data */
13    /* Add input checking if needed */
14end
15call fssclose /* Terminate Screen Environment */

23.5. Simple Screen Applications

There is a simple way to create formatted screens using preformatted rexx scripts, and this allows an easy screen setup without coding all the screen definitions manually.

23.5.1. Screen with Attributes in one Column

From BREXX.V2R5M0.SAMPLES(#FSS1COL)

 1 /*          + ------------------- screen with 1 column
 2  *          !
 3  *          !    + -------------- Title line of screen
 4  *          !    !     */
 5frc=FMTCOLUM(1,'One Columned Formatted Screen',
 6     ,'1. Input ===>',
 7     ,'2. Input ===>',
 8     ,'3. Input ===>',
 9     ,'4. Input ===>',
10     ,'5. Input ===>',
11     ,'6. Input ===>',
12     ,'7. Input ===>',
13     ,'8. Input ===>',
14     ,'9. Input ===>',
15     )
16do i=1 to _screen.input.0
17   say "User's Input "i'. Input Field: '_screen.input.i
18end
19return

The above definition creates and displays this screen:

------------------------ One Columned Formatted Screen ------------------------

1. Input ===> _________________________________________________________________
2. Input ===> _________________________________________________________________
3. Input ===> _________________________________________________________________
4. Input ===> _________________________________________________________________
5. Input ===> _________________________________________________________________
6. Input ===> _________________________________________________________________
7. Input ===> _________________________________________________________________
8. Input ===> _________________________________________________________________
9. Input ===> _________________________________________________________________

After entering input and pressing enter, you receive the provided input:

------------------------ One Columned Formatted Screen ------------------------

1. Input ===> Brexx
2. Input ===> is
3. Input ===> the
4. Input ===> Best
5. Input ===>
6. Input ===>
7. Input ===>
8. Input ===>
9. Input ===>

The provided input is stored in SCREEN.INPUT.xx an can be used or printed as in this REXX script:

User's Input 1. Input Field: Brexx
User's Input 2. Input Field: is
User's Input 3. Input Field: the
User's Input 4. Input Field: Best
User's Input 5. Input Field:
User's Input 6. Input Field:
User's Input 7. Input Field:
User's Input 8. Input Field:
User's Input 9. Input Field:

23.5.2. Screen with Attributes in two Columns

From BREXX.V2R5M0.SAMPLES(#FSS2COL)

 1 /*          + ------------------- screen with 2 columns
 2  *          !
 3  *          !    + -------------- Title line of screen
 4  *          !    !     */
 5frc=FMTCOLUM(2,'Two Columned Formatted Screen',
 6     ,'1. Input ===>',
 7     ,'2. Input ===>',
 8     ,'3. Input ===>',
 9     ,'4. Input ===>',
10     ,'5. Input ===>',
11     ,'6. Input ===>',
12     ,'7. Input ===>',
13     ,'8. Input ===>',
14     ,'9. Input ===>',
15     )
16do i=1 to _screen.input.0
17   say "User's Input "i'. Input Field: '_screen.input.i
18end
19return

you get the attributes in two columns:

------------------------ Two Columned Formatted Screen ------------------------

1. Input ===> _________________________ 2. Input ===> _________________________
3. Input ===> _________________________ 4. Input ===> _________________________
5. Input ===> _________________________ 6. Input ===> _________________________
7. Input ===> _________________________ 8. Input ===> _________________________
9. Input ===> _________________________

Entered input is provided in the same way as in the one column screen example.

23.5.3. Screen with Attributes in three Columns

Just change the number of columns to 3: frc=FMTCOLUM(3,’Three Columned Formatted Screen’,

23.5.4. Screen with Attributes in four Columns

Last option is to place the attributes in four columns: frc=FMTCOLUM(4,’Three Columned Formatted Screen’,

23.5.5. Screen special Attributes

You can tailor the appearance of formatted column screens, by setting _screen.xxxx variables:

23.5.5.1. Presetting Screen input fields

Use _SCREEN.INIT.n=’input-value-as-default’, n is the reference to the field in the FMTCOLUMN definition. 1 is first, 2 second, etc.

Example:

1_SCREEN.INIT.1='FRED'
2_SCREEN.INIT.3='Flintstone'
3_SCREEN.INIT.4='FL2311'
4_SCREEN.INIT.5='Quarry'

Calling the formatted screen, you get a pre-set Screen:

------------------------ One Columned Formatted Screen ---------------------

1. First Name  ===> Fred__________________________________________
1. Family Name ===> Flintstone____________________________________
2. UserId      ===> FL2311________________________________________
3. Department  ===> Quarry________________________________________

23.5.5.2. Input field appearance

If not changed, the input fields appear with an underscore in the available length. You can change it by setting _screen.preset. If you set _screen.preset=’+’ (one character) the input field filled by the character you defined. If you use more than one character _screen.preset=’_ ‘ only the given string is displayed.

23.5.5.3. Input field length

The field length is, by default, delimited by the following field definition in the row, or by the end of the line.

If you want to limit it to a certain length by: _SCREEN.LENGTH.n=field-length n is the field number you want to set. It is sufficient to set just the field length you want to limit.

23.5.5.4. Input Field CallBack Function

Normally, if you press enter, the screen control is giving back to your rexx, and the variable content is returned. If you prefer to check the entered input while your formatted screen is still active, for example, to validate user’s input, you can define a callback function:

_screen.ActionKey='internal-subprocedure'

The internal sub-procedure must be coded without a PROCEDURE statement; else you cannot use the screen input variables

 1_screen.ActionKey='checkInput'
 2frc=FMTCOLUM(2,'Two Columned Formatted Screen',
 3...
 4return
 5/* --------------------------------------------------------------------
 6* Call Back Routine from FMTCOLUMN to check provided Input
 7* --------------------------------------------------------------------
 8*/
 9checkInput:
10  if _screen.input.1 = '' then do
11    call FSSzerrsm 'Field 1 ist mandatory'
12    call FSSzerrlm 'Please enter valid content in Field 1'
13    return 1
14end
15if _screen.input.2 = '' then do
16    call FSSzerrsm 'Field 2 is mandatory'
17    call FSSzerrlm 'Please enter valid content in Field 2'
18    return 1
19end
20...

In case of an error, your call back function can use the FSSzerrsm function, which displays a short message in the formatted screen’s title line and/or the FSSzerrlm function to display a long message. The error message is displayed in the last line of Formatted Screen. Your callback sub-procedure signals with its return code how to proceed:

Return

Description

return 0

everything ok, leave screen an pass control back to calling rexx

return 128

something is wrong, re-display the screen

return 256

something is wrong, leave the screen

return n:

field n contains wrong input, re-display screen n >0 and n<128 represents the field number in error

23.6. FSSMENU Supporting Menu Screens

To ease the creation of menu screens, you can use the FSSMENU definition. It creates the screen layout as well as the dialogue handling part.

23.6.1. Defining a Menu Screen

CALL FSSMENU 'option','note','description','action',[startRow],[startCol]
Parameters

  • option – option code which leads to performing the associated action. The option can be a numeric or alphanumeric string and its length must not exceed 2.

  • note – short description of the action to perform

  • description – long description of the action to perform

  • action – action is performed is associated option is selected TSO prefixes an action for a TSO function call or with CALL if a REXX procedure should be called.

  • startRow –

    row in which the first menu should be placed, default is 12. This parameter is only validated for the first FSSMENU definition and automatically used for each subsequent call. To achieve a row centred menu appearance, you can use the following rexx coding before the first FSSMENU definition:

    menumax=5 /* number of Menu entries
startRow=(FSSHeight()%2)-(menuMax%2+1)-3

    and pass startRow as a parameter in the FSSMENU definition

  • startCol –

    column in which the menu should be placed, default is 6. This parameter is only validated for the first FSSMENU definition and automatically used for each subsequent call. To achieve a column centred menu appearance, you can use the following rexx coding before the first FSSMENU definition:

    startcol=(FSSWidth()%2)-30

    and pass startCol as a parameter in the FSSMENU definition

The FSS menu definitions can be included within a typical FSS Screen definition to add additional fields or text parts to the formatted screen. These parts can be dynamically updated if you specify a callback procedure in the FSSMENU Display call.

The FSSMENU definition relies on the existence of the following fields (FSSMENU does not automatically generate them); they must be defined separately, either implicitly or explicitly:

  • ZCMD is defined by FSSTOPLINE or FSSCOMMAND

  • ZERRSM is defined by FSSTITLE

Example defined in a REXX script:

 1...
 2CALL FSSMENU 1,"RFE",    'SPF like" productivity tool',
 3              ,"TSO CALL 'SYS2.CMDLIB(RFE)"
 4CALL FSSMENU 2,"RPF",    'SPF like" productivity tool','TSO RPF'
 5CALL FSSMENU 3,"IM",     'IMON/370 system monitor','TSO IM'
 6CALL FSSMENU 4,"QUEUE",  'spool browser','TSO Q'
 7CALL FSSMENU 5,"HELP",   'general TSO help','TSO HELP'
 8CALL FSSMENU 6,"UTILS",
 9     ,'information on utilities and commands available','TSO HELP UTILS'
10CALL FSSMENU 7,"TERMTEST" ,'verify 3270 terminal capabilities',
11     ,'TSO TERMTEST'
12...

23.6.2. FSSMENU Displaying a Menu Screen

To display the menu and handle the selected actions, FSSMENU must be called with the $DISPLAY parameter:

returnkey=FSSMENU('$DISPLAY',[callback-procedure],[actionkey-procedure])
Parameters

  • returnkey – key used to end the dialogue handling, it is either PF03, PF04, PF15, or PF16

  • $DISPLAY – Display the menu defined before

  • callback-procedure – optional own callback procedure (internal or external) to update FSS variables or other variables. This procedure is called just before the menu is displayed and re- displayed. Therefore the variables which are defined for the menu screen and modified in the procedure are displayed with their new content. The callback procedure needs the scope of the FSSMENU variables; therefore, it must not be defined with a PROCEDURE statement. Just define the callback name with a label.

  • actionkey-procedure –

    optional own action key procedure (internal or external) to check user’s input in the command line This procedure is called when the user pressed the enter key, and the command line contains input. This input could be a simple menu option or maybe a command, which you like to process. It is also called if a PF-Key was used to request an action. PF03, PF04, PF15 and PF16 are not passed to the procedure as they trigger the standard return action. The action key procedure is called with the parameters action-key and command-line. To receive them in your procedure use:

    parse arg action, command

    Name of the above variables is of course freely selectable. To return to the calling menu, it is essential to provide a return code; this allows the menu processing to decide on the next steps.

    Return codes:

    • 0 input has been handled by the exit, re-display Menu

    • 4 input has not been handled, continue with internal checks

    • 8 exit Menu immediately

Example: Simple Display without any exits

1rckey=FSSMENU('$DISPLAY')
2say 'End Key 'rckey
3...

Example: Before Display update some variables via a callback procedure

 1rckey=FSSMENU('$DISPLAY','UPDVAR')
 2say 'End Key 'rckey
 3...
 4/* ----------------------------------------------------------------------
 5* Update some Variables before displaying the Menu
 6* ----------------------------------------------------------------------
 7*/
 8Updvar:
 9MDate=date() /* assuming MDATE/MTIME are defined in the MENU */
10MTime=time('L')
11Return
12...

Example: Before Display update some variables via a callback procedure, and check command line input via an enter-exit

 1rckey=FSSMENU('$DISPLAY','UPDVAR','CHECKKEY')
 2say 'End Key 'rckey
 3...
 4...
 5/* ----------------------------------------------------------------------
 6* Update some Variables before displaying the Menu
 7* ----------------------------------------------------------------------
 8*/
 9Updvar:
10MDate=date() /* assuming MDATE/MTIME are defined in the MENU */
11MTime=time('L')
12Return
13/* ----------------------------------------------------------------------
14* Check user's Input in command Line
15* Return code handling:
16*  0 input has been handled by exit, re-display Menu
17*  4 input has not been handled, continue with internal checks
18*  8 exit Menu immediately
19* ----------------------------------------------------------------------
20*/
21CheckKey:
22Parse arg actionkey,usercommmand
23If length(usercommand)>2 then do
24  Say usercommand' is not an Option'
25  Return 0 /* continue, command already checked */
26End
27Return 4
28/* maybe an Option, continue to option check */

23.6.3. FMTMENU Fully Defined Menu Screens

Using FSSMENU, you can define the menu lines and generate the menu handling, but it must be incorporated in a normal REXX script containing the other parts of the screen definition and handling. FMTMENU allows you the definition of a menu screen in one step, but there are additional screen definitions in the menu possible.

23.6.3.1. Definition of the Menu

CALL FMTMENU 'option','note','description','rexx-script'
Parameters

  • option – option code which leads to performing the associated action. The option can be a numeric or alphanumeric string.

  • note – the short description of the action to perform

  • description – long description of the action to perform

  • rexx-script – REXX script which performs the action when the option is selected. Note the difference, to FSSMENU, here it must be a REXX script, but it may also contain calls to TSO, etc.

An FMTMENU always contains a title line (first row) an option line (second row) a message line (last row -1 ) and a footer line (last row).

23.6.3.2. Displaying the FMTMENU Screen

To display the menu and handle the selected actions, FMTMENU must be called with the $DISPLAY parameter:

returnkey=FMTMENU('$DISPLAY','menu-title')
Parameters

  • returnkey – key which was pressed to end the dialogue handling, it is either PF03, PF04, PF15, or PF16

  • $DISPLAY – Display the menu defined before

  • menu-title – defining the menu title

23.6.3.4. Formatted List Output

The usage of SAY statements displays the standard output of a REXX script. The disadvantage you can not scroll in it. Alternatively, you can write it in a sequential file and view it after the script has ended. By using the FMTLIST command and passing a result buffer in a stem variable, you can browse in the output while your REXX script is still running.

Example REXX reads entire RXDATE Member and displays it:

1/* REXX */
2ADDRESS TSO
3"ALLOC FILE(INDD) DSN('BREXX.CURRENT.RXLIB(RXDATE)')"
4"EXECIO * DISKR INDD (STEM BUFFER."
5"FREE FILE(INDD)"
6CALL FMTLIST
7RETURN

Results:

CMD ==>                                           ROWS 00001/00199 COL 001 B01
***** ***************************** Top of Data ******************************
00001 /* REXX */
00002 /* ---------------------------------------------------------------------
00003  *  should not be used anymore, all date functions are integrated in
00004  *    DATE(<output-format>,<date>,<input-format>)
00005  * ---------------------------------------------------------------------
00006  *  RXDATE Transforms Dates in various types
00007  *  ............................. Created by PeterJ on 21. November 2018
00008  *  RXDATE(<output-format>,<date>,<input-format>)
00009  *  date is formatted as defined in input-format
00010  *    it defaults to today's date
00011  *  Input Format represents the input date format
00012  *    it defaults to 'EUROPEAN'
00013  *     Base      is days since 01.01.0001
00014  *     JDN       is days since 24. November 4714 BC
00015  *     UNIX      is days since 1. January 1970
00016  *     Julian    is yyyyddd    e.g. 2018257
00017  *     European  is dd/mm/yyyy e.g. 11/11/2018
00018  *     German    is dd.mm.yyyy e.g. 20.09.2018
00019  *     USA       is mm/dd/yyyy e.g. 12.31.2018
00020  *     STANDARD  is yyyymmdd   e.g. 20181219
...

Using the PF7 and PF8 you scroll upward and forward, PF10 and PF11 scroll left and right. M in the CMD line and PF7 moves buffer to the top, M and PF8 to the bottom. A number and PF7 or PF8 moves the buffer the specified lines up or down.

23.6.3.5. FMTLIST Prerequisites

FMTLIST always displays the content of the stem variable BUFFER. The buffer must have the general structure:

BUFFER.0

contains the number of entries in BUFFER

BUFFER.1

contains the first line

BUFFER.2

second line

…

BUFFER.n

last line

As the name is fixed, it does not need to be passed to FMTLIST.

23.6.3.6. FMTLIST calling Syntax

FMTLIST [length-line-area],[line-area-character],[header-1],[header-2],[applicationID]
Parameters

  • length-line-area – length of displayed line-area, default is 5

  • line-area-character – character which should be displayed in the line area, default is none, then the line area contains the line number

  • header-1 – this is an optional header line which is shown as first-line the displayed buffer

  • header-2 – optional second header, only if header-1 is also defined

  • applicationID – If you specify an application ID, the FMTLIST screen supports line commands. The Line commands must be defined and coded in the calling REXX script as a callback label: applicationID_linecommand.

If you use PF7/PF8 to scroll up and down, the two header lines are always displayed as the buffer top lines.

23.6.3.7. FMTLIST supported PF Keys and Scrolling commands

PF3/PF4

exit FMTLIST screen

PF7

scroll one page up

PF8

scroll one page down

PF10

shift buffer 50 columns left

PF11

shift buffer 50 columns right

PF12

Display last command

If you use a combination of a number in the command line and PF7 or PF8, the buffer scrolls the number of lines up or down.

Command-line functions:

TOP

displays the first line of the buffer

M and PF7

displays the first line of the buffer

BOTTOM

displays the last line of the buffer

BOT

displays the last line of the buffer

M and PF8

displays the last line of the buffer

23.6.3.8. FMTLIST Customising Options

By setting _SCREEN.xxxx, you can manipulate the appearance of FMTLIST in various ways:

Variable Name

Default

Allowed Values

Note

_screen.cmdchar

blank

Command Line character building the command line. Default is blank and creates an empty command line which is displayed with the 3270 attribute #USCORE

_screen.color.Cmd

#red

Attribute Definitions

Colour of Command Line

_screen.color.Stats

#white

Attribute Definitions

Colour of Statistics (line and buffer numbering)

_screen.color.Top1

#red

Attribute Definitions

Colour of line area first line

_screen.color.Top2

#blue

Attribute Definitions

Colour of line conten first line (Top of Data)

_screen.color.Bot1

#red

Attribute Definitions

Colour of line area last line

_screen.color.Bot2

#blue

Attribute Definitions

Colour of line content last line (End of Data)

_screen.color.List1

#white

Attribute Definitions

Colour of line area (content part)

_screen.color.List2

#green

Attribute Definitions

Colour of line content part

_screen.footer

undefined

Content of footer (PF1 …)

Fixed Footer Line (at screen height)

_screen.color.footer

#white

Attribute Definitions

Colour of line content part

_screen.Message

undefined

1 for defining message

Fixed Message Line (screen height-1)

_screen.TopRow

1

1 up to Screen height-3

Begin row of fmtlist, if it is 2 or more there are empty lines above FMTLIST

_screen.TopRow.proc

Undefined

Is a call-back proc name in the rexx calling FMTLIST. There you can define the line above the FMTLIST screen. They can be set with FSSfield or FSSText commands. The number of added rows must not exceed _screen.TopRow-1

_screen.BotLines

Lines reserve at bottom of FMTLIST

1 up to Screen height-3

As screen height is dynamic depending on the 3270 definitions.

_screen.BotLines.proc

Undefined

Is a call-back proc name in the rexx calling FMTLIST. There you can define the lines at the end of the FMTLIST screen. They can be set with FSSfield or FSSText commands. The first line number which can be set is passed as arg(1) parameter. For consistency reasons of call back parameters, it is enclosed in quotes. This means you must strip them off: first=strip(translate(arg(1),’’,”’”))

23.6.3.9. FMTLIST calling other REXX scripts from the command line

If you want to play another REXX script from within the FMTLIST buffer you can do so, by entering: rexx-script-name in the command command line.

Simple REXX scripts

A simple Rexx script does not contain any call to an FSS Screen. A sequence of say statements may provide the result, or you can place it in a buffer.x stem. If you do so, the result displayed in the current FMTLIST buffer. Which means the existing content is overwritten.

1Buffer.1='first line'
2Buffer.2='second line'
3Buffer.0=2

If you want to keep the contents of the current buffer, use the prefix command LOOKASIDE rexx-script-name, and a new stacked buffer is created residing on top of the previous buffer. The previous buffer can be re-activated by pressing the PF3 key; it destroys the current buffer and returns to the last buffer.

If the called rexx-script contains an FMTLIST, FSSMENU, or FMTMENU itself a new buffer is created automatically.

23.6.3.10. Formatted List Line and Primary Commands

The FMTLIST Buffer supports Line Commands if it is called with an applicationID. The line command is coded within the calling procedure (performing the FMTLIST) as a callback label, to keep the scope of the variables there must not be a PROCEDURE statement used. The callback label must be coded as: applicationID_linecommand. In the following example there is a line command S, U and D defined :

 1/* REXX */
 2ADDRESS TSO
 3"ALLOC FILE(INDD) DSN('BREXX.RXLIB(RXDATE)')"
 4"EXECIO * DISKR INDD (STEM Buffer."
 5"FREE FILE(INDD)"
 6call fmtlist ,,,,MYLIST /* MYLIST is application ID */
 7return
 8
 9/* ---------------------------------------------------------------------
10* Line commands are organised as "call-back' labels to the calling REXX
11* Format is REXX name_linecmd
12* ---------------------------------------------------------------------
13*/
14
15mylist_s: /* line command S, just output selected line */
16  say Arg(1)
17  return 0 /* tell FMTLIST to proceed normally */
18
19mylist_u: /* line command U, allow editing line */
20  newLine=lineedit(,arg(1))
21  return 4 /* tell FMTLIST, you changed line */
22
23mylist_e: /* line command E, automatically change line */
24  newLine='new Line set'
25  zerrsm='update'
26  zerrlm='Line has been updated'
27  return 4 /* tell FMTLIST, line is changed line */
28
29mylist_d: /* Delete Line */
30  return 5 /* tell FMTLIST to delete selected line */

RC Code actions

RC=0

means the line command was processed

RC=4

means the line command was processed; if the REXX variable NEWLINE contains a value, the selected line will be overwritten by this value.

RC=5

delete this line

RC=6

a completely new buffer.n stem has been provided and should be displayed immediately. The old buffer content will be removed. If you set a ZERRSM or ZERRLM message the message will be kept and displayed.

RC=7

a new buffer.n stem has been provided and should be displayed in a new FMTLIST buffer, which is stacked on top of the previous one. Once you return with PF3 you will see the old buffer content. If you set a ZERRSM or ZERRLM message the message will be kept and displayed.

RC=8

invalid line command

Additionally, you can change the colour of the line in the buffer; you have to set:

  • SETCOLOR1 sets the colour of the selected line of the line area, e.g. setcolor1=#green

  • SETCOLOR2 sets the colour of the selected buffer content line, e.g. setcolor2=#red

If none or just one of the colours have been set, the other field colour remains unchanged

23.6.3.11. Formatted List Samples

There are several scripts in BREXX.V2R5M1.SAMPLES illustrating the usage of FMTLIST.

FMTOPBOT

has an embedded FMTLIST with user-defined header and footer lines.

@STUDENTL

the front end of the VSAM student database example

#BROWSE

Displays the LISTALC command

23.6.3.12. Debugging Simple Screen Applications

If you need to debug the behaviour of simple screen applications, you can switch on a trace feature in the calling REXX script:

_screen.FTRACE=1

You get a trace of the performed step within the screen application.

 1/* REXX */
 2do i=1 to 35
 3    buffer.i='Buffer Line 'i
 4end
 5buffer.0=i-1
 6/*
 7_screen.color.top2=#yellow
 8_screen.color.mylist=#red
 9_screen.color.cmd =#blue
10_screen.color.stats=#white
11*/
12_screen.footer='PF1 Help PF3 Return PF4 Return'
13_screen.Message=1
14CALL FMTLIST ,,'','','TEST'

Displaying Trace in TSO:

09:45:27.09 Entering FMTLIST
09:45:27.18 Display Screen
***
The screen is displayed, waiting for the next user action
09:45:56.65 User Action PF08
09:45:56.69 Command Line ''
09:45:56.71 Display Screen
***
The screen is displayed, waiting for the next user action
09:46:42.13 User Action PF07
09:46:42.17 Command Line '10'
09:46:42.20 Display Screen
***
The screen is displayed, waiting for the next user action
09:47:10.09 User Action PF03
09:47:10.09 Command Line ''
***

23.6.3.13. Formatted List Monitor FMTMON

By setting up a formatted list monitor you can monitor certain events on a timely basis. You can for example continuously view updated entries of the Master Trace Table

 1CALL IMPORT FSSAPI
 2/* --------------------------------------------------------------------------
 3* FMTMON is an FSS application that refreshes itself every xxx milliseconds
 4* the refresh takes place in the call-back procedure MonTimeOut it must
 5* provide a new buffer or just return
 6* There is also an enter-key call-back procedure MonEnter where you can
 7* execute commands, e.g. CONSOLE and modify the buffer if wanted
 8* --------------------------------------------------------------------------
 9*/
10call fmtmon "MVS Trace Table",1000
11return 0

23.6.3.14. FMTMON calling Syntax

FMTMON header,[refresh-frequency]
Parameters

  • header – is displayed as title in the FMTMON screen

  • refresh-frequency – refresh timer in milliseconds

23.6.3.15. FMTMON Call-Back Procedures

FMTMON requires two call-back procedures, which must be implemented in the calling REXX procedure.

  1. MONENTER: is called when has entered input and presses the enter-key

 1/* -------------------------------------------------------------------
 2* MONENTER Call Back PROC of FMTMON Enter key pressed, do something
 3* return 0 continue normally
 4*  4 continue normally, buffer is not touched
 5*  8 end monitor (as PF3)
 6*  12 end monitor (as PF4)
 7* -------------------------------------------------------------------
 8*/
 9MonEnter:
10call CONSOLE arg(1)
11/* action requested console command */
12return 0

  1. MONTIMEOUT: is called when the frequence-time-out has been reached

 1/* -------------------------------------------------------------------
 2* MONTIMEOUT Call Back PROC of FMTMON Enter key pressed, do something
 3* Timeout in FSS, you can provide new content in
 4* BUFFER.i i=1 to number of lines
 5* BUFFER.0 must contain number of lines
 6* return 0 continue buffer is unchanged
 7* 1 continue new buffer provided
 8* -------------------------------------------------------------------
 9*/
10MonTimeout:
11/* arg(1) entry count */
12/* create new contents of FMTMON Buffer.
13return

23.6.3.16. FMTMON provide data to display

FMTMON displays the content of the stem variable BUFFER, typically it is updated in the MONTimeout call-back procedure.

The buffer must have the general structure:

BUFFER.0

contains the number of entries in BUFFER

BUFFER.1

contains the first line

BUFFER.2

second line

…

BUFFER.n

last line

As the name is fixed, it does not need to be passed to FMTMON.

23.6.3.17. FMTMON predefined Action Keys

  • Help key: PF1

  • Scrolling keys: PF7/PF8

  • Commands: TOP/BOT/UP n(-lines)/DOWN n(-lines)

23.6.3.18. FMTMON Application display Master Trace Table

This example is stored in: BREXX.V2R5M1.SAMPLES(MTT)

23.7. FSS Functions as Host Commands

Alternatively to the FSS functions described in ”FSS Function Overview” you can use the FSS Host command API directly. In this case, all definitions, calculations, validations, etc. must be handled by your REXX script directly.

23.7.1. INIT FSS Environment

Initialise the FSS environment; this must be performed before any other FSS call:

ADDRESS FSS
'INIT'

23.7.2. Defining a Text Entry

ADDRESS FSS
'TEXT 'row column attributes text'

  • text: text to be displayed on the screen

  • row: row where text should be placed

  • column: column where text should be placed.

  • attributes: screen attributes, like colours, protected, high-lighted etc. For details refer to the attributes section

23.7.3. Defining a Field Entry

ADDRESS FSS
'FIELD 'row column attributes field flen [preset]'

  • text: text to be displayed on the screen

  • row: row where text should be placed

  • column: column where text should be placed.

  • attributes: screen attributes, like colours, protected, high-lighted etc. For details refer to the attributes section

  • field: Screen field name

  • flen: length of input area representing field name

  • preset: content initially displayed (optional), defaults to blank

23.7.4. Getting Field Content

ADDRESS FSS
'GET FIELD field rexx-variable'

  • field: Screen field name

  • rexx-variable: variable receiving the field content

23.7.5. Setting Field Content

ADDRESS FSS
'SET FIELD field value'

or

ADDRESS FSS
'SET FIELD field 'rexx-variable'

  • field: Screen field name

  • value: new field content

  • rexx-variable: variable containing the field content

23.7.6. Setting Cursor to a field

Sets the cursor to the beginning of the Screen Field

ADDRESS FSS
'SET CURSOR field'

  • field: Screen field name

23.7.7. Setting Colour

Sets the Colour of a Screen Field

ADDRESS FSS
'SET COLOR field/text colour'

  • field: Screen field name

  • colour: Color definition,for details refer to the attributes section

23.7.8. Getting action Key

When the user presses an action-key on a screen, the key value can be fetched in a rexx-variable:

ADDRESS FSS
'GET AID rexx-variable'

  • rexx-variable: variable receiving the action key

23.7.9. Display or Refresh Formatted Screen

Used to display the Formatted Screen the first time, or to refresh an active screen:

ADDRESS FSS
'REFRESH'

23.7.10. End or Terminates FSS Environment

Ends the Formatted Screen environment and releases all used main storage:

ADDRESS FSS
'TERM'

23.7.11. Get Terminal Width

ADDRESS FSS
'GET WIDTH rexx-variable'

  • rexx-variable: variable receiving the action key

23.7.12. Get Terminal Height

ADDRESS FSS
'GET HEIGHT rexx-variable'

  • rexx-variable: variable receiving the action key