REXX for CICS TS: Panel facility

The REXX panel facility provides the REXX programmer with simple tools and commands for panel definition and for panel input/output to 3270 type terminals. The panel facility allows easy definition of panels using any editor. The requirement is that the panel source definition file should be in the REXX File System (RFS) before it is further processed. The panel input/output command provides the ability within a REXX program to change dynamically many of the field attributes statically defined by the panel definition facility.

How you define panels

Defining a panel requires two steps.

Use an editor to create the panel source file in the REXX File System. The panel source should contain field control characters and the panel layout. The panel layout can contain field control characters, regular displayable text characters, and possibly, imbedded variable names.
Convert the panel source into an intermediate form (panel object) that can be used by the panel input/output commands. The panel facility automatically generates the intermediate file when the input/output command that is referencing that panel is first invoked or an explicit command in the REXX environment (or a REXX exec containing the command) can be invoked to generate the intermediate file.
Note: This automatic generation is executed whenever the panel object cannot be found, or when the panel source has a date or time change that is later than the panel object. Any change to the panel source causes a new panel object to be created. Therefore, be cautious when you change a panel source after a program that uses that panel is out of the testing phase. It is to your advantage to move the panel source out of the RFS, or into an RFS directory that the program cannot access, after the project goes into production.

Example of panel definition

The following example demonstrates the capability and function of the panel facility and also helps you understand and visualize the general concepts described in this information. An overview of the example is as follows:

It defines field control characters that set the characteristics of panel fields.
It uses the field control characters to define a panel layout. The control character definition and the panel definition (the two parts together are called panel source) is saved in the REXX File System.
It uses the panel source to generate a panel object that is used to send or receive panels in a REXX program.

  ** SAMPLE PANEL DEFINITION.
 
  define the field control characters to be used in the panel layout.
.DEFINE < blue protect
.DEFINE @ blue skip
.DEFINE ! red protect
.DEFINE > green unprotect underline
.DEFINE # green unprotect numeric right underline

define a panel named applican, which
queries an applicant's name and address.
(this line and the above lines are treated as comments).

.PANEL applican


< Please type the requested information below @

                     !Applicant's name
@Last name ...:>&lname                   @
@First name ..:>&fname                   @
@MI...........:>1&mi

                     !Applicant's mailing address

@Street.......:>&mail_street                               @
@City.........:>&mail_city                    @
@State........:>2&mail_state
@Zip...:#5&mail_zip

.PANEL

**  END OF SAMPLE PANEL DEFINITION.

** START OF REXX PROGRAM USING THE PREVIOUS PANEL.

/* program to query applicant's name and address */
lname = '';  /* null out all name parts */
fname = '';
mi = '';
mail_street = '';
mail_city = 'DALLAS';  /* prefill the most likely response for city/state */
mail_state = 'TX';
mail_zip = '';
do forever;
  'panel send applican cursor(lname)';
  if rc > 0 then
     call error_routine;

  'panel receive applican'; /* pseudo-conversational this would be separate */
  if pan.aid = 'PF3' | pan.aid = 'PF12' then
     leave;
  if pan.aid = 'ENTER' & pan.rea = 124 then
     iterate;
  if pan.aid = 'CLEAR' | substr(pan.aid,1,2) = 'PA' then
    iterate;  /* go to beginning of loop */
  if rc > 0 then
     call error_routine;

  /* process the name and address */

end;
'panel end';
exit

error_routine:
   Say 'An error has occurred'
return;

** END OF REXX PROGRAM and end of sample.

Note: The following characters might display differently in the REXX online help depending on the code page used in your emulator configuration:

@ # $
¢