****************************************************************** * * * 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 you made (for example, painting a continuation field longer than the previous field).
- shows the different types of fields using the color attributes established for them;
- removes the screen painting symbols "%", "{" and "}" (only
for this display; they still exist internally);
- "normalizes" any fields with multiple "&", "@", "#", "=" or "~" symbols to the standard display for that type of field (single-character fields with these symbols are left alone), as follows:
$$$ converts to #**
@@@ converts to #__
### converts to #..
=== converts to =** if the previous occurrence is protected
=== converts to =__ if the previous occurrence is required
~~~ converts to =..
- duplicates the occurrences of any subordinate frames painted on the screen, based on the number of occurrences given on the "Subordinate Frame Information" screen for that frame [See 3.3.9.]
To make changes, type PREVIOUS to return to the Paint page. Remember, you can make changes to the Base-Frame items only on the "Base-Frame Painting" page, and to items in a subordinate frame only on the Paint page for that frame. If needed, you can continue forward (OK) to the Frames page, where you can ask to modify any frames already painted on this screen. You can also make changes at a later time by using the MOD SCREEN entry form.
If you have painted any element fields on your screen, Screen Definer asks you to identify them on the Elements page.
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: ADD SCREEN 02/19/86 18:02| |Screen DONOR: Base-Frame Elements -Record 1 of 1| | Donor Number: A*** Total Pints Donated: B** | | !! Name: C___________________ | | !! Address: D_____________________________ | | =............................. | | !! City: E______________ !! State: F_ !! Zipcode: G.... | | Phone Number: H........................ !! Can he/she be called? I.. | | !! Blood Type: J__ | | | | Comments: K............................................................ | |_______________________________________________________________________________| |Elements 1-11 of 11. To review an element, mark it with an X.| | _ A: id x B: total.pints | | _ C: name _ D: address | | _ E: city _ F: state | | _ G: zipcode _ H: phone.number | | _ I: can.be.called _ J: blood.type | | _ K: comments | |-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| +-------------------------------------------------------------------------------+
It is easier in a real Screen Definer session to see how this page of the entry form works than to see it here. An explanation may help clarify the example page above, which we have already filled out.
If there are element fields defined in the top half of your screen, Screen Definer splits the page in half, placing a letter from A to L in the first character position of the first 12 element fields in the top half. In the bottom half of the page, the letters are listed in front of fields in which you type element names. You type the name of the element next to the letter that appears in the appropriate field above.
To review or revise any of the following for a particular element, type an X in the field just before the element's name (e.g., before "total.pints" above):
- the occurrence number of the element
- the adjustment of the value within the field for output
- an edit mask
- display attributes (Color, Emphasis, Blinking, Bright and Underline)
- a default value for input
On your terminal screen, it is easy to see the element fields and the letter that begins each one because each field will be in reverse video, blinking.
When you have typed the names of all the marked elements, issue the OK command to continue. Screen Definer then verifies that you named valid elements; if not, you will get an error message and will be reprompted for valid element names. (You can correct them, or if the situation warrants, issue the PREVIOUS command to return to the painting pages to make changes.)
When Screen Definer has verified that you named valid elements, it marks the next 12 element fields in the top half with the letters A to L, and continues as above.
When all the elements in the top half of the screen are identified, Screen Definer flips the top and bottom halves, and you begin identifying the elements in the bottom half in the same manner.
If you marked any of the element names with an X, Screen Definer will continue with an element Review Screen. [See 3.3.5.] If you didn't mark any, Screen Definer will take you to the Variables page; but if you didn't paint any Variables, the next page you will see is Frames. [See 3.3.6, 3.3.8.]
If you have marked any element fields on the Elements page so that you can review its display attributes, edit mask, adjustment in the field, etc., that information is presented to you on the Element Review page, giving you a chance to make modifications if desired.
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: ADD SCREEN 02/19/86 18:03| |Review Page for Element: TOTAL.PINTS -Record 1 of 1| | Donor Number: **** Total Pints Donated: *** | | !! Name: ____________________ | | !! Address: ______________________________ | | =............................. | | !! City: _______________ !! State: __ !! Zipcode: ..... | | Phone Number: ......................... !! Can he/she be called? ... | | !! Blood Type: ___ | | | | Comments: ............................................................. | |_______________________________________________________________________________| | Element Name: TOTAL.PINTS | Mark with an X to add or review:| | Starting Occurrence: 1 | X Display and Default Values | | Adjust: Right Left, Center, Right | | | Edit Mask: _____________________________ | | | | | |____________________________________________|__________________________________| |Display: Protected Field (White, Bright, Protected) | |-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| +-------------------------------------------------------------------------------+
On the Element Review page, you begin working with the individual elements you marked, one at a time. As before on the Elements page, Screen Definer splits the screen in half. If the marked element is in the top half of the painted screen, Screen Definer marks it with reverse video, blinking, to distinguish it from the rest. In the bottom half of the screen are listed the attributes for the element in question, which you can change as described below:
If you mark the field so that you can review Display and Default Values, then when you issue the OK command to continue to the next page of the ADD SCREEN form, Screen Definer will take you to the Element Display and Defaults page, shown below. On the other hand, if you are through with this element (meaning you haven't marked the "Display and Default Values" field), then typing OK will take you to the next Element Review page, or, if you have no more marked elements, to the Variables page [See 3.3.6.] or, if you didn't paint any variables, to the Frames page. [See 3.3.8.]
If you mark the "Display and Default Values" field on the Element Review page, Screen Definer makes a few changes to it, showing you a page like this:
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: ADD SCREEN 02/19/86 18:03| |Display and Defaults for Element: TOTAL.PINTS -Record 1 of 1| | Donor Number: **** Total Pints Donated: *** | | !! Name: ____________________ | | !! Address: ______________________________ | | =............................. | | !! City: _______________ !! State: __ !! Zipcode: ..... | | Phone Number: ......................... !! Can he/she be called? ... | | !! Blood Type: ___ | | | | Comments: ............................................................. | |_______________________________________________________________________________| | Element Name: TOTAL.PINTS | | Color: White Blue, Red, Pink, Green, Cyan, Yellow, White | | Emphasis: Normal Normal, Reverse, Hide | | Blinking: No Yes, No | | Underline: No Yes, No | | Bright: Yes Yes, No | | Default: ___ | |-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 Element Display and Defaults page is thus a continuation of the Element Review page, allowing you to make changes to the display attributes and enter a default value (see below) for the individual element being reviewed.
Once you have completed your work on this page, you type OK to continue. Just as described above for the Element Review page, if you have any more elements to review, Screen Definer will take you to the Element Review page for the next one. Otherwise, you will go forward to the Variables page (if you painted any variables on the screen) or to the Frames page. [See 3.3.6, 3.3.8.]
The Variables page works exactly like the Elements page just described. [See 3.3.4.] If you have painted any variable fields on your screen, Screen Definer will ask you to name them on this page.
We did not paint any variables on our DONOR screen, so we would not see this page of the entry form when defining that screen. The DONOR example continues with the Frames page. [See 3.3.8.] However, to show you an example of the Variables page, and two others associated with it, we will use another example, SCREEN2, in this section and the next. SCREEN2 is a Menu screen, offering the user a choice between two activities, with two occurrences of an optional variable painted as "#" and "~", which we will name NEXTTASK.
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: ADD SCREEN 02/19/86 20:04| |Screen SCREEN2: Base-Frame Variables -Record 1 of 1| | Mark the next task you want to do with an X: | | | | !! # Add donations to the current record | | !! ~ Make changes to the donor's general information | | | | | | | | | | | |_______________________________________________________________________________| |Variables 1-1 of 1. To review a variable, mark it with an X.| | X A: #NEXTTASK____ | | | | | | | | | | | |-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| +-------------------------------------------------------------------------------+
Screen Definer will show you one half of the screen at a time, prompting you for the variable names in the other half. You type the name of the system or user variable associated with each marked field in the place next to the appropriate identifying letter. In addition, you mark an X in front of the names of any variables for which you want to review its display attributes, its type, or its adjustment within the field.
Precede the name of each variable with either a dollar sign ($, for system variables) or a pound sign (#, for user variables).
Remember that system variables are for output only.
Type OK when you have typed all the names and are ready to continue, either to the next page or to the next 12 variables on the screen, whichever is the case. If you are going "to the next page", you will go to the Variable Review page for the first of any elements you marked with an X. [See 3.3.7.] If you didn't mark any, meaning that you want any user variables you painted to be defined as string variables, left-adjusted, with the standard default attributes, then Screen Definer will take you to the Frames page. [See 3.3.8.]
If you marked any variable fields on the Variables page so that you can review its display attributes, its type (for user variables) or its adjustment in the field, that information is presented to you on the Variable Review page, giving you a chance to make changes if you want. In effect, this screen also defines the user variables; the variable's type, declared here, will appear in the generated vgroup definition.
Here again we continue the example introduced in the previous section. [See 3.3.6.] It has nothing to do with the DONOR screen being defined in the rest of section 3.3.
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: ADD SCREEN 02/19/86 20:02| |Review Page -Record 1 of 1| | Mark the next task you want to do with an X: | | | | !! # Add donations to the current record | | !! ~ Make changes to the donor's general information | | | | | | | | | | | |_______________________________________________________________________________| | Variable Name: #NEXTTASK | Mark with an X to add or review:| | | X Display and Edit Mask Values| | | | | Type: String (e.g., String, Int, Flag) | | | Adjust: Left Left, Center, Right | | |____________________________________________|__________________________________| |Display: Optional Field (Green, Normal, Underline) | |-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| +-------------------------------------------------------------------------------+
On the Variable Review page, you begin working with the individual variables you marked, one at a time. It is similar to the Element Review page in appearance and function.
The screen is split in half again. If the marked variable is in the top half of the painted screen, Screen Definer marks it with reverse video, blinking, to distinguish it from the rest of the screen. In the bottom half of the screen are listed the attributes for the variable, as well as some other information, which you can change as described below:
If the variable is a user variable that has been painted with multiple occurrences, Screen Definer will also define a subscript variable for it. The subscript variable's name is determined by adding the three letters SUB to the end of the variable name. In a future version of Screen Definer, you will be able to choose another name for the subscript variable, or even name another variable already defined as the subscript.
If you mark the field so that you can review Display and Edit Mask values, then when you issue the OK command, Screen Definer will take you to the Variable Display and Defaults page, shown below. On the other hand, if you are through with this variable, meaning that you didn't mark that field, then typing OK will take you to the next Variable Review page or, if you have no more variables to review, to the Frames page. [See 3.3.8.]
This page, which you use only if you marked the "Display and Edit Mask Values" field on the Variable Review page, is similar to the parallel one for elements. Screen Definer makes only a few changes to the screen, still displaying the variable being defined in reverse video, blinking, in the top half of the screen (unless that variable was painted on the bottom half of the screen, in which case the attributes and edit mask blanks appear in the top half). For the SCREEN2 example, the page would look like this:
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: ADD SCREEN 02/19/86 20:03| |Display and Defaults for Variable: NEXTTASK -Record 1 of 1| | Mark the next task you want to do with an X: | | | | !! # Add donations to the current record | | !! ~ Make changes to the donor's general information | | | | | | | | | | | |_______________________________________________________________________________| | Variable Name: #NEXTTASK | | Color: Green Blue, Red, Pink, Green, Cyan, Yellow, White | | Emphasis: Normal Normal, Reverse, Hide | | Blinking: No Yes, No | | Underline: Yes Yes, No | | Bright: No Yes, No | | | |-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 individual display attributes Color, Emphasis, Blinking and Underline, were described earlier. [See 2.6.] Changes you make to them here will affect only the variable being reviewed.
If the variable is defined as a numeric type (INTEGER or PACKED), then the edit mask prompt will appear below the display attributes. Edit masks were discussed briefly in the section on the Element Review page. [See 3.3.5.] But see chapter 19 of the manual "SPIRES Technical Notes" for complete information on edit masks.
Once you have made changes to this page, you can type OK to continue. If there are more variables marked for review, Screen Definer will take you to the next Variable Review page; otherwise, you will go to the Frames page next. [See 3.3.8.]
Whenever you complete your work on the base-frame fields or on a subordinate frame of the screen, Screen Definer shows you the Frames page. Here you either complete your work by issuing the SEND command, or you decide to add, modify or remove a frame of the screen. (Once again, we use the DONORS screen example.)
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: ADD SCREEN 02/19/86 18:03| |Frames for GQ.JNK.BLDDONOR, screen DONOR -Record 1 of 1| |Type SEND at the bottom of the page to complete this Screen Definer record. | | OR | |Mark the task you want to do with an X and type OK at the bottom of the page: | | X Add a new frame | | _ Modify an existing frame | | | | | | # Frame Name Structure Name Frame Size | | 1 <Base Frame> 17 | | | | | | | | | | | | | | | | | |-<Base Frame> completed | |Type OK below to continue to next page. Type CANCEL to cancel transaction. | |Type SEND to complete this transaction. Type UNDO to discard changes to page. | |YOUR RESPONSE: ok | |f1=Help f5=OK f6=Send f7=Undo f8=Cancel f9=Options| +-------------------------------------------------------------------------------+
In the example, we marked the task "Add a new frame" because we need to add a subordinate frame for the DONATION structure. If we had wanted to make more changes to the base frame, we could have marked the "Modify" task, and Screen Definer would have taken us to the painting page for the base frame again for changes.
You may notice that the page mentions nothing about removing any frames. That's because in this particular case, there are no frames that can be removed, so that task is not listed. (You cannot remove the base-frame fields all at once, though you could choose to modify them. Then if you really want to remove the base-frame fields, you can erase them all from the painting page.) You will see the "remove a frame" task listed after we have added the frame for the DONATION structure. [See 3.3.9.]
The Subordinate Frame Information page begins a series of pages of the ADD SCREEN entry form used to create new frames or modify old ones. It asks you for some information about the frame before letting you paint it on your screen.
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: ADD SCREEN 02/19/86 18:04| |Screen DONOR: Subordinate Frame Information -Record 1 of 1| | Frame Name: DONATION____ | | | | Frequency: 5_ Occurrences per screen or containing frame| | | | Rows per occurrence: 1_ Size (in number of rows) of this frame | | | | Structure: DONATION________ Structure this frame represents, if any | | | | Starting occurrence: 1__ Number of first occurrence of structure | | | | | |_______________________________________________________________________________| | Existing Subordinate Frames: | | | | | |On the next page, paint the frame named here. You cannot make changes to other| |frames. For information on painting, ask for HELP on the next page. | |-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| +-------------------------------------------------------------------------------+
On this page you type a unique name for the frame. (No other frame on this screen may have the same frame name.) A list of all the subordinate frames already defined for the screen appears near the bottom of the page, as shown above ("Existing Subordinate Frames:").
Also, were there any subordinate frames to list, another prompt would appear for you to answer: "Contained by", which you answer with the name of the subordinate frame that contains the one being defined, if any. You do not type any name if the frame is contained only by the base frame. (When you do type a name, always type the name of the frame most directly containing the one you are defining. If you are defining frame C, which is contained by frame B, which is in turn contained by frame A, answer "Contained by" with "B".)
Note: Once you have specified that a frame is contained by another and you have finished defining it, you cannot change the "Contained by" value. If you find that you must change it, you will have to remove the frame and add a new one with the new "Contained by" value.
You also specify the number of times the frame should appear on the page (or, if the frame is within another subordinate frame, the number of times the frame should appear within it) and the size in rows of each occurrence. Remember that each occurrence of the frame will be placed below the preceding one, so be sure that you have enough space in the 17 rows of the screen to fit all the occurrences. Of course, neither number may exceed 17.
If the frame represents a structure, you identify the structure on this page. You can specify the occurrence numbers of the occurrences as well, counting from 1 (one) for the first occurrence. This capability is important for screens that handle "extra" occurrences of structures from other screens. For example, if we wanted to create a second screen to handle records with more than 5 donations, we would specify that the second screen start with occurrence 6 of the structure.
If you change your mind about adding (or changing) the frame, you can issue the PREVIOUS command to return to the "Frames" page. [See 3.3.8.] However, Screen Definer will discard any work you have done on this frame already; but for safety, it will first warn you that it is going to do that.
Warning: As always, if you issue the CANCEL command, Screen Definer will discard all the work you have done on the entire screen since you issued the GET command, not just your current work on the frame.
When you have answered all the questions and are ready to paint the frame, issue the OK command.
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: ADD SCREEN 02/19/86 18:04| |Screen DONOR: DONATION Frame -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 we have painted the one row of the DONATION frame. You follow the same rules and use the same symbols that you used to paint the base-frame fields earlier. [See 3.3.2.]
You can place a "base-frame frame" (that is, a frame not within any others) anywhere on the screen, including on rows already containing base-frame fields. The painting of one subordinate frame defined within another is restricted to the containing frame, however -- the rest of the screen is protected.
When you are done painting the frame, issue the OK command to continue to the review page.
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: ADD SCREEN 02/19/86 18:05| |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 during subordinate-frame definition works just like it did for the base frame. [See 3.3.3.] However, note that the defined frame has been replicated on the screen 5 times, as requested on the Frame Information page.
You can issue the PREVIOUS command to return to the painting screen to make changes if you want, or to return even further back to the Subordinate Frame Information page if you want to change the number of occurrences of the frame.
If you like what you see, type OK to continue to the Elements and Variables pages again, where you name the elements and variables you have painted on the screen, if any. Again, these pages work just like their counterparts that handled screen-level fields. [See 3.3.4, 3.3.6.]
When you're finished with them, you will be returned to the Frames page.
On the Frames page, you will again decide whether to complete the work on your screen by issuing the SEND command or to make further changes to it by adding, modifying or removing frames:
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: ADD SCREEN 02/19/86 18:07| |Frames for GQ.JNK.BLDDONOR, screen DONOR -Record 1 of 1| |Type SEND at the bottom of the page to complete this Screen Definer record. | | OR | |Mark the task you want to do with an X and type OK at the bottom of the page: | | _ Add a new frame | | _ Modify an existing frame | | _ Remove an existing frame | | | | # Frame Name Structure Name Frame Size | | 1 <Base Frame> 17 | | 2 DONATION DONATION 1 | | | | | | | | | | | | | | | |-DONATION frame completed | |Type OK below to continue to next page. Type CANCEL to cancel transaction. | |Type SEND to complete this transaction. Type UNDO to discard changes to page. | |YOUR RESPONSE: send | |f1=Help f5=OK f6=Send f7=Undo f8=Cancel f9=Options| +-------------------------------------------------------------------------------+
In this particular case, we are finished with the screen definition, so we issue the SEND command. Otherwise, we would choose the appropriate task and continue. Note that we are now offered the choice of removing a frame, now that there is a subordinate frame that can be removed. [See 3.3.8.]
If you choose to modify or remove a frame, Screen Definer will ask you to choose a frame from the list of frames shown. Remember that you cannot remove the "<Base Frame>", though you can modify it, removing all the fields from it on the painting page.
You can modify or remove only one frame at a time; however, if you choose to remove a subordinate frame that contains other frames, you will in effect remove all those screens at once. Screen Definer will always ask you to verify that you chose the correct frame to remove, marking the frames on the list that will be removed with it.
If you modify a frame, Screen Definer will take you through the same cycle of pages you went through to add the frame, letting you make changes as desired.
When you have issued the SEND command to complete the transaction, you are all done with the ADD SCREEN entry form. You can continue by adding another screen if you want by issuing the GET command again. Alternatively, you can use another entry form to modify or remove the screen you just added (MOD SCREEN) or to generate a format definition from the Screen Definer record (GENERATE). Your choices are described on the screen after the successful conclusion of the transaction.
When you want to make changes to a screen definition or remove it from a Screen Definer record entirely, you use the MOD SCREEN entry form. You can change almost all the items you specified when you defined the screen with the ADD SCREEN form, with these exceptions:
- the ID of the screen
- the "Copy from" value
Note that there are ways to get the desired effect of changing those two items. [See 3.4.2.]
The procedure for using MOD SCREEN is almost identical to that of ADD SCREEN, as are most of the pages of the form. [See 3.3.] Remember to use the HELP command anytime you need more information.
Here is the procedure to follow:
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.
If the Screen Definer record you are using has only one screen, Screen Definer will take you right to the General Information screen. Otherwise, you will see something like this:
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: MOD SCREEN 02/20/86 20:59| |Screen Selection for record GQ.JNK.PRISM.DONORS -Record 5 of 5| |Type the number of the screen you want to modify and then type OK below: 1_ | | | | # Screen ID Screen Title | | 1 INPUT1 Input for General Information | | 2 INPUT2 Input for Family Member Information | | | | | | | | | | | | | | | | | | | | | | | | | |-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| +-------------------------------------------------------------------------------+
Note that this example is for a different Screen Definer record than most of the previous examples have used; that record had only a single screen, so this page of the MOD SCREEN form would not apply to it.
Each of the screens in the record is listed. Choose the one you want to modify by typing the appropriate number in the blank field at the top of the page, and then issue the OK command.
If you aren't sure which screen you want to modify or remove based on its name, feel free to choose the most likely one; then look at a few pages of the MOD SCREEN form, including a painting page, to see if it's the right one. Don't worry about choosing the wrong one -- no screen is actually changed or removed until you issue the SEND command, so if you see you've chosen the wrong screen, just issue the CANCEL command and start again.
Although all the other pages of the MOD SCREEN form are the same as their counterparts in the ADD SCREEN form, there are substantial differences between the General Information pages. [See 3.3.1.] Once again using the DONOR screen of the GQ.JNK.BLDDONOR Screen Definer record we've been working with, we see this page when we begin using the MOD SCREEN form:
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: MOD SCREEN 02/19/86 19:43| |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 Type 'R' to review this screen for removal: _ | | | | Screen Title: Blood Donor Input | | | | | | | | Is this screen for output only? No | | | | | | | |_______________________________________________________________________________| | | | | | | |-Form continues on the next page | |Type OK below to continue to next page. Type CANCEL to cancel transaction. | |Type SEND to complete this transaction. Type UNDO to discard changes to page. | |YOUR RESPONSE: ok | |f1=Help f5=OK f6=Send f7=Undo f8=Cancel f9=Options| +-------------------------------------------------------------------------------+
You can change the screen title, or you can change your mind about whether the screen is for display only. You cannot change the ID of the screen, however. [If you must change the screen ID, use ADD SCREEN to create a new screen with that name, and then use "Copy from" to make a copy of this screen. Then you can remove this screen with the MOD SCREEN entry form.]
If you named a screen as a source for the "Copy from" feature on the General Information page of the ADD SCREEN form, that information is shown here for your information. However, you cannot change it in this entry form. [See 3.4.] [If you want to change "Copy from", you are in effect completely changing the screen. Again, the solution is to use ADD SCREEN to create a new screen, requesting the desired "Copy from"; then remove the old one.]
To remove this screen from the current Screen Definer record, first type an "R" in the designated field on the page. Screen Definer will then display the screen on the Remove Screen page, asking you to verify that you want it removed. That page is described in the next section. [See 3.4.3.]
If you did not type an "R" in response to the removal prompt, the MOD SCREEN form continues with the Frames page. [See 3.4.4.]
If you typed an R" in the field on the General Information page indicating you might want to remove the screen from your Screen Definer record, then the next page of MOD SCREEN is the Remove Screen page. There Screen Definer shows you the painted screen, asking you to verify that you want to remove it.
The example below shows what the Remove Screen page would look like if we had marked the DONOR screen for removal on the General Information page:
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: MOD SCREEN 02/19/86 19:43| |Remove Screen DONOR from GQ.JNK.BLDDONOR -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) | | !! ................... !! ................................................ | | !! ................... !! ................................................ | | !! ................... !! ................................................ | | !! ................... !! ................................................ | | !! ................... !! ................................................ | |_______________________________________________________________________________| | Type YES to remove this screen: ___ | | | |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: | |f1=Help f4=Previous f6=Send f7=Undo f8=Cancel f9=Options| +-------------------------------------------------------------------------------+
Notice that the screen is not removed from the Screen Definer record unless you both type YES in response to the prompt and type SEND to complete the transaction. If you decide not to remove the screen, issue the CANCEL command to cancel the transaction completely. Alternatively, you can type PREVIOUS to return to the General Information page and make changes to the screen instead. [See 3.4.2.]
All other pages of the MOD SCREEN entry form are identical to the pages bearing the same names in the ADD SCREEN entry form. In order of appearance, they are:
- Frames, where you choose to add, modify or remove a frame, or to complete the transaction by issuing the SEND command. [See 3.3.8.]
- Frame Information, where you add, review or change information about a frame, including its name, its size in rows, its number of occurrences on the screen, the name of the structure it represents, and the occurrence number of the structure. [See 3.3.9.]
- Painting, where you add, review or change the fields on the screen, using the screen-painting symbols. Remember, you can issue the HELP command to see a list of the symbols from that page of the entry form. [See 3.3.2.]
- Review, where you review the screen painted on the previous page. [See 3.3.3.]
- Elements, where you name or revise the elements painted on the screen. [See 3.3.4.]
- Element Review, where you review or revise such things as the display attributes, occurrence number, edit mask or value adjustment for individual elements painted on the screen. [See 3.3.5.]
- Variables, where you name or revise the variables painted on the screen. [See 3.3.6.]
- Variable Review, where you review or revise such things as the display attributes, edit mask or value adjustment for individual variables you painted on the screen. [See 3.3.7.]
As always, to complete your work, you issue the SEND command, which is available on the Frames page. If you want to cancel the entire transaction without making any changes to the screen, issue the CANCEL command at any point.
Remember too that if you begin work on a frame and decide you do not want to make any changes but neither do you want to cancel all the work you've done on the screen since the last GET command was issued, you can use the PREVIOUS command to back out of the cycle of work on that frame.
When you have issued the SEND command to complete the transaction, you are done with the MOD SCREEN entry form. You can continue by modifying other screens (or the same one again) by issuing the GET command again. Alternatively, you can use another entry form to do other work, such as the GENERATE form to generate your format definitions. The most common choices are described on the screen after the successful completion of the transaction.
When you are ready to generate the format definition(s) and vgroup definition (if you defined any variables) from your Screen Definer record, you use the GENERATE entry form.
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 generate formats code from 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 GENERATE entry form:
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: GENERATE 02/19/85 20:50| |Format Generation -Record 1 of 1| |This entry form creates a SPIRES format definition from the Screen Definer | | record GQ.JNK.BLDDONOR, for subfile PRISM BLDDONOR. | | | | FORMATS record key: GQ.JNK.BLDDONOR________ | | Name the input format to be created: PRISM ENTRY__________ | | | | | | | | | | | | | | | | | | | | | | | | | | | |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: send | |f1=Help f6=Send f7=Undo f8=Cancel f9=Options| +-------------------------------------------------------------------------------+
Screen Definer asks you to confirm or change the format definition key (the value of its ID statement), which by default is the same name as the Screen Definer record. You can change it by typing over it with another value, which must begin with your own account number. It may not contain any blanks.
Note: There are two situations when Screen Definer can create multiple format definitions from a single record:
1) If you have painted any phantom elements on the screen, those elements will be handled by load-format definitions called by the main format definition; the default format IDs will be the same as the default format ID for the main format definition, with the additional suffix ".PH1", ".PH2", etc.
2) Depending on a combination of the number of screens in one record and their complexity, Screen Definer may create one or more load formats to hold some of the code for some of the screens; it does that to prevent format definitions from getting too large. The default format IDs will be the same as the default format ID for the main format definition, with the additional suffix ".LD1", ".LD2", etc.
In either case, all the format IDs are listed here on the Format Generation screen, and you can change them as you like. They will appear again on the confirmation screen for this entry form, at which point you should write them down.
You are also asked to supply a format name (the value used by a SET FORMAT command). The name may be from 1 to 16 alphanumeric characters; in addition, the special characters period, underscore and hyphen are allowed, as are internal blanks.
If you defined any user variables as you painted the screens of this record, Screen Definer will also ask you for the ID of the vgroup definition it will create for them. Like the format definition key, the vgroup definition's default key will be the same name as the Screen Definer record. You can change it by typing over it with another value, which must begin with your own account number, and may not contain blanks.
When you have completed filling out the page, issue the SEND command; Screen Definer will create the format definitions and try adding them to the FORMATS subfile in SPIRES. If any records with those keys already exist in the subfile for your account, Screen Definer will ask if you want to replace them with the new definitions. (The warning error WF will appear next to the names of those records.) If you do want to replace the existing records, just type SEND again as directed; otherwise, type new names in the format-ID fields and type SEND again. Screen Definer will follow the same procedure for the vgroup definition it creates.
Screen Definer tells you when it has successfully added the records to the SPIRES system subfiles. You are then all set to compile the definitions in SPIRES. [See 4.]
When you want to remove an entire record from Screen Definer, you use the GENERATE entry form. [Use the MOD SCREEN entry form to remove individual screens from a record. [See 3.4.]]
WARNING: Removing a Screen Definer record is a very serious step, in that you cannot "undo" the process. Make absolutely sure that the record you are removing is one you no longer need and is the one you want removed.
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 generate formats code from 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 REM RECORD entry form:
+-------------------------------------------------------------------------------+ |Screen Definer Entry Form: REM RECORD 03/02/86 13:00| |Remove Screen Definer Record GQ.JNK.BLDDONOR -Record 1 of 1| | Record: GQ.JNK.BLDDONOR | | for subfile: PRISM BLDDONOR | | (file GQ.JNK.BLOOD.DONORS, record-type REC01) | | Date created: Wednesday, February 19, 1986 | |Date modified: Wednesday, February 19, 1986 | | | |Screen Name_ Title___________________________ | |DONOR Blood Donor Input | | | | | | | | | | | | | | | |_______________________________________________________________________________| | Type YES to remove this Screen Definer Record: ___ | |_______________________________________________________________________________| |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| +-------------------------------------------------------------------------------+
To remove the record you must both type YES after the prompt and issue the SEND command. If you decide not to remove the record, issue the CANCEL command to cancel the transaction.
Again, be extremely cautious when using this form. Once a Screen Definer record has been removed, it is gone, and you cannot recover it.
This is the easiest part of the Screen Definer procedure. After leaving Prism (by issuing the END command), you compile the vgroup definition (if one was created) and the format definition(s) in SPIRES, following the procedure outlined below:
This command invokes the SPIRES program.
You must first compile the vgroup definition that Screen Definer wrote for you if you defined user variables on any screens. To do so, you select the VGROUPS subfile and issue the COMPILE command, identifying the vgroup definition by its ID.
When that compiles, you can compile the format definition(s):
Issue the COMPILE command, identifying the format definition by its ID, named when you generated the format with the GENERATE entry form.
You should receive the message "-Format Definition Compiled". If you do not, i.e., if you receive error messages, you should contact your SPIRES consultant as soon as possible.
If you are replacing a format that already exists, you can replace the COMPILE command with the RECOMPILE command. (If you use the COMPILE command instead, SPIRES will tell you that the compiled version of the format already exists, and ask you if it is "OK to replace?")
Issue the COMPILE command for each of the format definitions Screen Definer made for you. The order in which they are compiled is unimportant.
If you have designed your screens for an entry form of a Prism application, you need to announce the new addition in the application's profile record in Prism Profile. In Prism:
- 1) Select the Prism Profile file.
- 2) Issue the ENTRY command to establish the MOD FORMS entry form.
- 3) Issue the FIND command to find the appropriate profile record.
- 4) Issue the GET command and fill out the form.
MOD FORMS asks you:
- to name the form;
- to specify its purpose, which will appear on the entry form menu;
- to name the format to be set for the form (which is the format name you verified or changed in the GENERATE entry form of Screen Definer);
- to name the transaction for which the form can be used (i.e., adding, updating, both);
- to name the screens of the format in the order in which they are to be presented to the user (these are called "screen processing steps" in MOD FORMS);
- to choose "patron options" for each screen, such as the commands that Prism should enable for the user when this screen is displayed, such as SEND or PREVIOUS.
Complete details on filling out MOD FORMS (and about entry forms in general) can be found in Chapter 10 of the "Prism Applications" manual.
Connecting screens to a SPIRES file is much more complicated than it is in Prism. Please see Chapter 5, "Full Screen Programming", of the SPIRES manual "Device Services" for instructions.
It is quite possible that you will want to make changes to the format definition Screen Definer has created for you, especially in the first versions of Screen Definer, which do not have all the sophisticated features planned for it. [See 6.] For example, if you need to work with user variables inside the format, you will need to add Uprocs to the frame definitions as appropriate. [On the other hand, you may easily work with the variables outside of the format, say, in a protocol step between screen steps in a Prism application.]
Of course, it is important to remember that any changes you make to the code will not be reflected in the Screen Definer record. If you ever return to Screen Definer to make some changes to it that Screen Definer can handle, you will need to reincorporate your "handmade" revisions as appropriate after generating new format and (possibly) vgroup definitions.
Screen Definer is an evolving tool, whose ongoing development will produce more features and fewer limits. This section lists the current limitations we are aware of, indicating those that we expect will change as development continues, which are preceded by "(*)".
- (*) You can put only 14 screens in one Screen Definer record.
- (*) A screen design can be only 17 rows high, regardless of the size of the terminal you're using.
- (*) A screen design can be only 79 columns wide, even if the terminal can handle larger widths.
- (*) No box-drawing support is available, other than characters you can type already, such as underscores (_) and vertical bars (|).
- (*) Though you can copy a screen from another Screen Definer record of your own, you cannot yet tie it to the other record (with the "Defined-by" option) so that changes to the original will affect the copy.
- (*) A screen that will be used for multiple records (such as a screen for the Prism BRIEF display) cannot have a separate header frame at the top (i.e., you cannot yet use Screen Definer to create the BRIEF.HDR frame).
- (*) There is not yet a way to allow an indefinite number of occurrences of a structure, element or variable, for either output or input.
- (*) You cannot yet specify a relative position of fields for output based on the ending position of values in other fields.
- (*) There is not yet a way to allow fields scattered around the screen to be grouped for editing purposes (e.g., to insure that if the user enters a value in one field, no value is entered in another).
- (*) A screen may contain only 10 frames, including the base frame.
- Subordinate frames may be nested to 6 levels deep.
- A frame may contain up to 40 different elements, with a total of 50 additional occurrences of them and a total of 50 continuation fields for them.
- A frame may contain up to 40 different variables, with a total of 50 additional occurrences of them and a total of 50 continuation fields for them.
- For each of the three field types Error, Text and Title, all fields of that type on all screens of the record will have the same display attributes. (In other words, one error field can't be, say, a different color than another in the same Screen Definer record.)
- Element fields cannot handle dynamic elements.
- (*) In a later version of Screen Definer, you will be able to specify for an element:
- local Uproc processing
- VALUE statement processing for output
- (*) In a later version of Screen Definer, you will be able to see a list of elements in the subfile.
- (*) In a later version of Screen Definer, you will be able to specify for a variable:
- specific occurrence number of the variable if it is in an array
- a default value for the field
- a name for the variable's subscript variable
- (*) System variables painted on a screen cannot be unprotected.
- Titles cannot begin in column 1 of the screen because they must be preceded by the "%" character.
- Multiple occurrences of element or variable fields that are specified with the "=" screen-painting character must all be the same length as the first occurrence.
- A field that is a continuation of a field in the previous row (specified with the "+" screen-painting character) must be the same length as its parent and must begin in the same column as its parent.
- Text fields may not contain the "{" or "}" characters as part of the
text.