****************************************************************** * * * Stanford Data Center * * Stanford University * * Stanford, Ca. 94305 * * * * (c)Copyright 1994 by the Board of Trustees of the * * Leland Stanford Junior University * * All rights reserved * * Printed in the United States of America * * * ****************************************************************** SPIRES (TM) and Prism (TM) are trademarks of Stanford University.
Screen Definer simplifies the process of creating "screens" for Prism and SPIRES full-screen applications. A Screen Definer screen is an image to be displayed on a terminal screen. The screen may be used to display data from a SPIRES file or Prism application, or used as a blank form that the user fills out, thus adding or updating records in SPIRES or Prism.
For input, the user fills out the blanks on the screen as he or she would fill out a paper form. The user can use the tab key or other cursor-positioning keys to move about the screen, typing in new data or typing over old data. Some parts of the screen (e.g., instructions or labels) may be "protected" -- that is, the user cannot type in them or change data already in them. The application can then read the user's input data from the "unprotected" parts of the screen, placing them in a data base record for storage or into variables for other uses.
Prism and SPIRES use "formats" to determine what to place on the screen and what to read from it (and what to do with what is read). To create a format, you must create a "format definition", which is basically a set of instructions, using a special formats language, that describes how data is to move from the data base to the user, or vice versa. When you create a format definition, it becomes a record in the SPIRES subfile FORMATS; it becomes a format when it is compiled.
Writing full-screen formats code is tedious and time-consuming. Just as File Definer relieves the application developer from the tedium of coding long file definitions, Screen Definer creates long format definitions based on the specifications you give it. Most of your time is spent designing your screens -- telling Screen Definer about them is a matter of "painting" the screens you want and answering a few questions about them. In many cases, it will take less than 10 minutes for you to use Screen Definer to create format definitions.
You do not need to know how to write format definitions, but you will need to know how to compile them to use the formats Screen Definer creates. [See 4 for the simple steps of compiling a format definition.] In a future version of Screen Definer, even that knowledge may not be necessary in many cases.
You also need to know how to install the screens into a Prism application or how to connect the compiled format into a SPIRES full-screen application, depending on which program your application is based in. [See 5.] Of course, if you want or need to customize the generated format definitions, you need to be familiar with the formats language. It is likely that some users may need features that are not yet available in Screen Definer -- and if you truly need them, you will have to add them to the formats code yourself. [See 6 for a list of current limitations and planned enhancements of Screen Definer.]
Although it can be used for both SPIRES and Prism applications, Screen Definer is itself a Prism application. In other words, you use Screen Definer within the Prism environment. If you are not familiar with Prism, you should get a copy of "Introduction to Prism", a 10-page document that describes how to use Prism, explaining its most common features and commands. In addition, Prism is a self-documenting system -- online instructions and other helpful information are provided to guide you smoothly through Screen Definer. Be sure to ask Prism for help when you need it, by issuing the HELP command.
When you develop screens for an application, you will follow four main steps:
- 1) Design the screens
- 2) Use Screen Definer to generate format definitions
- 3) Compile the format definitions
- 4) Connect the formats to the Prism or SPIRES application
This document will take you through the steps of this procedure.
The first chapter is a primer to Screen Definer, a brief summary of the most vital information about it. It is very likely that you will be able to use Screen Definer on your own after you read those few pages.
The rest of the document is the Screen Definer reference manual, where each of the steps listed above is covered in detail. If the primer moves too quickly for you or if you have questions about a particular subject, you will find that the reference manual goes more slowly, providing much more information.
Screen Definer, a Prism application, is a product of the Data Resources Group of the Stanford Data Center at Stanford University. It was designed and programmed by Bruce Strong. This document was prepared by John Klemm. Other members of the Screen Definer design team are John Sack, Sandy Laws, Lynn McRae and Jeff Rensch.
This chapter presents a summary of how to use Screen Definer. It can be considered a primer to Screen Definer, while the rest of the document serves as the reference manual. The same material presented in this chapter appears in more detail in the reference chapters, so if you have trouble understanding something here or if you need more information about a topic, you should consult the reference chapters.
You can use Screen Definer to create screens for full-screen applications in both Prism and SPIRES. You must be able to select the SPIRES subfile or the Prism application for which the screen is being defined. Also, to install the screen in a Prism application, you must be able to change the Prism Profile record for the application.
Screen Definer users typically create several types of screens:
- Data Entry screens
- Parameter or Menu screens
- Output-only screens
These screens usually work for both input and output. The screen is presented to the user (output), who then makes changes to it and returns it to the program (input). The changes the user makes (usually filling in blanks) involve data to be put into a Prism or SPIRES file. The purpose of the screen may be to create new records or it may be to modify existing ones, in which case the existing record's data would appear as output for the user to change as desired.
These screens also work for both input and output, but do not handle element values from records in the file. They might, for example, present the user with a choice of actions (output); when the user marks a choice, the screen is returned to the program (input), which then processes the user's choice as appropriate.
These screens usually present information, such as instructions. They are protected, so the user cannot make changes to them. Although they can be used to display records (in which case they are called "Display screens", referring to the DISPLAY command in Prism), Screen Definer's capabilities for creating Display screens are very limited. Future enhancements to Screen Definer will produce better support for Display screens, at which time this document will be updated to discuss them.
Screens designed and defined in Screen Definer are currently limited in size to a width of 79 columns and a height of 22 rows. The maximum height may be reduced to 17 rows, which is the maximum number of rows for an entry screen in Prism's Guided mode that can be used by standard 24-row terminals.
When you design a screen, you place "fields" on it. A field may be a piece of text, an element or variable value, a place to mark data entry errors, etc. Everything you place on the blank screen is, or is part of, a field.
A field may be any length from 1 to 79 characters in size; a field is only one row high. One value might require several fields to hold it. For example, a long value might start in one field and wrap around into another field on the next row. There are several types of fields allowed:
- Element fields, representing element values from or for the data base. These fields may be
declared protected or unprotected ("protected" means the user may not type in the
field; "unprotected" means the user may), and if unprotected, they may be
declared required or optional.
- Variable fields, representing values of SPIRES system and user-defined variables you will use in your application. They may be declared protected or unprotected, required or optional.
- Text fields, always protected, which contain text to be displayed on the screen (e.g., instructions).
- Error fields, always protected, which display error messages or codes set by the application. They are almost always associated with unprotected element and variable fields. They must precede (on the left) the field they are associated with.
- Title fields, always protected, which are used to "label" an element or variable field. Though similar to text fields, they may have different display attributes than text fields to make them stand out from the other text. Words within the title may be separated by a single blank.
Each field must be preceded by a blank character position, except for fields beginning in column 1. You cannot have two fields horizontally adjacent to each other. (But see the note below under Screen Painting.)
The screen on which fields are placed consists of one or more "frames". Each Screen Definer screen has a "base frame", with up to 22 rows high by 79 columns across, the maximum size of a defined screen depending upon terminal size. On many screens you will place all your fields in the base frame.
However, if you have elements in structures (or other groups of closely related fields) which you might want to repeat several times on the screen as a group, one below the other, you will place those fields in a "subordinate frame". A subordinate frame is placed inside either the base frame or another subordinate frame, which in turn is placed inside the base frame or another subordinate frame, etc.
Subordinate frames may be nested 6 levels deep -- the nesting is usually done to match the depth within the record of the structure the frame is handling.
Fields that are not within any subordinate frames are called "base-frame fields".
When you define a screen in Screen Definer, you are asked to "paint" on a blank screen the fields you want to appear. First you paint any fields in the base frame; later you paint fields in any subordinate frames you want.
To paint, you use various special symbols to represent each character position of the field on the screen. A chart of the symbols appears below: [The chart also appears several other places in this manual, as well as in the online help for Screen Definer. Type HELP SYMBOLS USED IN SCREEN PAINTING, or type HELP on the screen-painting pages of the ADD SCREEN and MOD SCREEN entry forms.] Notice that some types of fields may begin with one character and continue with another.
Screen Painting Characters
**** - protected element
____ - unprotected, required element
.... - unprotected, optional element
#** or $ - protected variable
#__ or @ - unprotected, required variable
#.. or # - unprotected, optional variable
=** or = - subsequent occurrence of a protected element or variable
=__ or = - subsequent occurrence of a required element or variable
=.. or = or ~ - subsequent occurrence of an optional element or variable
++++ - continuation on a subsequent row of a field that wraps
!!!! - error code
%text - title
text - text to appear on the screen
{text} - forced text; the text within the brackets is handled as
text, even though it may contain screen-painting symbols
& < > \ - (for future extension of Screen Definer)
Note: the symbols "%", "{" and "}" characters for titles and forced text are stripped off; thus, the character position they hold on the painted screen can be considered the required blank before a field.
Below is a sample screen design for an input screen for the BLOOD DONORS subfile in SPIRES. It could be used to collect data about new donors or to update information about previous donors. General information about the donor is entered in the top half of the screen, and information about specific donations is entered in the bottom half. [The BLOOD DONORS subfile is described in detail in the SPIRES primer, "A Guide to Data Base Development".]
%Donor Number: **** %Total Pints Donated: ***
!!%Name: ____________________
!!%Address: ______________________________
=.............................
!!%City: _______________ !!%State: __ !!%Zipcode: .....
!!%Phone Number: ......................... !!%Can he/she be called? ...
!!%Blood Type: ___
%Comments: ...............................................................
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
{* * * * * * * * * * Donation Information * * * * * * * * * *}
%Date(s) %Location(s)
!! ...................... !! ...............................................
!! ...................... !! ...............................................
!! ...................... !! ...............................................
!! ...................... !! ...............................................
!! ...................... !! ...............................................
Using the preceding chart, you can determine what each field on the sample screen represents. For example, the first field is a title field (identified by the % sign) for the ID element. The next field "****" is a four-character field representing a protected element value. In this case, it is ID, the slot key number of the record.
In BLOOD DONORS, each donation is one occurrence of the DONATION structure in the donor's record. In the sample screen design, the DONATION structure is handled by a subordinate frame, one row high, that is placed on the base frame five times. The text and titles that identify it are not placed in the subordinate frame; they are placed in the base frame so that they are not repeated over and over on the screen, as the frame is. Note that the text is placed in braces because it contains asterisks, which are special screen-painting symbols.
Here's how the screen might look to a user who wants to add a new donor record:
Donor Number: Total Pints Donated:
Name: ____________________
Address: ______________________________
______________________________
City: _______________ State: __ Zipcode: _____
Phone Number: _________________________ Can he/she be called? ___
Blood Type: ___
Comments: _______________________________________________________________
_______________________________________________________________
* * * * * * * * * * Donation Information * * * * * * * * * *
Date(s) Location(s)
______________________ _______________________________________________
______________________ _______________________________________________
______________________ _______________________________________________
______________________ _______________________________________________
______________________ _______________________________________________
Notice that the error fields have been hidden, and the symbols denoting the text and title fields have been stripped off. Fields expecting user input are underlined; note that the protected element fields for "Donor Number" and "Total Pints Donated" do not appear. If the screen were being used to update pre-existing records, the appropriate element values would appear in those fields.
What you can't see in this printed simulation is that on most terminals, there is a difference between optional and required fields. The optional fields (both the underscore and the data the user types) are displayed in green on color terminals or at normal intensity. On the other hand, the required fields are displayed in yellow on color terminals, or at brighter-than-normal intensity.
If a terminal cannot handle a particular display attribute, the attribute is ignored; no error occurs. So even if you are sure that your screen will never be used on a color terminal, each field will have a color attribute, which will be ignored by non-color terminals.
Screen Definer is an application in Prism. To use it:
- 1) Issue the SET TERMINAL command to tell the system what type of terminal you are using. (Type HELP TERMINALS if you do not know how to use the SET TERMINAL command.)
- 2) Issue the command PRISM. You may choose either Guided or Command mode, depending on your familiarity with Prism.
- 3) Select SCREEN DEFINER from the list of applications.
In addition, issue the HELP command in Prism whenever you need assistance. Help is available for every screen you will see in Screen Definer.
In Screen Definer, you work with a Screen Definer record, which is primarily a collection of screen definitions. You cannot define any screens until you have created a Screen Definer record to hold them.
To create a Screen Definer record, follow these instructions, which match those shown on the terminal screen:
- 1) Type the command ENTRY.
- 2) Choose CREATE from the list of entry forms shown.
- 3) Type the command CREATE.
The Screen Definer record is similar to a SPIRES format definition -- in fact, it will be used to generate format definitions later. Like a format definition, it must have a name (the Screen Definer record key) that is unique for your account.
All screens in the record are defined for a single subfile, which you name when you create the Screen Definer record. You must be able to select the subfile in SPIRES or select the application in Prism in which the subfile is used.
You also choose default display attributes for the various types of fields -- that is, whether error fields should be blinking and red, etc. Usually, all fields of a given type will share the same characteristics, specified here. (When defining screens, you will be able to change the characteristics of individual element and variable fields to differ from these defaults.)
- 4) Fill in the appropriate blanks in the two pages of the CREATE entry form, following the directions given on the screen. Type HELP if you need more information.
- 5) Type SEND to file the Screen Definer record.
You define screens one at a time using the ADD SCREEN entry form:
- 1) If you are not already in the Screen Definer application in Prism, follow the first set of instructions above.
- 2) Type the command ENTRY.
- 3) Choose the ADD SCREEN entry form.
- 4) Type the command FIND.
- 5) Using the indexes shown, find the Screen Definer record you created. The simplest method, if you remember the record key, is to issue the command:
FIND RECORD <gg.uuu.record.key>
- 6) Type the command GET. If there are several records in your search result, follow GET with the number of the record you want. The GET command starts your work with the ADD SCREEN entry form.
On the first page of the ADD SCREEN entry form, labeled "General Information" at the top, you answer some general questions about the screen you are defining. For example, you will give the screen a name unique to the Screen Definer record.
You will also be asked whether you have any base-frame fields to paint on the screen. If you do not, answer NO and Screen Definer will take you ahead to the page of the form for creating subordinate frames (see below).
You also declare here whether the screen will be used for output only. [See 1.1.]
Assuming you do have base-frame fields to paint, you "paint" them (that is, you type the appropriate symbols for each desired field) on the next page of the form, which is basically just a blank screen. Paint only base-frame fields; do not paint any fields that are in subordinate frames yet.
Here, for example, are the base-frame fields you would paint for the sample screen for BLOOD DONORS, using the design and screen-painting symbols discussed in this primer a few pages ago:
+-------------------------------------------------------------------------------+
| %Donor Number: **** %Total Pints Donated: *** |
| !!%Name: ____________________ |
| !!%Address: ______________________________ |
| =............................. |
| !!%City: _______________ !!%State: __ !!%Zipcode: _____ |
| %Phone Number: ......................... !!%Can he/she be called? ... |
| !!%Blood Type: ___ |
| |
| %Comments: ............................................................... |
| +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| {* * * * * * * * * * Donation Information * * * * * * * * * *} |
| %Date(s) %Location(s) |
+-------------------------------------------------------------------------------+
Later in this entry form, you will paint the fields of the subordinate frame that handles the DONATION structure.
When you are finished painting, type OK to continue to the Review page, where Screen Definer reports any painting errors you made on the painting page, if any. If so, you should type PREVIOUS to return to the painting page to correct your errors.
For the Review display, the "{", "}" and "%" characters are stripped off text, and fields are shown with the appropriate color attributes. If you painted any fields with multiple "$", "@", "#", "=" or "~" symbols, those fields will be "normalized" to the other standard display for that type of field. (For instance, the painted field "###" would be normalized to "#..", both of which mean "a three-character optional variable field".)
Later, when you have added subordinate frames, this page will also duplicate each frame on the screen the requested number of times.
If you like what you see, type OK to continue; otherwise, type PREVIOUS to return to the painting screen to make changes.
If you painted any element or variable fields on your screen, the next page or pages ask you to name the element or variable associated with each field.
At the same time that you name each element and variable, you can mark (with an X) that you want to review or make changes to the attributes for that element or variable field, including changes to the type of variable.
If you mark that you want to review or change any attributes for any elements or variables, the next few pages, called "Element Review" or "Variable Review", will give you that opportunity.
For elements, you can change display attributes, value adjustment within the field, the edit mask (if any), and the element's occurrence number. For variables, these pages in effect define them -- you can change display attributes, variable type (e.g., string or integer), and value adjustment within the field.
The next page asks you to issue the SEND command if you are finished defining the screen, or to continue the definition process by adding, modifying or removing a frame.
If you decide to add a subordinate frame, then on the next page Screen Definer will ask you some general questions about the frame (again, you need to supply a unique name for the frame). Then you will return to the painting page to paint the frame on top of the screen as it is defined so far. Here is what you would paint on the BLOOD DONORS screen to handle the DONATIONS structure, painting it where you want the first occurrence of the subordinate frame to appear:
+-------------------------------------------------------------------------------+ | !! ...................... !! ...............................................| +-------------------------------------------------------------------------------+
When you are done, the Review page is shown again, duplicating the frame on the screen, once for each occurrence specified on the Subordinate Frame Information page. Then Screen Definer asks you to name the elements and/or variables you defined in the frame. Then you return to the Frames page that asks you to SEND the record or add, modify or remove another frame. The cycle continues until you finally SEND the record to complete the screen definition.
To add another screen, just GET the record again, continuing from step 6 above.
If you want to make changes to a screen you have already defined, you need to use the MOD SCREEN entry form. Basically, you follow the same procedure as you did with the ADD SCREEN form, but instead of choosing ADD SCREEN you choose MOD SCREEN when selecting an entry form (see above).
After you type the GET command to begin using the MOD SCREEN form, Screen Definer will show you a list of the screens in the Screen Definer record, asking you to choose the one you want to modify. (If the record has only one screen, this step will be skipped.)
In the MOD SCREEN form, Screen Definer takes you through almost the same pages you went through with ADD SCREEN. You can change most of the ingredients of a screen -- you can completely repaint it if you want.
When you have finished defining screens for your format, it is time to generate format definitions. The procedure to follow is:
- 1) If you are not already in the Screen Definer application in Prism, follow the instructions under "Invoking Screen Definer in Prism" above.
- 2) Type the command ENTRY.
- 3) Choose the GENERATE entry form.
- 4) If you still have a search result containing the Screen Definer record you want to use, skip to step 6; otherwise, type the command FIND.
- 5) Using the indexes shown, find the Screen Definer record you created. The simplest method, if you remember the record key, is to issue the command:
FIND RECORD <gg.uuu.record.key>
- 6) Type the command GET. If there are several records in your search result, follow GET with the number of the record you want. Now the GET command starts up the GENERATE entry form.
The GENERATE form asks you to approve or change the format definition ID it derives from your Screen Definer record key (you might want to write it down -- you'll need it later).
If the Screen Definer record contains many screens, or if you have placed "subfile phantom elements" on any screens, then Screen Definer will create several format definitions, and will ask you to approve or change the format definition IDs for them too. (The additional format definitions contain "load formats", which are called by the main format as it needs them.) Also, if you defined any user variables, Screen Definer will ask you to approve or change the ID it will assign to the vgroup definition that it creates for the variable definitions.
Screen Definer also asks you to approve or change a format name.
Then Screen Definer generates the format and vgroup definitions and adds them to the FORMATS and VGROUP subfiles in SPIRES.
Before you can use your format in a Prism or SPIRES application, you must compile the format definition(s) (and vgroup definition, if any):
- 1) If you are still in Prism, issue the END command to leave.
- 2) Issue the command SPIRES.
- 3) Skip to step 4, unless Screen Definer created a vgroup definition for you. If it did, issue the following commands, where "gg.uuu.vgroup.id" is the name of the vgroup definition you wrote down when you generated the format definitions:
SELECT VGROUPS COMPILE gg.uuu.vgroup.id
- 4) Issue the command SELECT FORMATS. Then issue the following command for each format definition Screen Definer created, using the format IDs you wrote down when you generated the format definition:
COMPILE gg.uuu.format.id
The formats are now compiled.
How you use the format from this point depends on your application. A later chapter of this manual will describe how to tie your format into Prism and SPIRES applications. [See 5.]
Each screen (base frame) of the Screen Definition record translates into two data frames of the format definition, one for input, the other for output. [Only one data frame, for output, will be created for output-only screens.] Any subordinate frames you painted on the screen become indirect frames in the format definition. All of the data frames have a Usage value of NAMED, meaning that a data frame will be executed only if a command (such as DISPLAY) names it specifically with the USING prefix, as in USING FRAME1 DISPLAY.
This chapter may have given you enough information about Screen Definer to satisfy your needs. Some Screen Definer users will need to know more, at least in some areas. The reference manual that follows presents Screen Definer in much more detail. The table of contents and index can guide you to specific areas of interest.
Chapter 2 discusses how to design screens, concentrating on general concepts of Screen Definer, the components of a screen, and screen painting.
Chapter 3 covers the Screen Definer procedure, taking you page by page through each form:
3.1 CREATE create a Screen Definer record 3.2 MOD GENERAL modify general Screen Definer record information 3.3 ADD SCREEN add a screen to a Screen Definer record 3.4 MOD SCREEN modify/remove a screen in a Screen Definer record 3.5 GENERATE generate a format from a Screen Definer record 3.6 REM RECORD remove a Screen Definer record
Chapter 4 describes the procedure to follow to compile a format definition.
Chapter 5 briefly discusses how to tie the compiled format definition to a Prism or SPIRES application, primarily leading you to other documentation that covers that information in detail.
Chapter 6, last but certainly very important, lists some of the current limitations of and future enhancements planned for Screen Definer. If you are wondering whether a particular part of a screen design you have created can be done with Screen Definer, you might consult that section now.
If you have any problems using Screen Definer, please use the SUGGEST command in Prism to let us know about them, or see your SPIRES consultant.
Like an artist facing a blank canvas, you may find yourself overwhelmed by the possibilities for filling the terminal screen. Of course, few artists would confront a blank canvas without at least a basic design in mind, if not in a sketchbook. Similarly, you will find your Screen Definer work more productive if you spend a few minutes planning your screens, perhaps sketching them out on a pad, before you use Screen Definer.
This chapter will describe some of the general concepts of Screen Definer, introducing you to its capabilities and vocabulary. It will tell you what types of fields you can place on a screen, how fields can be grouped together into multiply-occurring "frames" on a screen, and how you describe your screen design to Screen Definer by "painting" the screen.
There are several different types of screens you might want to create with Screen Definer. For example, you might want to create data entry screens for Prism, where a "blank entry form" is displayed to the user, who then fills in the blanks. On the other hand, you might want to create some screens that display some text or present menus of choices for the user to make.
This section will show you some sample screens of various types, to give you ideas about how Screen Definer may be used. It is likely that some screens will require extra code (in protocols or within the generated format definitions themselves) to make them useful. However, Screen Definer will do most of the tedious work of creating the format definition.
In all cases, the screens shown would be part of full-screen formats. Although you could use Screen Definer to create formats that would be used in non-full-screen applications, that is not its purpose, and such uses will not be discussed here.
Screen Definer can be used to create input and output screens for data entry:
+-------------------------------------------------------------------------------+ | Pals of Stanford - Member Information | | | | Name: ___________________________ Phone: _________________ Sex: _ | | | | Address: _______________________________________________________________ | | _______________________________________________________________ | | | | City: ______________________________ State: __ Zipcode: _________ | | | | (etc.) | +-------------------------------------------------------------------------------+
In its output form, this screen would appear on the user's terminal, who then could begin filling in the blanks ("unprotected fields"). The screen can indicate where input is required (yellow or bright-intensity underscored fields) and where it is optional (green or normal-intensity underscored fields). Explanatory text can be placed on the screen, such as the heading at the top, or the labels ("titles") placed in front of each unprotected field.
Once the user has completed the screen, the screen can be "read" as input by Prism or SPIRES, which means that the program takes the data the user has typed and places it in a record as element values or into variables, as determined by the screen definition. If the data causes errors of some type (e.g., no value is given for the required STATE element), the screen can be redisplayed (output) with the user's input still on it, with additional error codes or messages displayed on the screen. Then the user would correct the error and the program would read the screen again.
Another type of screen that is easy to create is a "Menu screen":
+-------------------------------------------------------------------------------+ | | | Mark the task you want to do next with an X: | | | | _ Add information on another donation to this record | | _ Modify information on a donation already in this record | | _ Remove a donation already in this record | | | +-------------------------------------------------------------------------------+
On this type of screen, you are not dealing with element values; usually you are manipulating variables. For instance, the three optional fields in the screen above (the underscores) represent variable values. As output, the screen would be displayed to the user, who would mark one of the fields, and send the screen back as input. You would have added code to the generated format definition to determine which variable value has been changed to "X" or determine if the user has made some mistake, in which case an error message might be displayed and the user reprompted.
A menu screen generally offers choices; you might make other kinds of screens ("parameter screens") that ask the user for values, such as the name of a report, for a Prism application. Thus, screens you create with Screen Definer do not have to be used to move data in and out of the data base. Using text and variables, you can create input/output screens that have nothing to do with data base transactions.
You can also create screens used solely for output purposes. The screen is protected so that the user cannot change any data; moreover, the screen would not be read back by Prism or SPIRES. An output-only screen might contain only text, such as directions suggesting what to do next, or it might contain text and variables, as in this confirmation screen:
+-------------------------------------------------------------------------------+ | | | You have successfully added the following record to BLOOD DONORS: $$$$ | | | | To review this record, type REVIEW. | | To create another record, type CREATE. | | | +-------------------------------------------------------------------------------+
This screen, which we might install in Prism when we put our BLOOD DONORS file there, could be used to end the transaction of creating a new record. It would reassure the user that the transaction had completed successfully, and provide some suggestions for what to do next. (For example, every entry form in Screen Definer ends with a confirmation screen.)
Notice that the screen has the symbols "$$$$", indicating a system variable field. When defining the screen, we could place the value of the system variable $KEY in that field, meaning that the key of the record just added would appear there when the screen is presented to the user.
A special type of Output-only screen, not yet supported, is the Display screen, used to display records. For example, the BRIEF and FULL displays in Prism applications are Display screens. Though it may be possible to use Screen Definer to create some Display screens, several important design techniques for them are not yet supported by Screen Definer. In particular, header frames for multiple record displays, and ways to handle irregularly-occurring elements are features that will be added to a future version of Screen Definer. [See 6.]
Now that you know some of the possibilities for screen design, you should learn some of the specific concepts and capabilities of Screen Definer.
When you use Screen Definer, you work with a "Screen Definer record", which contains one or more screen definitions.
You will begin in Screen Definer by creating a Screen Definer record. Then, to define a screen, you will GET that record (GET is a Prism command) using the ADD SCREEN entry form, define a screen, and then SEND the record to Screen Definer. You follow that procedure for each screen you want to add. Then, when you are through defining screens, you generate a format definition from the record, and all the screens become part of that format definition.
Each Screen Definer record is associated with a SPIRES subfile, i.e., a particular goal record-type of a particular SPIRES file. For Prism applications the subfile name is "PRISM file-id" where "file-id" is the 1-to-8-character file identifier. (Even if you are creating screens that are not related to any data base, the Screen Definer record must be associated with one.)
When you are ready to generate formats code, a Screen Definer record, with all its screens, translates into:
- a primary format definition;
- possibly one or more load-format definitions (if any screens contain phantom elements, or if there are more screens than Screen Definer can easily place in one format definition);
- a vgroup definition, if you created any user variables.
Each screen definition becomes a data frame (usage NAMED) in the format, which a Prism application can invoke for execution as a "processing step" in an entry form.
In SPIRES, an application developer usually thinks of a format for adding a record or displaying a record as consisting of a single data frame. But in full-screen applications, a single screen often cannot hold all the data in a record, so multiple screens are usually necessary. So several screens may be needed to handle the input of a record in full-screen applications, and the application will control which screens are presented when. Prism handles the input through processing steps; in SPIRES, you generally control it in protocols. [See 5.]
Whether you place each screen you define into a separate Screen Definer record or you put all screens you will ever use with a particular subfile into one record (or something in between) is in many cases up to you. Here are some rules and guidelines that may help you decide:
- 1) It is more efficient for SPIRES to look for another frame in the same format than to set a different format. Hence, in terms of efficiency, it is better for an application to have as many of its frames as possible in one format.
- 2) It is more efficient to keep all screens for a single transaction in a single Screen Definer record. For example, if you are creating a set of three screens used one after the other to add a record to a subfile, you should keep them in a single Screen Definer record. [On the other hand, if some of the screens used in a transaction are for one subfile while others are for a second subfile, you will need at least two Screen Definer records, one for the screens of each subfile.]
- 3) You should usually put screens that share the same variables in the same Screen Definer record.
- 4) You should usually place sets of screens that share common screens into the same record. [You can, however, use the "Copy from" feature described later to have the same screen be in several different Screen Definer records.]
A very important consideration right at the start is the type of terminal that the user of your screens has. The terminal the screens are being designed for must be a full-screen terminal. At Stanford, the best recommendation is that it be a terminal model supported by WYLBUR and MILTEN. (Type the WYLBUR command HELP TERMINALS for a list.) If the terminal can be used for Prism and Page WYLBUR, then screens created with Screen Definer can be used on it.
Similarly, the terminal you are using to develop your screens must be a supported terminal, since you must be able to use Prism. Ideally, you will probably want to use Screen Definer on the same type of terminal, or even the same terminal, that your users will have when they use your screens. That way, you will know the limitations of the users' terminals -- for example, that it doesn't support color, or reverse video -- so that you don't develop screens that depend on characteristics the terminal doesn't have. [Some terminals have odd quirks: for instance, the IBM Color PC does not support underlining; fields with the Underline attribute appear in reverse video instead.]
Attributes that have no effect on a given terminal are ignored for that terminal. It does not matter, for instance, if a Blue field is displayed on a non-color terminal; the Color attribute is ignored, and the field is displayed using the terminal's standard display "color". No display error occurs.
Screen sizes vary from terminal to terminal, and the amount of the terminal screen available to you may vary as well.
However, in the present version of Screen Definer, the maximum number of rows allowed per screen is 22.
¿þþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþÜ | | | | | | | 22 rows high | | | | | | | | | | |<------79 columns wide---------------->| | | | | | | | | | ¾þþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþ»
Screens may have many different purposes, but they have only a few components. The basic unit of screen design is a "field", a group of horizontally contiguous character positions on the screen, all sharing the same "field attributes" (see below).
In other words, all the characters of a field will be in the same row, adjoining each other. Many fields may appear on a single row, but they must be separated from each other by a blank space on the screen. If the field has the color attribute "blue", then all the characters in the field will be blue (on color terminals). Similarly, if the blinking attribute is set for the field, then all the characters in the field will blink on and off. [See 2.6 for a complete discussion of field attributes.]
The rest of the screen can be considered blank, i.e., it has no attributes.
There are several different types of fields; text fields, for instance, contain only textual information, such as instructions. A text field always displays the same text each time the screen is used. Element fields, on the other hand, contain element values from the record currently being updated. Alternatively, they may be blank, waiting for the patron to type values in for a new record.
Just as file owners often choose to group related elements together into structures (usually so that they can repeat as a group), you can group fields together into a "subordinate frame", which can repeat multiple times vertically down the screen. Subordinate frames are most often created to handle element fields in structures.
Subordinate frames are placed in the base frame, up to 22 rows high by 79 columns across, the maximum size of a defined screen. Each screen has one base frame. If you have a screen that handles no structural elements, you will probably define all the fields for that screen in the base frame of the screen. Those are sometimes called "base-frame fields".
Fields for elements in structures are defined in subordinate frames, which are in turn placed in the base frame (or in another subordinate frame).
For example, suppose you are creating the input screen shown in the first chapter for the BLOOD DONORS subfile. [See 1.3.] To handle the DONATION structure (each occurrence of which has the date and location of a donation), you could define a one-row subordinate frame:
!! ...................... !! ...................................
and specify that it should appear five times:
______________________ ___________________________________
______________________ ___________________________________
______________________ ___________________________________
______________________ ___________________________________
______________________ ___________________________________
When the patron uses the screen for input, each row in which data is entered becomes an occurrence of the DONATION structure -- the date and location of a particular donation are thus kept together.
In a subordinate frame that handles a structure, don't place any fields for elements that are not in that structure. For example, in the BLOOD DONORS screen, we wouldn't put the record-level NAME element in the DONATION frame, even if the DONATION frame occurred only once on the screen -- doing so can cause chaos during record processing. (SPIRES/Prism can lose its place in the structure if it has to leave the structure to handle another element. See "SPIRES Formats", section B.8.2, for more information.)
Like the base frame, subordinate frames are always 79 columns wide, but they may be from 1 to 22 rows high. Subordinate frames may themselves contain subordinate frames, which in turn may contain more frames, etc., to six levels deep. The depth of a frame will usually match the depth in the record of the structure being handled by that frame.
If you request multiple occurrences of a subordinate frame on a screen, each subsequent occurrence will begin on the row after the previous occurrence ends. In other words, you can't put multiple occurrences of a subordinate frame next to each other.
A subordinate frame doesn't have to occur multiple times on a screen. In fact, there are times when you may have a subordinate frame that occurs only once and is the size of the entire screen. How, and why, would that be true?
Remember that unless your goal record is quite small, you are likely to need more than one screen for a record. Suppose you have the following goal-record structure:
STUDENT.ID
NAME
ADDRESS
YEAR.STRUC
YEAR
QUARTER.STRUC
QUARTER
FINANCIAL.AID
The first screen might be used to gather the student's name and other pertinent record-level information.
+-------------------------------------------------------------------------------+ |Screen #1 - General Student Information | | | | Name: ___________________________ | | | | Address: _______________________________________________________________ | | _______________________________________________________________ | | (etc.) | +-------------------------------------------------------------------------------+
You might need a second screen to handle, for example, all occurrences of QUARTER.STRUC that are within the first occurrence of YEAR.STRUC (say, 1984):
+-------------------------------------------------------------------------------+ |Screen #2 - Financial Aid information | | Name: Year: __________ | | Autumn Aid programs: 1 ________________________________________ | | 2 ________________________________________ | | 3 ________________________________________ | | Winter Aid programs: 1 ________________________________________ | | 2 ________________________________________ | | 3 ________________________________________ | | Spring Aid programs: 1 ________________________________________ | | (etc.) | +-------------------------------------------------------------------------------+
Screen #2 is defined as a base frame, with nothing painted on it. The base frame holds a 22-row subordinate frame for YEAR.STRUC, which has the "<season> Aid programs" titles painted on it. The YEAR.STRUC frame in turn has four occurrences of the subordinate frame that handles QUARTER.STRUC, one for each season. Each of those occurrences handles three occurrences of the FINANCIAL.AID element. So, in this case, the YEAR.STRUC frame can have only one occurrence on the screen.
Prism could call this screen over and over again, till the user was through adding occurrences of YEAR.STRUC, when he or she would issue the SEND command to complete the record's processing.
The Name field would probably be handled by a protected variable too. The student's name would be put into the variable during processing of the first page. (these instructions would have to be added to the generated format definition by hand).
This type of nested-frame scenario can go deeper and deeper, in terms of structures and subordinate frames, such that a screen may contain several frames on top of each other, each the size of the entire screen. Even so, the screen will still have a base frame (even if no fields are defined in it) and each containing structure must be represented by a frame. For example, if you used an entire screen to handle one occurrence of the QUARTER.STRUC structure, you would still have to define a subordinate frame (for YEAR.STRUC) to contain it, even if you didn't place any YEAR.STRUC fields in it.
If you paint variable fields in a subordinate frame, each appearance of the variable on the page will be defined as a separate occurrence. For instance, if you paint a variable field in a frame that repeats once on the screen, the two appearances of the variable will be two different occurrences.
However, if you paint the same variable once on each of several different screens, the variable will have only one occurrence, which will be used on each screen. For example, if we painted a third screen that was an exact duplicate of "Screen #2" above, the variable field used to hold the name would have the same occurrence of the variable on both screens.
Frames may be used for other reasons besides structure-handling. You might want to repeat a group of text and/or variable fields several times on the screen, for instance. In such cases, you do not name a structure when defining the subordinate frame using the ADD SCREEN or MOD SCREEN forms. [See 3.3.9.]
There are basically five types of fields you can paint on a Screen Definer screen:
- Element fields
- Variable fields
- Text fields
- Title fields
- Error fields
Element fields hold element values from or for a record in the data base. Singly occurring and multiply occurring elements can be represented by fields on a screen. There is practically no limit to the number of elements that you can place on a screen. (There is a limit of 40 different elements per frame, however.) Virtual elements may be specified; dynamic elements may not. [See 6.] Phantom elements may be specified for output, though they must be handled by their own subordinate frame since they are retrieved via a structure.
Element fields may be defined as "protected", meaning that the user cannot change the value in the field, or "unprotected", meaning that he or she can change the value. (Of course, if you want the user to type a value in the field, you define it as "unprotected".) Making only some of the screen unprotected limits the area where the user can type and where the format has to look for the user's input.
Unprotected element fields may also be defined as "required" or "optional" -- if required, then the user must enter a value in the field; if optional, then the user does not have to.
It may seem incongruous to define an element field as protected on an input screen, but that technique is often used when you are designing a screen for record modification. For instance, you may want to display the record's key but not allow it to be changed.
Variable fields hold values for either user variables or system variables. System variable fields are always protected; the user cannot change the value of a system variable field. A typical use of a system variable is the appearance of $RECNO in the BRIEF display for a Prism application. ($RECNO is the number of the record in the current display of records, counting from 1.)
User variable fields, like element fields, may be protected or unprotected. If unprotected, they may be required or optional. An unprotected user variable might be used for a user's response to some question, which would determine what screen to go to next.
If you paint a user variable on a screen, Screen Definer will generate a variable definition in the Vgroups section of the format definition. The variable can be defined as a string, integer, packed-decimal, flag, floating-point or hex variable. In fact, it can be any kind of SPIRES variable except dynamic.
An array for a variable will be created if multiple occurrences of the variable are painted, or if the variable appears in a frame that repeats on the screen.
[In the current implementation of Screen Definer, user variables are not very useful, except insofar as they cause Screen Definer to generate some basic code for them: a record defining them in the VGROUPS subfile and input/output label groups for them in the format definition(s). In most cases, you will need to alter the format definition or write substantial new code to use them in the format. You may use them outside of the format, e.g., in a protocol, but naturally you will have to write your own code. In a future implementation, you may be able to set default values for them, to use them in the format, etc., without having to change the generated format definition yourself.]
Text fields are generally used to display text that should always appear on the screen, e.g., instructions, a general title for the screen, a line across the middle, etc. Text fields are always protected -- the user cannot type on them.
Be careful to place the screen-painting symbols "{" and "}" around text containing other painting symbols, so that Screen Definer does not misinterpret them. [There is currently no way to include the "{" and "}" symbols as part of a text field without manually changing the generated format definition.]
A title field is a text field meant to be associated with a particular element or variable field, serving as a label:
Name: ____________________
"Name:" is a title for the field that follows it.
What distinguishes titles from text fields to the user is that title fields usually have different display attributes from text fields, so that they will help draw the user's eye to fields for data entry. [To you, the applications developer, title fields may also be different from text fields in the code they generate. If possible, Screen Definer will place the code in the label group for the element or variable associated with the title, in TITLE and TSTART statements. If that isn't possible, the title will get its own label group.]
Title fields are usually placed immediately to the left of the associated field or just above it.
Title fields are identified in screen painting by the percent sign (%) that precedes them. [See 2.7.] The percent sign does not appear when the screen is actually used by the user; it only appears during screen painting in Screen Definer. Because the percent sign is required, you cannot get a title field to begin in column 1; it can appear starting in column 2 because the percent sign must precede it, being placed in column 1. If you must begin a "title" in column 1, you will have to use a text field instead (see below), or make changes to the generated format definition yourself.
Title fields, always protected, may contain single blanks, but not multiple ones:
%This phrase is a title field %This phrase is not a title field.
The second example would be treated as one title field ("This") and 6 text fields.
Error fields are used to flag input errors to the user. They are always protected. If the screen is used for output only, error fields have no effect.
An error flag is always associated with an element or variable field. Specifically, it is associated with the first element or variable field to its right. Title or text fields may come between the error field and its the error field's object field, but they must both appear on the same row.
It is recommended that you paint an error field for each required field. Screen Definer will automatically generate an error message (RQ) for required fields that the user leaves blank.
If a processing rule error occurs when Prism or SPIRES is reading the data input from a screen, the current value of the system variable $UCODE (or as much as will fit in the allowed space) will be placed in the error field. The screen can then be redisplayed using a reprompt mechanism so that the user can correct the error.
Usually the error field is two characters long (a Prism standard, and a SPIRES convention for full-screen formats), so the value of $UCODE is generally set to be a two-character code. In Prism, each code plus an explanation of it should be placed in the ?ERROR help record, so that the user can issue the command HELP RQ (or whatever the code is) and get its explanation.
The value of $UCODE can come:
- from setting its value in the format's label group in which the error would be detected (which means adding code to the generated format definition in the current implementation of Screen Definer); or
- from the $MSG proc in the element's INPROC rules in the file definition; or
- from the $MSG proc in an INPROC statement in the format's label group in which the error would be detected (which means adding code to the generated format definition in the current implementation of Screen Definer).
- from Screen Definer itself, which sets it as:
- RQ for a required field for which the user fails to give a value;
- ID for an element field that holds the key of the record, if the record is being added in Prism (using the CREATE command) but a record with that key already exists.
Though you, as an application developer, and Screen Definer may be concerned with element and variable fields when creating and modifying code, the user will see a different set of field types, based on their appearance on the screen. For instance, a system variable field and a protected element field will both appear the same on the screen: white (if a color terminal is being used) or with brighter intensity. In fact, all data that is protected (i.e., element or variable values, not text or titles) is by default displayed with the same attributes, regardless of its source.
In essence, the distinction the user sees is between protected data fields, required fields and optional fields, not between element and variable fields. This distinction generates more field types, at least in terms of terminology. In particular, there are required fields, optional fields and protected data fields, whose members are shown in the chart below:
Type Usually called... ----------------------- ------------------------ Required fields Element fields Required Element fields User Variable fields Required Variable fields Optional fields Element fields Optional Element fields User Variable fields Optional Variable fields Protected Data fields Element fields Protected Element fields System Variable fields System Variable fields User Variable fields Protected Variable fields
An important part of this list are the "common names" listed to the right of some of the field types. Since system variables are always protected, a "required variable field" must be a user variable, so the word "user" is generally omitted. Similarly, the term "protected variable field" refers to a user variable, since a system variable does not need the "protected" label.
Each field on a screen has various attributes that control how it appears on the user's terminal. For instance, on a color terminal, the characters displayed in the field might be displayed as red or blue or green or some other color, as specified by the Color attribute for that field. (Remember, attributes that have no effect on a given terminal are ignored.)
Several of the field attributes have been discussed already: Protected/Unprotected and Required/Optional. [See 2.5.] But there are five "display attributes" for you to use too:
- 1) EMPHASIS -- how the foreground and background of the field appear. (The foreground is the character displayed in each character position of the field, while the background is the rest of the position.)
- The Emphasis value "Normal" means that both the foreground and background of the field be displayed as "normal", with the foreground being the color determined by the Color attribute (or the standard foreground for non-color terminals).
- "Reverse" indicates "reverse video", where the background color is determined by the Color attribute and the foreground is the color generally used for the background.
- "Hide" indicates that only the background should appear. It might be used for a "password" field, to provide an unprotected field whose value does not appear on the screen as it is typed.
- 2) COLOR -- the color of the characters within the field. That is, it determines the color of the foreground. (If the Emphasis attribute for the field is "Reverse", then Color determines the background of the field instead, with the terminal's standard background color becoming the foreground color.) The Color attribute affects only color terminals. The possible Color values are:
Blue Red Pink Green Yellow White Cyan (turquoise)
- 3) BLINKING -- whether the field should blink on and off. Blinking is often specified for error fields (see defaults below).
- 4) UNDERLINE -- whether or not the field should be underlined. It is most often used to mark unprotected fields, giving the screen the look of a form. The underlined fields help indicate where data should be input or what data can be changed.
- 5) BRIGHT -- whether the foreground (or the background, when the Emphasis is reverse video) should have a brighter-than-normal intensity. It is often specified for required fields, protected data fields, and error fields.
Here is a chart that shows the default values for the Blinking, Emphasis, Color and Underline attributes, based on field types. Remember that "Protected data fields" means System Variable fields, Protected Element fields, and Protected User Variable fields. "Required fields" means Required Element fields and Required User Variable fields, and "Optional fields" means Optional Element fields and Optional User Variable fields.
Field type Emphasis Color Blinking Underline Bright --------------------- -------- ------ -------- --------- ------ Required fields Bright Yellow No Yes Yes Optional fields Normal Green No Yes No Protected data fields Bright White No No Yes Error fields Bright Red Yes No Yes Title fields Normal Cyan No No No Text fields Normal White No No No
"Default values" are the values assigned to those attributes for those field types if you do not change them. You may change the default values globally for the six field types shown in the chart -- that is, you can make all error fields appear in reverse video instead of bright Emphasis if you want. You may also change the attributes for individual element and variable fields.
The global changes are made when you create your Screen Definer record using the CREATE entry form or when you modify your Screen Definer record using the MOD GENERAL entry form. The changes to individual element and variable fields are made when you create or modify a screen, using the ADD SCREEN or MOD SCREEN form.
Now that you have a good idea of the capabilities at your disposal in Screen Definer, you may be ready to design your screen or screens. When you define a screen, Screen Definer will ask you a few basic questions about the screen (e.g., it will ask you for an identifying name for the screen) and then Screen Definer will present you with a blank input screen.
There you "paint" your screen design.
You type different pieces of your design into the positions where you want them to appear on the completed screen. The text you want to appear is simply typed as text (with some exceptions). Title fields are handled similarly. The other types of fields are represented by special characters, generally one character per character position for the finished screen.
For example, knowing that the symbol for a protected element field is an asterisk character, you would type **** to signify a four-character protected element field.
Below is a compact list of the field designator characters. Each type is discussed separately afterwards. Note that most of this information is also available on the help page you get if you request HELP from the "Screen Painting" page of Screen Definer.
**** - protected element
____ - unprotected, required element
.... - unprotected, optional element
#** or $ - protected variable
#__ or @ - unprotected, required variable
#.. or # - unprotected, optional variable
=** or = - subsequent occurrence of a protected element or variable
=__ or = - subsequent occurrence of a required element or variable
=.. or = or ~ - subsequent occurrence of an optional element or variable
++++ - continuation on a subsequent row of a field that wraps
!!!! - error code
%text - title
text - text to appear on the screen
{text} - forced text; the text within the brackets is handled as
text, even though it may contain screen-painting symbols
& < > \ - (for future extension of Screen Definer)
For each character position of a field for an element value, type:
* (an asterisk) for a protected element value
_ (an underscore) for an unprotected, required element value
. (a period) for an unprotected, optional element value
Examples: ********** a 10-character protected element value
____ a 4-character unprotected, required element value
....... a 7-character unprotected, optional element value
___ =.. =.. a 3-character unprotected, required element value
followed by 2 3-character optional occurrences
of the same element (see "=" explanation below)
For the 1st character position of a field for a user or system variable value:
# (a pound sign) to indicate the start of a variable field
For subsequent character positions of the field, type either:
* (an asterisk) if the variable field is protected
_ (an underscore) if the variable field is unprotected, required
. (a period) if the variable field is unprotected, optional
Alternatively (particularly for 1-character fields), use these symbols for each character in the field:
$ (a dollar sign) if the variable field is protected
@ (at sign) if the variable field is unprotected, required
# (a pound sign) if the variable field is unprotected, optional
Examples: #__ (or @@@) a 3-character unprotected, required variable value
#*** (or $$$$) a 4-character protected variable value
# a 1-character unprotected, optional variable value
#.. (or ###) a 3-character unprotected, optional variable value
A title is a piece of text related to an element or variable field. Precede the typed text of the title with the character:
% (a percent sign)
Example: %Name: a title field; "Name:" will appear as placed
Rules: A title may contain single but not multiple blanks. It cannot wrap
to another row, unless each piece of it is preceded by a percent sign.
Examples: %Phn Num: a title field; single blank is ok
%Phn Num: a title field (Phn) and a text field (Num)
Error code fields point to errors made on an input screen. They are associated with element or variable fields. For each character in an error field, type:
! (an exclamation point)
Example: !! a 2-character error field (recommended size)
Rules: An error field is associated with the first element or variable field
to its right. Title and text fields may come between the error field
and the field to which it is associated, but both must be in the same
row.
Example: !!%State: __ a 2-character error field for a two-character
required element field with a title
For the 1st character position in a field for a subsequent occurrence of an element or variable, type:
= (an equal sign)
For subsequent character positions of the field, type either:
* (an asterisk) for a protected element or variable
_ (an underscore) for an unprotected, required element or variable
. (a period) for an unprotected, optional element or variable
Alternatively, use these symbols for each character in the field:
= (an equal sign) if the field is exactly the same as the previous one
~ (a "not" sign, or tilde) if the field is optional, but the previous
one was required
Examples: #**** ===== two 5-character protected fields for a variable
___ =__ =__ six 3-character unprotected required fields for
=__ =__ =__ an element
______ two 6-character unprotected, required fields for
====== an element, and two optional fields for the
=..... same element below them
======
Rules: A repeat symbol must be the same length as the first occurrence. A
repeat symbol directly beneath an element or variable is associated
with that element or variable. A repeat symbol to the right of an
element or variable on the same line is associated with that element
or variable, unless the preceding rule applies. Occurrence numbers
follow a left-to-right, top-to-bottom precedence. (See examples below)
Examples: **** ____ two protected element fields (one below the other)
=*** =___ and two unprotected, required element fields
A: ___ === two unprotected, required element fields for "A"
BB: ___ === and two for BB
A: ___ === three unprotected element fields for "A" and
B: ___ === one for B (Remember, in ambiguous situations,
the element or variable directly above the
repeat symbol has precedence over one to the
left.) The occurrences can be symbolized as:
A: (A1) (A2)
B: (B0) (A3)
Use offsetting, as in the previous example, if
the precedence rules work against your design.
To indicate continuation of an element or variable value on the next row, type for each character position in that row:
+ (a plus sign)
Example: #********* a protected variable value, continuing on the
++++++++++ next row
Rules: The continuation field must start directly under the first character
in the field being continued, and must be the same length as that field.
Example: .......... (invalid: the continuation field is shorter than
++++++++ the field being continued)
Type text as you want it to appear on the screen. If it contains any of the special screen-painting characters, especially if they could be misinterpreted, surround the text with braces. Remember that the symbols &, <, > and \ (ampersand, less-than, greater-than and back slash) are special characters too, reserved for future use.
Examples: record.key braces not needed
record . key braces needed because of spaces around period
Here are some useful rules and suggestions to keep in mind when you are designing a screen. Some of them have already been discussed in this chapter but bear repetition.
You cannot have two fields directly adjacent to each other:
Invalid: !!____ Valid: !! ____
Note that you can count the "%", "{" and "}" screen-painting characters as blanks when following this rule because they will not appear on the user's screen (they only take up a position on the painted screen).
Remember that your defined screens can only be up to 22 rows high. You may see more blank rows when you paint the screen, but Screen Definer won't let you paint anything in the bottom ones.
Use screens liberally -- too much data and too many different field types can make a screen look very crowded and become difficult to read. It is not difficult in Prism to allow users to go from one input screen to another, and not much harder in SPIRES.
On the other hand, try to keep the total number of screens needed for a transaction reasonable. Don't require the user to fill out so many screens that he or she gets tired or lost trying to do one piece of work. In particular, try to keep related data together on one screen, so that the user can get a sense of completing a unified block on each screen.
This chapter is a step-by-step guide through a Screen Definer session, displaying and describing the screens you will see. Your input on each screen is shown in bold.
If you are not familiar with Prism, you should at least skim the short "Introduction to Prism" pamphlet so that you will understand how to use Prism applications, e.g., how to move from one screen to another, how to find records, etc. Remember to issue the HELP command at any point in your Prism session if you would like more information.
Issue the command PRISM to begin your Prism session:
COMMAND> prism
After you choose Guided or Command mode (Guided mode is easier to use if you are not very familiar with Prism), you will be asked to select a Prism application. You can wait till it appears on the menu of selections, or you can simply type SCREEN DEFINER at the prompt.
Once you have selected Screen Definer, you will see Screen Definer's "welcome". It includes directions for how to proceed, depending on what you want to do.
Although Prism applications commonly have three distinct types of tasks (searching, reporting and entry), you will generally use entry tasks to work with Screen Definer. Hence, you should issue the ENTRY command to see the list of entry forms available to you in Screen Definer.
The rest of this chapter will discuss the five entry forms available in Screen Definer, one section apiece:
3.1 CREATE create a Screen Definer record 3.2 MOD GENERAL modify general Screen Definer record information 3.3 ADD SCREEN add a screen to a Screen Definer record 3.4 MOD SCREEN modify/remove a screen in a Screen Definer record 3.5 GENERATE generate a format from a Screen Definer record 3.6 REM RECORD remove a Screen Definer record
The procedure for using each entry form will be covered, starting from the list of entry forms.
The CREATE entry form is used to create a new Screen Definer record to hold a set of screens. You cannot define any screens until you have created a Screen Definer record to hold them.
Remember to follow the procedure described at the beginning of this chapter if you have not already entered Prism and selected the Screen Definer application. [See 3.]
Screen Definer will present you with the first page of the CREATE form, the General Information page.
Here is the first page of the CREATE entry form:
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: CREATE 02/19/86 16:48| |General Information | |The two pages of this entry form ask you for some general information about the| |Screen Definer record and all the screens in it: | | | | Screen Definer record key: GQ.JNK.________________ | | | | Subfile to which this record applies: __________________________________ | | | | | |_______________________________________________________________________________| |Screen Definer record key: a name beginning with your account number that | | uniquely identifies this Screen Definer record, e.g., GQ.DOC.RESTAURANT. | | | |Subfile to which this record applies: All the screens in a single Screen | | Definer record must apply to the same SPIRES subfile. For Prism | | applications, type "PRISM file-id", replacing "file-id" with the file-id | | of your application. | | | |-Form continues on the next page | |Type OK below to continue to next page. Type UNDO to discard changes to page. | |Type CANCEL to cancel transaction. Type HELP for more information. | |YOUR RESPONSE: | |f1=Help f5=OK f7=Undo f8=Cancel f9=Options| +-------------------------------------------------------------------------------+
On this page of the form, Screen Definer asks you to name the Screen Definer record (that is, provide a key value) and to name the subfile it is associated with. The Screen Definer record name always begins with your account number, so that prefix is placed in the record name's field for your convenience.
When you have typed the two names, type OK in the command line (after "YOUR RESPONSE:") and press the return key, or just press the F5 function key. Here is what the screen might look like just before pressing the return key:
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: CREATE 02/19/86 16:48| |General Information | |The two pages of this entry form ask you for some general information about the| |Screen Definer record and all the screens in it: | | | | Screen Definer record key: GQ.JNK.BLDDONOR________ | | | | Subfile to which this record applies: PRISM BLDDONOR____________________ | | | | | |_______________________________________________________________________________| |Screen Definer record key: a name beginning with your account number that | | uniquely identifies this Screen Definer record, e.g., GQ.DOC.RESTAURANT. | | | |Subfile to which this record applies: All the screens in a single Screen | | Definer record must apply to the same SPIRES subfile. For Prism | | applications, type "PRISM file-id", replacing "file-id" with the file-id | | of your application. | | | |-Form continues on the next page | |Type OK below to continue to next page. Type UNDO to discard changes to page. | |Type CANCEL to cancel transaction. Type HELP for more information. | |YOUR RESPONSE: ok | |f1=Help f5=OK f7=Undo f8=Cancel f9=Options| +-------------------------------------------------------------------------------+
In general, in the rest of this chapter, pages of an entry form will be shown to you with the data filled in as above, not blank as shown in the first example.
Screen Definer will verify the information, e.g., that you typed a valid record key, or that you can select the subfile you named. If an error is detected, Screen Definer will mark the field or fields where the error occurs with an error code, put an error message in the message area near the bottom of the page, and reprompt you for valid values. If you do not understand what error(s) you made, issue the HELP command, optionally followed by the error code.
You make corrections by typing over your mistakes and then type OK to try again.
After Screen Definer approves the values you have entered, you continue to the next page.
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: CREATE 02/19/86 16:50| |Default Attributes for GQ.JNK.BLDDONOR | | | | | |Below are the default display attributes for the various types of fields you | |may place on a screen. If you want to change any, type over them with the new | |choices. Remember, type HELP if you want information about the attributes. | |_______________________________________________________________________________| | | | Autotab: Yes Emphasis Color Blinking Underline Bright | |Required: Bright Yellow No Yes Yes | |Optional: Normal Green No Yes No | |Protected Data: Bright White No No Yes | |Error Fields: Bright Red Yes No Yes | |Title Fields: Normal Cyan No No No | |Text Fields: Normal White No No No | |_______________________________________________________________________________| |Emphasis: Normal, Reverse, Hide | |Color: Blue, Red, Pink, Green, Cyan, Yellow, White | | | |Type SEND to complete this transaction. Type CANCEL to cancel transaction. | |Type PREVIOUS to return to prior page. Type UNDO to discard changes to page. | |YOUR RESPONSE: send | |f1=Help f4=Previous f6=Send f7=Undo f8=Cancel f9=Options| +-------------------------------------------------------------------------------+
On this screen you choose the attributes for various types of fields. [See 2.6.] For example, unless you change the value shown here, a text field will appear in white when it is displayed. To make changes, you use the tab key to move to the proper position and type the desired value over the old one, choosing a value from the list shown.
"Autotab" is a feature you can request that affects the cursor when the patron is entering data on input screens defined in the Screen Definer record. If Autotab is Yes, then the cursor will automatically move to the start of the next unprotected field when you have filled the current field. If Autotab is No, the cursor will just stay at the end of the current field, and you will need to use the tab key or other cursor positioning keys to move to the next field.
Remember that all fields of all screens defined in the Screen Definer record are affected by your choices here. All error, title and text fields will have the attributes specified on this screen; by default, so will element and variable fields. However, you can change the attributes of individual element and variable fields that you paint in the ADD SCREEN and MOD SCREEN entry forms.
When you are satisfied with your selections, type the SEND command to complete the transaction. When you see the confirmation screen, your Screen Definer record has been created:
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: CREATE 02/19/86 16:51| | | |The Screen Definer record GQ.JNK.BLDDONOR has been created. | | | |To create screens for this record, follow the steps below. (The steps are also| |shown on the welcome screen to the ADD SCREEN entry form once you get there.) | | | | 1) Jot down your Screen Definer record key, GQ.JNK.BLDDONOR. You will | | need it after the next step. | | | | 2) Type the ENTRY command, and then choose the ADD SCREEN entry form. | | | | 3) Type the command FIND RECORD GQ.JNK.BLDDONOR, or just type FIND and | | use other search criteria to find this Screen Definer record again. | | | | 4) Type GET to begin using the ADD SCREEN entry form to create a screen. | | | |-Transaction successful; record sent (ID: GQ.JNK.BLDDONOR) | |To add a new record: type CREATE | |To search this file: type FIND. | |To change entry forms: type ENTRY. | |To choose a different file: type SELECT. | |YOUR RESPONSE: | |f1=Help f2=Select f3=Find f6=Create f8=Entry f9=Options| +-------------------------------------------------------------------------------+
As the confirmation screen tells you, you might want to write down the Screen Definer record key; it will be easier for you to find the Screen Definer record when you need it later if you remember its key.
If you are ready to add one or more screens, you might want to continue to the ADD SCREEN entry form. [See 3.3.] Otherwise, we'll look at what changes can be made to the data in the Screen Definer record so far, using the MOD GENERAL entry form. [See 3.2.]
The MOD GENERAL entry form is used to make changes to the general information relating to all the screens in a Screen Definer record. Using this form, you can change the default attributes for various types of fields and change the name of the subfile the record is associated with.
The easiest way to find your record again is to issue the command:
FIND RECORD gg.uuu.record.key
where "gg.uuu.record.key" is the key of your Screen Definer record, which we recommended you write down. However, if you do not remember it, issue the command FIND, and Prism will show you which indexes you can use to find the appropriate record. You can retrieve only records defined by your account; so you cannot modify other people's Screen Definer records.
If there is more than one record in your current search result, you need to specify the number of the desired record on the GET command.
There is just one page in the MOD GENERAL entry form:
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: MOD GENERAL 02/19/86 16:55| |Default Attributes for GQ.JNK.BLDDONOR -Record 1 of 1| | Subfile for this record: PRISM BLDDONOR________________________ | | | |Below are the default display attributes for the various types of fields you | |may place on a screen. If you want to change any, type over them with the new | |choices. Remember, type HELP if you want information about the attributes. | |_______________________________________________________________________________| | | | Autotab: Yes Emphasis Color Blinking Underline Bright | |Required: Normal Yellow No Yes Yes | |Optional: Normal Green No Yes No | |Protected Data: Normal White No No Yes | |Error Fields: Normal Red Yes No Yes | |Title Fields: Normal Cyan No No No | |Text Fields: Normal White No No No | |_______________________________________________________________________________| |Emphasis: Normal, Reverse, Hide | |Color: Blue, Red, Pink, Green, Cyan, Yellow, White | | | |Type SEND to complete this transaction. Type UNDO to discard changes to page. | |Type CANCEL to cancel transaction. Type HELP for more information. | |YOUR RESPONSE: | |f1=Help f6=Send f7=Undo f8=Cancel f9=Options| +-------------------------------------------------------------------------------+
The MOD GENERAL entry form is almost exactly the same as the Default Attributes page of the CREATE form. [See 3.1.] It shows you the name of the subfile the Screen Definer record serves, as well as the default attributes you chose earlier.
You may make changes to the attributes for the various types of fields. Your changes will affect all the error, text and title fields of all the screens already defined in the Screen Definer record. The changes will not affect element and variable fields already defined, but will affect any new element or variable fields added later.
In addition, you may change the subfile to which the Screen Definer record is tied. However, if you have already created any screens that name elements in the first subfile and the elements with those names do not exist in the second one, Screen Definer will warn you at this point that you must either change the subfile name again (probably back to the original) or else change the element names in the screens of this record, using the MOD SCREEN form. Screen Definer will even tell you which screens and frames of the record contain the elements that must be changed.
After making any changes you want to make, issue the SEND command.
The ADD SCREEN and MOD SCREEN forms are the heart of Screen Definer. They have the most pages and are the most often used of the entry forms.
You define a screen for a Screen Definer record with the ADD SCREEN form. The form asks you some general questions about the screen, and then you paint the screen, using the screen design you developed and the screen-painting characters described in the previous chapter. [See 2.7.] More questions follow, which are concerned with the elements and variables you painted. Then you can decide to end the transaction with the SEND command, or you can add one or more frames to the screen definition, which you answer questions about and paint, or you can make modifications to frames you have already painted. The sequence continues till you issue the SEND command to end the screen definition.
Here is the procedure:
The easiest way to find your record again is to issue the command:
FIND RECORD gg.uuu.record.key
where "gg.uuu.record.key" is the key of your Screen Definer record. If you don't remember it, issue the command FIND, and Prism will show you which indexes you can use to find the appropriate record. You can retrieve only records defined by your account; so you cannot modify other people's Screen Definer records.
If there is more than one record in your current search result, you need to specify the number of the desired record on the GET command.
Filling out the form is straightforward. Remember to issue the HELP command if you want help in filling out the form. Beginning on the next page of this document, you'll see each page of the entry form, accompanied by information about how to fill out the page.
In most cases, each page of the form shown in this section has already been filled out, for the example screen for BLOOD DONORS. [See 1.2.]
Below is a list of pages in the ADD SCREEN form, shown in the order in which they appear. Some of these pages you may not see; others you may see several times. It all depends on the complexity of your screen. But you will always see the General Information page, which is the first one.
General Information page
Base-Frame pages:
Painting page
Review page
Elements page
Element Review page
Element Display and Defaults page
Variables page
Variable Review page
Variable Display and Defaults page
Frames page
Subordinate-Frame pages:
Subordinate Frame Information page
Painting page
Review page
Elements page
Element Review page
Element Display and Defaults page
Variables page
Variable Review page
Variable Display and Defaults page
Frames page
(etc.)
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: ADD SCREEN 02/19/86 17:51| |General Information -Record 1 of 1| |This is a screen definition for Screen Definer record GQ.JNK.BLDDONOR, | | for subfile PRISM BLDDONOR: | | | | Screen ID: DONOR_______ | | | | Screen Title: Blood Donor Input_______________ | | Type NO if all fields| | Do you want to paint any base-frame fields? Yes are in subordinate | | frames. | | Is this screen for output only? No_ | | | | Copy to Screen Definer Record Key Screen ID Defines? | | this screen from: _______________________ ____________ No. | |_______________________________________________________________________________| |Note: On the next page you paint the base-frame fields, unless you said NO to | |the question about them. For information on painting, ask for HELP on the | |screen-painting page of the entry form, or see the Screen Definer manual. | |-Form continues on the next page | |Type OK below to continue to next page. Type UNDO to discard changes to page. | |Type CANCEL to cancel transaction. Type HELP for more information. | |YOUR RESPONSE: ok | |f1=Help f5=OK f7=Undo f8=Cancel f9=Options| +-------------------------------------------------------------------------------+
If you have base-frame fields to paint, then the next page of the form is "Base-Frame Painting". If you do not, then Screen Definer will take you to the "Subordinate Frame Information" page to start defining a subordinate frame on the screen. [See 3.3.9.]
Your first view of the painting page for a screen essentially looks like this:
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: ADD SCREEN 02/19/86 17:53| |Screen DONOR: Paint Base-Frame Fields -Record 1 of 1| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |-...v....1....v....2....v....3....v....4....v....5....v....6....v....7....v....| |Type OK below to continue to next page. Type CANCEL to cancel transaction. | |Type PREVIOUS to return to prior page. Type UNDO to discard changes to page. | |YOUR RESPONSE: | |f1=Help f4=Previous f5=OK f7=Undo f8=Cancel f9=Options| +-------------------------------------------------------------------------------+
On standard 24-row terminals, you have 17 rows, starting from the first blank row (row 3), in which to "paint" your screen. On larger terminals, up to 22 rows can "painted". Though your terminal may show you more than 22 blank rows on the page, only the top 22 can be used; the lower ones are protected.
If you declared on the previous page that you have base-frame fields to paint, then here on this first go-round, you paint those fields -- that is, here you paint the fields that are not inside any subordinate frames.
Using your screen design, type the appropriate screen-painting symbols on the page. The symbols were described in detail in the chapter "Designing Screens". [See 2.7.] Type HELP to see them online. Here again is the summary list of them:
Screen-Painting Characters
**** - protected element
____ - unprotected, required element
.... - unprotected, optional element
#** or $ - protected variable
#__ or @ - unprotected, required variable
#.. or # - unprotected, optional variable
=** or = - subsequent occurrence of a protected element or variable
=__ or = - subsequent occurrence of a required element or variable
=.. or = or ~ - subsequent occurrence of an optional element or variable
++++ - continuation on a subsequent row of a field that wraps
!!!! - error code
%text - title
text - text to appear on the screen
{text} - forced text; the text within the brackets is handled as
text, even though it may contain screen-painting symbols
& < > \ - (for future extension of Screen Definer)
Here is the example screen as it would appear after you painted its base-frame:
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: ADD SCREEN 02/19/86 17:53| |Screen DONOR: Paint Base-Frame Fields -Record 1 of 1| | %Donor Number: **** %Total Pints Donated: *** | | !!%Name: ____________________ | | !!%Address: ______________________________ | | =............................. | | !!%City: _______________ !!%State: __ !!%Zipcode: ..... | | %Phone Number: ......................... !!%Can he/she be called? ... | | !!%Blood Type: ___ | | | | %Comments: ............................................................. | | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | | [* * * * * * * * * * Donation Information * * * * * * * * * *] | | %Date(s) %Location(s) | | | | | | | | | | | |-...v....1....v....2....v....3....v....4....v....5....v....6....v....7....v....| |Type OK below to continue to next page. Type CANCEL to cancel transaction. | |Type PREVIOUS to return to prior page. Type UNDO to discard changes to page. | |YOUR RESPONSE: ok | |f1=Help f4=Previous f5=OK f7=Undo f8=Cancel f9=Options| +-------------------------------------------------------------------------------+
Here is the example screen as it would appear after you painted its base-frame:
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: ADD SCREEN 02/19/86 17:53| |Screen DONOR: Paint Base-Frame Fields -Record 1 of 1| | %Donor Number: **** %Total Pints Donated: *** | | !!%Name: ____________________ | | !!%Address: ______________________________ | | =............................. | | !!%City: _______________ !!%State: __ !!%Zipcode: ..... | | %Phone Number: ......................... !!%Can he/she be called? ... | | !!%Blood Type: ___ | | | | %Comments: ............................................................. | | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | | [* * * * * * * * * * Donation Information * * * * * * * * * *] | | %Date(s) %Location(s) | | | | | | | | | | | |-...v....1....v....2....v....3....v....4....v....5....v....6....v....7....v....| |Type OK below to continue to next page. Type CANCEL to cancel transaction. | |Type PREVIOUS to return to prior page. Type UNDO to discard changes to page. | |YOUR RESPONSE: ok | |f1=Help f3=Cancel f4=Undo f7=Previous f8=OK f9=Options| +-------------------------------------------------------------------------------+
Note that the text "Donation Information" and the titles "Date(s)" and "Location(s)" were painted here. We did not save them for the "Donation" frame that handles the DONATION structure, which we will paint later. That's because we don't want the heading and titles repeated for each occurrence of the frame -- we want them to appear only once.
Remember to leave a blank space between fields. (The screen-painting characters "{", "}" and "%" count as blanks in this context.)
Each time you paint the screen and issue the OK command, Screen Definer gives you a chance to review your work, with the Review page.
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: ADD SCREEN 02/19/86 17:56| |Screen DONOR: Review -Record 1 of 1| | Donor Number: **** Total Pints Donated: *** | | !! Name: ____________________ | | !! Address: ______________________________ | | =............................. | | !! City: _______________ !! State: __ !! Zipcode: ..... | | Phone Number: ......................... !! Can he/she be called? ... | | !! Blood Type: ___ | | | | Comments: ............................................................. | | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | | * * * * * * * * * * Donation Information * * * * * * * * * * | | Date(s) Location(s) | | | | | | | | | | | |-Form continues on the next page | |Type OK below to continue to next page. Type CANCEL to cancel transaction. | |Type PREVIOUS to return to prior page. Type UNDO to discard changes to page. | |YOUR RESPONSE: ok | |f1=Help f4=Previous f5=OK f7=Undo f8=Cancel f9=Options| +-------------------------------------------------------------------------------+
The Review page is shown to you each time you finish painting a frame of your screen. It will give you a better idea of what the screen will look like when it is presented to the user. Specifically, the Review page:
- shows you any painting errors