21. Func='prompt' Opening windows

Using func='prompt' in RXS opens for the programming of dialogs using windows. The programming is 'non procedural': you specify in the coding which input you want at which point in your logic, and the RXS engine generates windows and a dialogue to connect theese. The user may iterate backwards among the windows when using the dialogue - this is not an issue for the programmer but handled by RXS itself.

Example 21.1:

)action out='prm1'

'member', 'enter member name'

)endaction

)action in='prm1'

)& func='prompt'

)endaction

The first action block writes a record to the queue 'prm1'. Two parts of the record are written separately, separated by comma. The second action block reads the queue 'prm1' and uses the information to generate a window on the screen. The window will prompt the user of the dialogue to enter a value for the variable 'member'. The user may act as indicated or may press F3 (end) to terminate the dialogue. RXS generates a guiding text in the window pointing out these two possible responses.

Example 21.2:

)action out='prm1'

'member', 'enter member name'

)endaction

)action in='prm1'

)& func='prompt'

)action in='myqualif.mydsn('member')'

)& out='que1'

unit.1

)endaction

)action out='myqualif.mydsn('member')'

)& in='que1'

)& outfunc='sub'

)& start=1

if start = 1 then do

"//* This member is submitted" date()time() userid()

start = 0

end

unit.1

)endaction

)endaction

The example reads a member from a dataset, adds a new line at the top of the member, submits and saves the member. The user is prompted to enter the name of the member that is to be acted on.

Example 21.3:

)action out='prm1'

'account', 'Enter (part of) account number'

'department', 'Enter department number'

)endaction

)action in='prm1'

)& func='prompt'

)& out='sql1'

"select account, name from myqualif.mytable "

"where account like '"account"%' "

"and department = '"department"' "

)endaction

)action in='sql1'

)& func='sql'

"name: "left(name,15)" has account: "account" ,

"(department "department")"

)endaction

Here we have two queues, prm1 and sql1, and three action blocks.

The first action block writes two rows on a queue, prm1, each row containing two parts, separated by comma.

The other action block writes something (in SQL syntax) on a queue sql1.

Output from the first action block is input to the second, governed by general order func='prompt'

The window on the screen looks:

Repeating - with more precision:

func='prompt' implies that information in the input queue is used to format a window on the screen, prompting the user to enter the value for one or more variables. The format and layout of the window depends on the amount of data shown; when appropriate a full screen panel will be shown instead of a window.

• The first part of each element in the input queue names the variable which is to be assigned a value.
• The second part of each element in the input queue is a guiding text to be shown next to the name of the variable and the input field. This part of the element may be omitted. In such case, only the name of the variable and the input field is shown in the window.
• Strings in the elements of the queue are in quotes. Applies even to the name of the variable: it is not a variable; it is a string indicating the name of a variable.
• When the user has entered values for these variables (or for this variable) and presses enter, the action block having func='prompt' will be triggered once. Assigned values are at hand inside the action blocks by their names. If the user presses F3 (end) instead of enter, an optional )notrigger part of the action block is triggered. If no )notrigger is programmed, the RXS program returns to a former state according to the following rules:

21a. The dialogue generated by prompt

If a RXS program contains at least one action block which is using func='prompt', the execution of the program - as seen from the user - will go like this:

If the user presses F3 (end) when output from RXS is shown on the screen, a re-display of the first window in the dialogue will take place

If the user presses F3 (end) when a RXS window is prompting for input, a re-display of the former window in the dialogue will take place. If the current window is the first window of the dialogue (or the sole window of the dialogue) then the RXS program terminates.

If the user presses enter in the same situation, the RXS program will prompt for input in the current window or display the next window, depending on whether the user has entered some input before pressing enter.

But do not put notice on these rules: As seen from the programmer of the RXS program, this is transparent. You indicate in the program which information you want at which point in the logic - the dialogue is not programmed (but optionally may be adjusted - see below).

Commit or rollback of changes made by the RXS program is affected by the way the user handles the dialogue. The commit point in RXS is - as mentioned - just prior to the display of output from RXS. If the program never reaches this point, a rollback is performed, and no update of DB2, MQSeries or sequential files is done. Therefore, if the user reverses out of the program by pressing F3 (end) in a re-show of each previous shown windows of the program, and continues to do this until the program terminates, then nothing is committed. If the user cycles several times through the logic, pressing F3 (end) after output is displayed, commit will take place each time the program reaches the point where output is to be displayed. Messages on screen will inform of commit and rollback.

If the user makes a reverse exit of the program, backing his way out through all windows including the first window, without having ever reached a display of output, RXS will set a return code +4 to ISPF.

21b. Tailoring the dialogue using programming

If the programmer uses return in the RXS program, this will force a jump to the first window of the dialogue - if the user has already seen this window. If not, the RXS program terminates.

If the programmer uses exit in the RXS program, this will unconditionally terminate the program.

Programming a )notrigger part of an action block which is using prompt will catch when the user presses F3 (end). For instance programming exit in the )notrigger block will cause the program to terminate if the user presses F3 (end) in this window.

Programming general order outfunc='nop' means that output is not displayed. Accordingly, the user has no occasion to press F3 (end) in the termination situation. Therefore, the program terminates unconditionally when the logic of the program is executed once. The same applies if the program does not produce any sequential output (any file). These are 'ok' situations, and any changes are committed.

To validate input from the user, use instruction set_halt:

Example 21.4:

)action out='prm1'

'member', 'enter member name'

)endaction

)action in='prm1'

)& func='prompt'

if datatype(left(member,1)) = 'NUM' then do

set_halt "Member-name must start with a chararacter"

end

)endaction

If the first charater in the string entered on the screen is numeric, then the panel is re-displayed with the indicated message. If the error is corrected, the dialogue continues normally.

To put additional guidance on the input-screen, use instruction set_message:

Example 21.5:

)action out='prm1'

'member', 'enter member name'

set_message "Member-name starts with a chararacter"

)endaction

)action in='prm1'

)& func='prompt'

)endaction

The message is displayed first time the RXS program reaches a panel-display. This could be the final display of output, but in this case, it is the prompt.

21c. Tailoring the dialogue using general orders

prompt

Setting general order prompt='yrsa' will internally name the window: it now bears the name 'yrsa'. A named window will remember its content, entailing that a re-show of the window later in the same ISPF session will re-display its values. The re-display may even be initiated from another RXS program provided that the variable names and the guiding texts which are set up in the window by both programs are identical. And of course, provided that the two programs name the window identical.

The variable prompt may hold a maximum of 6 characters (Window content is saved in ISPF-tables).

A window without a name will function the same way, and remember its content, provided that no other not-identical window without a name is used in the users ISPF-session. Again, windows are considered identical if they use identical variable names with identical guiding texts.

promptsource

Setting a value for general order promptsource governs the content of the window in the event of a re-display during the TSO-session.

There are three possible values:

• 'U' (default): If the window is re-displayed, all values are re-displayed too - provided that the window is unique, according to the discussion of prompt above. If the window has not been displayed before, values assigned in the RXS program will initially be shown.
• 'P' Values assigned in the RXS program will always be shown in a re-display of the window.
• 'I' In a re-display of the window, all values are blank.

promptall

Setting a value for general order promptall governs whether the user is allowed to continue by pressing enter without entering a value in every field in the window.

There are two possible values:

· 'Y' (Default) The user must enter a value in every field. Not obeying this, an error message will prompt the user to do so if he presses enter.

· 'N' The user may do as he likes: enter a value in none, in some, or in all fields of the window when pressing enter.

promptlgth

Setting a value for general order promptlgth will determine the length of the input fields in the window. Default length is 42 characters; any other value between 0 and 130 may be entered in promptlgth.

Setting a length of zero makes it pointless to display the window. Accordingly, it is not displayed. This may be used as a mechanism for transporting variables between RXS programs: making a prompt of a named window which is holding some values will make these values part of the RXS program. This is also true if the window is not actually displayed.

caps

Setting general order caps='on' will transform any input in the window to upper case. Setting caps='off' will not transform input. caps='on' is default.

zwinttl

This general order sets a windws-title: Assigning a value to variable zwinttl in the RXS program results in that value being written in the top part of the frame of the window - as a title.

21d. A more advanced example

In this example, window content - that is the names of variables and the guiding texts - reflects data originating from DB2, instead of being stated in the program:

Example 21.6

)text out='sql1'

select distinct department from our.employee

)endtext

)text out='sql2'

select name, salary from our.employee

where department = :wdep

)endtext

)text out='sql3'

update our.employee set salary = :wsalary

where department = :wdep and name = :name

)endtext

)action insql='sql1'

)& out='prm1'

department

)endaction

)action in='prm1'

)& func='prompt'

)& prompt='prm1'

)& promptall='n'

)& zwinttl="Select department(s) entering 'X'"

)& promptlgth=1

)action in='prm1'

if value(unit.1) = 'X' then do /*if selected on screen*/

wdep = unit.1

)action insql='sql2'

)& out='prm2'

name , "(Salary: "salary")"

)endaction

)action in='prm2'

)& func='prompt'

)& prompt=left(wdep,6)

)& promptall='n'

)& promptlgth='1'

)& zwinttl=wdep": Grant a 10% salary rise entering 'X'"

)action insql='sql2'

if value(name) = 'X' then do /*if selected on screen*/

wsalary = trunc(salary * 1.1)

left(name "("wdep")",25) "is granted a 10% salary",

"rise. New salary:" wsalary

)action insql='sql3'

)endaction

end

)endaction

)endaction

end

)endaction

)endaction

It is assumed that DB2 table our.employee contains fields Department, Name and Salary. Unique key is Department + Name.

Running the example will at first show a window listing all departments:

If one or more departments are selected using an 'X', a window showing a list of all employees and their salary is shown for each selected department.

Any employee selected in this window using an 'X' will be given a 10% salary raise. The user (the manager...) may cycle between the windows using 'enter' or 'F3'.

SALES department actually contains 41 employees; therefore RXS switches to a full screen window with scrolling:

When the last one of the departments selected on the first screen is processed, a list of employees receiving a salary rise is shown (see below), and all updates are commited: the new salaries are written to DB2. If the user at any point before this final display leaves the program (pressing F3 repeatedly) all updates are rolled back, and no employee is receiving any salary rise. The user will in this situation be notified that all updates are rolled back.

If commit is reached, this is what is finally displayed: a message confirming 'commit' and a list of actions made:

EDIT MYUSER.RXS.DATA SQL commit

Command ===> Scroll ===> CSR

****** ***************************** Top of Data********************************

000001 Wrinkley (MANAGEMENT) is granted a 10% salary rise. New salary: 122611

000002 Marenghi (MANAGEMENT) is granted a 10% salary rise. New salary: 40700

000003 Yrsa (SALES) is granted a 10% salary rise. New salary: 74048

000004 Frederik (SALES) is granted a 10% salary rise. New salary: 58080

****** **************************** Bottom of Data *****************************

If the program is executed several times, the first window (listing departments) will remember its selections and make a redisplay of what was entered before. The other windows will not remember their selections because guiding texts have changed due to the already granted salary rises.