******************************************************************
* *
* 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) is a trademark of Stanford University.
Document #763
This document matches the version of Prism released to production on August 13, 1994.
Changes in this release:
- PERFORM PRISM SUFIN AUTHORITY is replaced by PERFORM PRISM SERVICE SUFIN GETAUTH. [See 15.]
- New HELP option for SET FTRACE allows tracing of format frames used to generate help text. [See 7.4.3.]
- Prism no longer executes the header specified on a $FRAME-generated help at the start of the help. Instead, the header is executed whenever the help display enters screen overflow processing. As for FULL display headers, you can cause the header frame to execute if you want the header information on the first page of the help. [See 6.3.9.]
- The new command PERFORM PRISM HELP <help-term> may be used in a Prism protocol to simulate the user's typing HELP <help-term> at the command line. [See 6.8 (if you want to read this same explanation again).]
The following features for end-users were added to Prism 8/13/94.
- Personal Fields are now available in all Prism files. Personal Fields have been available since July 1993 in financial transaction files in Prism. With the August release of Prism, Personal Fields may be created in any Prism file. New commands associated with Personal Fields are SETUP FIELDS (to define Personal Fields) and TAG (to enter Personal Field values for specific records).
- A new DROP command lets you remove specific records from a search result, as an alternative to composing search commands to refine a search result.
- A new SETUP SEARCH option lets you save a specific search result (a specific set of records) as an alternative to saving a set of search commands to be re-issued later.
- Within a specific time limit in one Prism session (currently set at 1 hour), you will only be prompted for a PIN the first time. This change was made in response to requests from TIPS, in order to reduce seemingly redundant PIN prompts within a Prism session.
This document explains how to transform a SPIRES subfile into a Prism application, and install it in Prism, the online collection of Stanford administrative files and services.
You don't need advanced knowledge of SPIRES to install a basic Prism application -- the introductory SPIRES documents named later in this chapter provide all the background you need for the basic tasks covered in the beginning chapters of the document. A wider knowledge of SPIRES is needed for the more complex enhancements described later in the document.
As for Prism itself, you can begin exploring the applications already installed by typing the command PRISM and then selecting a file for searching. See also the short handout "Introduction to Prism", available through the PUBLISH command in WYLBUR.
For the Stanford community, Prism acts as a central collection of administrative files and services, with a single unified interface and command language. Prism includes extensive online help and instructions, to make it easy to learn how to do searching, data entry, and reporting. Once you learn how to use one Prism application, it is very easy to learn how to use another one, because of the shared command syntax and interface.
In addition, for you as an application developer, Prism is a powerful tool for implementing, testing, and delivering a full screen application in a very short time. You can save time you would have spent working on a user-interface (command language, helps, protocols, documentation), since Prism already provides much of this for you.
The simplified chart below gives a general idea of the structure of a Prism session. In this chart the end-user enters from the top and progresses downward as his or her Prism session continues.
Not every Prism application has every feature shown on the chart -- some applications don't need reporting or data entry -- but every application conforms to the model in a general way.
WELCOME TO PRISM
|
|
Select a file or
service
|
- - - - - - - - - - | - - - - - - - - - -
|
Welcome to
the file
/ | \
SEARCH |REPORT ENTRY
/ | \
Pick a search Pick a report Pick an
entry task
| | |
| | |
DISPLAY or DISPLAY REPORT CREATE
PRINT or PRINT or GET
Note that Prism takes care of everything for you above the horizontal dotted line; and Prism takes care of many of the details below the dotted line as well.
Every Prism application at minimum provides for searching data and displaying it, in BRIEF and FULL form. Many Prism files offer reporting and data entry as well as searching. To support this minimum activity, the following steps are required:
If your Prism application will support reporting or data entry as well as searching, you'll need to take these additional steps:
"Installing" an application in Prism means giving Prism a complete description of the application: for instance, telling Prism the name of the SPIRES subfile supporting the application, telling who will be responsible for maintaining the application, and so on. We call this full description a "File Profile".
The Prism Profile application in Prism is designed expressly for the purpose of helping you install your own application. In general, to add or modify a feature of your application, you use one of the entry forms in Prism Profile. Some of the tasks involved in installing or modifying your application may also be done from within your application, with the XSETUP command. Prism Profile and the XSETUP command will be discussed in detail in many chapters of this document.
Although the standard Prism interface can pretty much run your application for you, at some points you may want to customize your application to meet differing end-user responses and needs. To cover these special situations, Prism lets you code and install processing steps which invoke SPIRES formats and protocols code of your own. Your processing steps take over the flow of control from Prism for a short time and alter the environment to your application's particular needs. These steps are optional (except for entry forms). [See 9.]
For developers who want to customize their application even further, Prism offers several different ways to take over temporary control of some important processes such as data entry [See 12.] and searching [See 13.] The material in these late chapters is optional and requires a fairly advanced knowledge of SPIRES programming techniques. But the added power can be worth the complexity. You can probably skim chapters those chapters to see if the capabilities offered there would be useful to you.
Some Prism applications are used for online routing of University forms (such as SUFIN Journals and SNAP Purchase Requisitions). If you will be creating a routing application, you will need another document in addition to this one, called "How to Install a Routing Application in Prism". To print a copy, use the PUBLISH command.
The chart below suggests the SPIRES background you will need for different tasks in Prism. Creating a simple Prism application requires only basic SPIRES knowledge. Even for data entry, you can take advantage of the Prism application Screen Definer, and bypass most of the SPIRES formats language. The more complex tasks require more advanced knowledge of SPIRES.
Task in Prism________________ Useful SPIRES Reading__________
Creating and modifying a Guide to Data Base Development
SPIRES subfile for Prism and File Definer
Writing a display format Guide to Output Formats
Installing an application *
Adding help records *
Debugging the application *
Modifying your file profile *
* no SPIRES documentation needed
-----------------------------------------------------------------
Adding processing steps SPIRES Protocols and
SPIRES Formats
Creating simple reports Searching and Updating
Creating complex reports SPIRES Formats
Creating a basic entry form Screen Definer
Supporting complex data entry SPIRES Protocols, SPIRES Formats
SPIRES Device Services
Supporting complex searching SPIRES Protocols, Global FOR
Creating a routing application How to Install a Routing
Application in Prism
All of the documents listed above are available through the PUBLISH command (except for the routing applications document). You can also use the EXPLAIN command online in SPIRES for an explanation of any SPIRES term used in this document.
The first step in coding an application for Prism is to modify your application's file definition in SPIRES. Here are the changes you will probably need to make:
The first two tasks are covered in this chapter. The chapters covering entry forms include an explanation of how to define error codes. [See 11.3.2a.]
If you are not yet familiar with file definition in SPIRES, you should look at the manual "File Definer" (or for detailed information the "SPIRES File Definition" manual) in conjunction with this chapter. For an introductory look at how to define a SPIRES data base, see the manual "A Guide to Data Base Development".
Add to your file definition a subfile section in this form:
SUBFILE-NAME = PRISM File-id;
GOAL-RECORD = REC01;
ACCOUNTS = PUBLIC; <---- Determines who can select the subfile.
PROGRAM = PRISM; <---- Ensures that the subfile can only
be selected in Prism.
"File-id" (also known as "Prism-id") is a name of up to 16 characters uniquely identifying your file. No two files in Prism can have the same file-id, since it is the unique internal identifier that Prism uses to drive each application. (To see a list of file-ids in use, select the SPIRES subfile PRISM PROFILE and issue the command BROWSE FIRST FILEID.)
If you are creating your file definition using File Definer, the following line has the same effect as the statements shown above:
SUBFILE Prism <file-id>/ ACCOUNT Public/ PROGRAM Prism
In the line above, you would replace <file-id> with the particular file-id (16 characters or less) that you have chosen for your Prism application.
The file-id described above is an internal name for your and Prism's benefit. You will see it mentioned again and again in this document, because it is the unique identifying mark that ties together the different parts of your application in Prism.
But note that the people using your file will never see the file-id. What they will see is an "external" name of your application as you install it in Prism Profile. [See 4.] So it doesn't matter if the file-id is cryptic, as long as it is unique within Prism.
You may type SELECT followed by the at-sign (@) and the file-id as a shortcut for selecting your file in Prism (for example SELECT @PFUND.DIR, for an application with file-id of PFUND.DIR). This feature is not documented as something that end-users would be likely to need, but as an application developer familiar with the file-id you might find this a useful abbreviated way to select your file.
In the ACCOUNTS statement, specify which accounts (or groups or access lists) should have access to the subfile via Prism. Access to the subfile in Prism is also controlled by your application's file profile. Any account given access in Prism Profile must also be given access in the ACCOUNTS statement in the file definition.
It is usually most convenient to use ACCOUNTS = PUBLIC in your Prism subfile section, and then use the profile to control access in Prism. As you will see in later chapters, you have a lot of flexibility within your file profile in how you give access to your Prism application. For example, you may name access lists as well as individual accounts or account groups when you install your application in Prism Profile. [See 4.]
In addition, Prism lets you specify a subset of users for each activity in Prism. For instance, you can allow public access to your file for search and display, while allowing only a smaller group of people to use data entry or reporting.
If your profile gives an account access to your Prism application, but the account is not also listed in the Prism subfile section of your file definition, the person trying to select the file in Prism will get a "File not currently available" message.
The profile determines which accounts see an application listed on the SELECT menu in Prism. But the SPIRES subfile section makes the final determination about who can actually select the file in Prism. [See 8.5 for information about temporarily disabling a Prism file.]
The PROGRAM = PRISM statement in the subfile section ensures that this subfile will be accessible only through Prism. You are free to provide access via SPIRES too, of course. To do so, include another subfile section in your file definition, omitting the PROGRAM = PRISM statement.
Except for the form of the subfile-name the new subfile declaration has no special requirements peculiar to Prism, but some of the conventional ways of coding a subfile section in SPIRES don't apply to the Prism environment, and should generally be avoided there:
You can create a particular view (or views) of your Prism file with appropriate use of CONSTRAINT and search modifiers in your SPIRES file definition, but many statements (such as WHERE-MODS) that you commonly use to regulate SPIRES applications may turn out to be irrelevant or superfluous in Prism -- that is, Prism provides the same function in radically different ways.
Do not include a FORMATS statement of any kind in your subfile section, not even one that sets your Prism display format. Prism's own code will set display formats for each application, using paths when necessary to keep the system-wide environment stable.
Be wary of including SELECT-COMMANDS in your definition: they may interfere seriously with the Prism environment. You can virtually always code a protocol processing step at file-selection, to accomplish the same functions in Prism that SELECT-COMMAND statements accomplish in SPIRES. [See 3, 9 for more on file-selection protocol steps.]
In general, every Prism search type (index) corresponds to an index in your SPIRES file definition. [See 13 to learn about exceptions, in which protocol steps are associated with search types.] When you install a search type in your file profile, you must specify the corresponding SPIRES search term. If you want the name of the Prism search type to be different from the SPIRES search term, you must also supply that additional "external" name.
The indexes used with Prism's FIND command are also referred to as "search types". You will see both "index" and "search type" in messages and help screens, although the trend has been toward preferring the simpler term "index".
When you install a Prism index in your file profile, you have the opportunity to name the particular accounts or access lists allowed to use it. This type of security is done completely within Prism Profile (the ADD PROFILE or MOD INDEXES entry form) and does not require any modifications to your file definition.
Depending on the requirements of your application, you may need to make these modifications to your index definitions:
- You may wish to code some or all of the SPIRES indexes you install in Prism as "immediate" indexes, so end-users need not wait for overnight processing to search records by their updated values. (See below for more on immediate indexes, including a note on efficiency considerations.)
- If an index contains coded values, you may want to use SPIRES "indirect search" so end-users don't have to know the codes in order to search with the index. (Note: since indirect searching uses significantly more resources than regular searching, you'll need to weigh its ease-of-use benefits against the disadvantage in efficiency.)
- If you want to create "value-supplied" search types in your application, you might use the $REPARSE Proc in your index definitions to accomplish the search. [See 2.4.]
The "File Definer" and "SPIRES File Definition" manuals have more information on each of these topics.
If your application is updated on a daily basis, it will probably be worthwhile to make at least one of the indexes you install in Prism an immediate index. (Immediate indexing allows your end-users to retrieve newly-updated records by the changed criteria. Without it, the index does not get updated until the SPIRES file is processed, usually much later in the same day.) If your Prism application supports data entry, immediate indexing can be especially valuable, because end-users may want to search for a record they have just entered.
You should note that immediate indexes are somewhat more expensive than ordinary ones. Perhaps more significant, too many immediate indexes can adversely affect the efficiency of your application's use of system resources, by causing a high number of "I/O's" or input/output transactions to take place. In previous versions of this document we recommended you code all of your indexes to be "immediate", but today it may make better sense to pick and choose which indexes most need the feature.
One good alternative: you can choose perhaps two or three Prism search types to provide same-day access. Good candidates might be the record key (coded in SPIRES as a goal-index record-type) or some other logical value such as an order number. Your end-users can probably help you decide which indexes need to be "immediate" and which can do without.
The names of Prism indexes may be up to 8 characters long. The name must be a single word (no blanks), and should be as brief and self-explanatory as possible.
Whenever possible, an index that falls into a common category such as "department" will benefit from having the same standardized name across all Prism applications, so that end-users moving from one file to another will recognize the index in the new file. For instance, NAME is recommended for any personal-name index and DEPT for any university department index.
Some other candidates for standardization: PHONE for phone number; ACCT for a University fund account; SSN for a Social Security number, and MAILID or EMAIL for an electronic mail account.
Avoid abbreviations unless they are widely recognized, and avoid embedded characters such as periods in index names. As for the different values prompted for and recognized by the search type, indirect search as mentioned earlier can help translate these into familiar terms.
Prism currently accommodates 12 indexes without strain on the FIND menu on a standard-sized monitor. Even fewer than 12 (say, about 7) would be optimum for a "public" view of the file, since the search menu needs to be simple enough for novice users. Still, if you need to, Prism lets you install up to 64 indexes.
This section discusses a special (and powerful) Prism index that supplies its own search value whenever an end-user chooses it from a menu. Since a "value-supplied" index in Prism usually involves file definition modifications, we are covering it here. But you may prefer to skip this section for now and return to it later, when you enhance your basic application.
In most Prism searches, selecting an index is only the first step in performing the search. Just as with index searching in SPIRES, the end-user must also name a search value to complete the search request. I.e., in any search of the NAME index pictured below, the search would not be complete until a value (such as "Sarah Kent") had been specified:
TYPE OF SEARCH DESCRIPTION EXAMPLE NAME Personal name Sarah Kent DEPT Department Biology BIOMAJOR All Biology majors --
But you can also code and install a special "value-supplied" index that supplies its own value for the search and thus does not have to take the extra step of prompting the end-user for a value.
For example, the BIOMAJOR index shown above is a value-supplied index that performs an unprompted, behind the scenes search to retrieve all students who are majoring in Biology. All the end-user would have to do is type FIND BIOMAJOR (or answer the FIND prompt with BIOMAJOR); Prism and/or your code would do the rest.
Perhaps the best method for coding a value-supplied index would be to create a sort of "virtual index" to support it in your file definition, using Userprocs and/or the System Proc $REPARSE. For example, in the simple example above, the file definition might reparse the Prism search request FIND BIOMAJOR to become the index search FIND MAJOR BIOLOGY. The end-user would never have to be aware of this reparsing. (See the SPIRES explanation of the $REPARSE PROC for further explanation of how reparsing works.)
Another alternative is to code a protocol step for the value-supplied index, in which you supply the appropriate search value. [See 13.] This method would not require modifications to the SPIRES file definition.
Whichever way you code the value-supplied index, you must tell Prism not to prompt the user for a value. To do so, answer "Yes" to the following question asked for each index in ADD PROFILE:
Enter 'Yes' if search type supplies its own search value: ___
Some of the information that is required for other indexes (such as a prompt and sample value) becomes superfluous for a value-supplied index [See 4 for information on installing your file, including installing indexes.]
This chapter covers the display format that every Prism application must have in order to display records assembled in a Prism search. The display format covers the leftmost branch of the chart shown in the Introduction:
WELCOME TO PRISM
|
|
Select a file or
service
|
|
Welcome to
the file
/ | \
SEARCH (REPORT) (ENTRY)
/ | \
Pick a search
|
|
DISPLAY or <--- Your display format
PRINT is used here
Your displays are used not only when users search for records and display them, but also within data entry transactions. During update transactions, the DISPLAY command is available if the user wants to look at the record in a layout other than that of the entry screen.
The introductory manual "A Guide to Output Formats" explains most of the techniques you will need to create a SPIRES display format for use in your Prism application. Complete documentation for the formats language is in the manual "SPIRES Formats".
The FORMAT-NAME in your SPIRES display format is declared when you install your application in Prism Profile. There are no strict requirements for the name, and your application's users will never see this name. The recommended name is "<file-id> DISPLAY" where "file-id" is your application's unique file-id. Since the format-name must be 16 characters or less, you may prefer to use PRISM DISPLAY or some other name.
Your display format should contain at least two data frames, one named BRIEF and one named FULL. In the frame definitions, include DIRECTION = OUTPUT and USAGE = DISPLAY, NAMED statements. Below is a skeleton diagram of the format:
FRAME-ID = BRIEF;
DIRECTION = OUTPUT;
USAGE = DISPLAY, NAMED;
:
:
FRAME-ID = FULL;
DIRECTION = OUTPUT;
USAGE = DISPLAY, NAMED;
:
:
FORMAT-NAME = <file-id> DISPLAY; <--(or PRISM DISPLAY)
:
:
FRAME-NAME = BRIEF;
FRAME-TYPE = DATA;
FRAME-NAME = FULL;
FRAME-TYPE = DATA;
All frames of your Prism display formats should include USAGE = NAMED so that if you use the SPIRES command to break out of Prism temporarily for debugging purposes and issue the DISPLAY * command, you will see the record in native SPIRES format. DISPLAY * uses data frames of the current format unless USAGE = NAMED for those frames. [See 7.5 for information about the SPIRES command.]
Most SPIRES data frames must include a FRAME-DIM statement. However, an important point about FRAME-DIM in your Prism display format is that it is ignored completely when the format is executing in Prism. Prism itself sets up the size of the area in which data is displayed and manages the way displays continue from one screen to the next. Your display format is invoked as a load-format within Prism.
The FRAME-DIM is used, however, when you use your display format in native SPIRES -- while you are developing and debugging it, for example.
For your BRIEF and FULL frames, it is most straightforward to use line-by-line processing, by coding FRAME-DIM = 0,79.
FRAME-ID = FULL; DIRECTION = OUTPUT; USAGE = DISPLAY, NAMED; FRAME-DIM = 0,79;
If you need to use fixed frame dimensions (because you want to reference an earlier row in the buffer, for example) a good choice is FRAME-DIM = 15,79. This frame dimension, along with the SET FLUSH Uproc, simulates in SPIRES fairly closely the action of your display format while executing in Prism and mimics the environment in which your format must work.
FRAME-ID = FULL;
DIRECTION = OUTPUT;
USAGE = DISPLAY, NAMED;
FRAME-DIM = 15,79;
:
FRAME-NAME = FULL;
FRAME-TYPE = DATA;
UPROC = SET FLUSH;
[See B.3.3 in "SPIRES Formats" for details about the FRAME-DIM statement.]
Your display format must be prepared for the buffer to be flushed after line 15, since a standard 24-line screen in Guided Mode has an area 15 rows by 79 columns in which to display data. That is, you will not (for example) be able to place a value in row 20 of the display and then go back to put something in row 5, because in many cases row 5 will have already been sent to the terminal screen by the time you get to row 20 in your format.
In Command Mode, 19 lines are available on a standard screen to display data, and even more lines might be available if the user has a larger display monitor. But your format should accommodate the smallest display area -- 15 lines. Prism automatically sets up the display area with a dimension to accommodate the user's screen, whether it is 15 lines in Guided Mode, 19 lines in Command Mode, or some other number.
The BRIEF display is intended to be a multi-record display, so the information shown for any individual record must be concise. The BRIEF display can be thought of as a menu of numbered records featuring only the most essential information from each record. Most BRIEF displays use an average of 1-4 lines per record, which allows each screen to show from 3 to 19 records at a time on a standard size terminal screen.
If you wish, you may provide a header for your BRIEF display. This can be a handy way of labeling record values only once per screen -- saving the rest of the space for the record values themselves.
Here are two sample BRIEF displays, one without headers and one with them. Clearly, if you don't use headers above your record display, you must take care to label potentially ambiguous fields (such as "Phone" below) within the display.
Here is a sample BRIEF display without headers:
__________________________________________________________
1) Smith, Marlon P. Phone: 019-1344
Sci/Eng Laboratory
Kol-Koz Building
2) Smith, Mellita J. Phone: 014-3566
Sci/Fi Laboratory
Trullion
3) Smith, Travis T. Phone: 098-7654
English Department
Old Quad
(etc.)
__________________________________________________________
This sample BRIEF display has a header. The header will appear at the top of each screen of the display.
__________________________________________________________
I.D. Status Title Department
1) 12345 OPEN Data Aide/Trainee Vicarage
2) 23456 FULL Data Aide Deanery
3) 34567 FULL Data Aide/Trainee Parsonage
4) 45678 OPEN Data Aide Exchequer
(etc.)
__________________________________________________________
Here is a partial outline of formats code for a BRIEF frame:
FRAME-ID = BRIEF;
DIRECTION = OUTPUT;
FRAME-DIM = 0,79;
USAGE = DISPLAY, NAMED;
:
FRAME-NAME = BRIEF;
FRAME-TYPE = DATA;
An important part of the BRIEF display is the sequential numbering of the records appearing there. Your application's users will type this number in their DISPLAY FULL (or GET or PRINT) commands to tell Prism specific records they are interested in.
Prism uses the SPIRES system variable $RECNO (alias $RECNUM) to keep track of each record's position in the search result. The BRIEF frame must include this value as part of each record's display. Here is a sample label group to accomplish this task:
LABEL; VALUE = $RECNO || ')'; START = 1,1; PUTDATA;
The record-number followed by a right-parenthesis appears on the left side of the display followed by the first data value, with a single space separating the data value from the number. Data values on subsequent rows should probably be indented from column one to highlight the numbered row. Be careful not to let $RECNO values and your data overlap each other when the value of $RECNO becomes large (say, if a search retrieves a large number of records).
Note that Prism does not separate records on the BRIEF display by a blank line. If you want the blank line, you should place data into your BRIEF frame starting on the second row.
If you want to provide a header for your BRIEF display, include an XEQ frame called BRIEF.HDR in your display format. (An XEQ frame is a special type of format frame that does not process data base records.)
Here is a sample outline of a BRIEF.HDR frame:
FRAME-ID = BRIEF.HDR;
DIRECTION = OUTPUT;
FRAME-DIM = 0,79;
USAGE = DISPLAY, NAMED;
:
LABEL;
VALUE = 'I.D.';
START = 1,6;
DISPLAY = UND;
PUTDATA;
<etc.>
:
FRAME-NAME = BRIEF.HDR;
FRAME-TYPE = XEQ;
[See D.2 in "SPIRES Formats" for details about XEQ frames.]
Every Prism file must provide a FULL display. In general, FULL displays should show all the data from a record that users of the application are allowed to see. Since the FULL display of a single record might span more than one screen, you should label the elements in the display clearly, so that even first-time users know what they are seeing.
Note that you can create additional displays besides BRIEF and FULL, to serve special purposes or meet particular needs of your users. [See 3.4.]
Your FULL display must be coded in the same format as your BRIEF display. [See 3.2.] Write a data frame called FULL:
FRAME-ID = FULL;
DIRECTION = OUTPUT;
USAGE = DISPLAY, NAMED;
FRAME-DIM = 0,79;
:
FRAME-NAME = FULL;
FRAME-TYPE = DATA;
Using line-by-line processing (FRAME-DIM = 0,79) is most straightforward, but it is also possible to use fixed frame dimensions. [See 3.1 for detailed guidance about FRAME-DIM in your Prism display format.]
Prism precedes each FULL display with the number that the record had in its BRIEF display (its position in the search result). This number is supplied by the system in the status area at the top of the screen; you do not need to incorporate $RECNO into your FULL frame as you do with the BRIEF frame.
In most cases the FULL display will begin at the very top of the data portion of the screen, i.e., with no blank line preceding it. So you should begin positioning your FULL data on the first row of your frame. Prism does insert blank lines between any records that are displayed FULL together on the same screen -- a situation that might come up if an end-user asked for a range of records to be displayed FULL.
If you are certain that you always want each FULL record to begin on a new screen, then enter a value of "0" (zero) for this question when you install your display:
Enter minimum lines required for full displays: __
(This question appears in all the places where you can install displays: the ADD PROFILE and MOD DISPLAYS entry forms in Prism Profile, and the XSETUP DISPLAYS command.) [See 4.1.4.]
You can provide a header for your FULL displays. Unlike a BRIEF header, which is used to provide a constant heading for all the records in a BRIEF display, the FULL header is used to repeat important identifying information for a single record, when that record's FULL display is longer than a single screen. Prism invokes the FULL header on the second and following screens (not the first screen) of a record's FULL display. Thus information in the FULL header relates to a single record's display rather than to a multi-record display.
To provide a FULL header, write an overflow frame called FULL.HDR. Here is a partial outline of the code:
FRAME-ID = FULL.HDR;
DIRECTION = OUTPUT;
USAGE = DISPLAY, NAMED;
FRAME-DIM = 0,79;
:
:
FRAME-NAME = FULL.HDR;
FRAME-TYPE = OVERFLOW; <--Note the FRAME-TYPE
Technical note: you can now code GETELEMs in frames of type OVERFLOW. Previously, it was necessary to use the functions $GETUVAL or $GETCVAL, but this is no longer the case.
As mentioned above, the header for a FULL display only begins appearing on the second screen of the screen display. If you want the header to begin appearing on the first screen of your FULL display, you must create that first appearance yourself within the FULL frame. In the format declaration section, declare the FULL.HDR frame a second time, as frame-type INDIRECT (as well as OVERFLOW), and then reference it from your FULL frame.
Sometimes a FULL display of a single record will span more than one screen in Prism. For example, a FULL display more than 15 lines long will take more than one screen in Guided Mode on a standard size terminal. But shorter FULL displays may split across screens too, during a multi-record display request such as DISPLAY ALL FULL.
When a record does span screens in this way, you may want to guarantee that certain segments of the display always appear together on the same screen. For instance, if your file contains elements for NAME and ADDRESS, followed by long textual elements called DESCRIPTION and ABSTRACT, you may want to ensure that DESCRIPTION and ABSTRACT are always displayed in one piece, and never span two screens. (You would like them to appear on the same screen with NAME and ADDRESS, but only if the entire block can fit on the screen.)
Coding the UPROC = HOLDATA statement in your format is the recommended method for bracketing together related segments of a record in the FULL display. The HOLDATA statement should appear as a Uproc in a label group preceding the label group(s) whose data should be kept together upon one screen.
For instance, to ensure that the display of DESCRIPTION and ABSTRACT never spans two screens, code a HOLDATA statement roughly as follows:
LABEL; UPROC = HOLDATA; <--code this statement before LABEL = DESCRIPTION; elements to be bracketed into GETELEM; a segment : PUTDATA; LABEL = ABSTRACT; : PUTDATA; LABEL; UPROC = FLUSHDATA; <--closes the segment for : DESCRIPTION and ABSTRACT
Note the FLUSHDATA Uproc in the example above, which closes the segment opened by HOLDATA. Instead of FLUSHDATA, you could code another HOLDATA statement, if you wanted to close the first segment and simultaneously open a new segment containing multiple values or label groups.
You may not need HOLDATA and FLUSHDATA in your display format at all. If you do decide to use them, you will probably need to experiment to make sure they create the kind of display you want.
If you use the HOLDATA technique described here, you will probably need to request a large enough "minimum" number of rows for your FULL display to encompass the entire segment when you answer this question:
Enter minimum lines required for full displays: __
Choose a number large enough to accommodate your largest HOLDATA segment. (This question appears in all the places where you can install displays: the ADD PROFILE and MOD DISPLAYS entry forms in Prism Profile, and the XSETUP DISPLAYS command.)
The BRIEF and FULL displays described so far are sufficient for most applications. But additional displays may make your application's data even clearer to your users. For instance, if you have dropped information from your FULL display for the sake of security, you might code a special display showing this information to a small subset of your end-user community.
If your users naturally think of your data as split up into categories, you could code and install an additional display for each category. For instance, a student file might offer a display for academic information, a display for extracurricular activities, and a display (with limited access) showing grades.
An additional display may also be used to display a record immediately after an entry transaction, if the user issues a REVIEW command. [See 11.3.1 for a discussion of the REVIEW command.]
One good use for an additional display is to provide a convenient format for printing your data. If your end-users often print from your application, you'll probably save them time by installing the "print" format as an additional display instead of as a pre-defined report. Additional displays can be accessed from virtually anywhere in your file, whereas reports can only be accessed after a user types REPORT.
Like your primary displays, your additional displays fall into two basic categories: BRIEF-style and FULL-style.
BRIEF-style Displays FULL-style Displays - feature multiple, - feature single, numbered records unnumbered records - include $RECNO - do not include $RECNO in their coding in their coding - can have header frames - can have header frames of frame-type XEQ at top of type OVERFLOW at top of every screen of 2nd and later screens
Every additional display should resemble either BRIEF or FULL in the features listed. (The header frame is optional.) When you install the display, you specify whether it is BRIEF-style or FULL-style, and Prism treats the display accordingly.
For each additional display, code a data frame in your display format -- the same format that defines your BRIEF and FULL display. The name of the frame corresponds to the name of the extra display you wish to offer. For instance, to code an additional display to be accessed in Prism by the command DISPLAY SUMMARY you would name your frame as below:
FRAME-NAME = SUMMARY; FRAME-TYPE = DATA;
One restriction on the name you choose is that it must not conflict with the existing DISPLAY options: BRIEF, FULL, REPORT, or ALL. (I.e., don't name your frame FULLER, even if it is.)
Additional displays can have headers like FULL or BRIEF displays. The frame-type for the header of a BRIEF-like display would be XEQ; the frame-type for the header of a FULL-like display would be OVERFLOW. [See 3.2, 3.3.]
Prism allows you to install as many as 200 additional displays, besides BRIEF and FULL. To install an additional display, use the XSETUP DISPLAYS command (or the MOD DISPLAYS entry form in Prism Profile). [See 3.5.] (Of course, you will not be able to install additional displays until you have installed your application with ADD PROFILE.)
There are several places in Prism where your additional displays are listed automatically:
- The display names are listed among the display options that end-users see when they type HELP OPTIONS.
- Prism automatically lists them (name and description) as part of the HELP <file-name> record explaining your file. [See 6.4.2.]
- The names and descriptions are automatically listed on the HELP DISPLAYS IN THIS FILE record for your file.
- The displays are listed as formatting options on the Prism PRINT screen.
- When a user issues the DISPLAY command during data entry, Prism shows a list of displays (and descriptions) to choose from.
You may want to publicize your additional displays even further, by listing them on your file's welcome screen or in other help records.
We recommend, in fact, that you write a help record describing each of your additional displays, so that users can type HELP <display-name> DISPLAY for an explanation. It is also possible to create a context help for a specific display. [See 6.4.4 for details on these help records.]
Before you can use your displays in Prism you must declare their names and characteristics. Prism will need to know the following details among others:
- The name of the format containing your display frames.
- The minimum number of rows that must be available on a Prism screen before a new record can be displayed. (E.g., if there are 2 lines left on a screen, Prism needs to know whether to begin displaying the next record or hold it for the following screen.)
Your BRIEF and FULL displays may be installed in the ADD PROFILE entry form, at the time you first create your file profile. [See 4.1.4 for an example of the ADD PROFILE screen relating to displays.] To modify information about your BRIEF and FULL displays later, or to install additional displays besides BRIEF and FULL, use the XSETUP DISPLAYS command (or the MOD DISPLAYS entry form in Prism Profile).
XSETUP DISPLAYS is one of a family of XSETUP commands with which you may maintain your application. [See 8 for more information about XSETUP.] As with all XSETUP commands, type XSETUP DISPLAYS while you have your own application selected.
An alternative to XSETUP DISPLAYS is the MOD DISPLAYS entry form in Prism Profile. Both tools provide the same function (and the screens shown for both are almost identical), but XSETUP DISPLAYS offers the convenience of being able to maintain your application without having to move to Prism Profile.
Here is an example of the screens for XSETUP DISPLAYS. This example shows how you would install a new display for the United States file.
__________________________________________________________________________
United States XSetup Display 04/05/90 09:51
Select Function
--------------------------------------------------------------------------
1 <-- Type the number of the function you want to perform (1-3).
1. DEFINE a new display.
2. MODIFY or REMOVE an existing display.
3. CHANGE the order of displays.
___ <-- For MODIFY or REMOVE, type a number from the list below.
1. BRIEF, FULL BRIEF and FULL displays
__________________________________________________________________________
After entering "1" in the first field above and issuing the OK command, you are taken to a second screen where you name the accounts that should have access to the display and tell Prism the following:
- A brief description of the display (48 characters maximum). This description is shown when Prism lists your displays for users (e.g. in HELP DISPLAYS IN THIS FILE).
- The minimum number of rows that need to be available on a Prism screen before a new record can be shown using this display.
- Whether the additional display resembles a BRIEF display or a FULL display. [See 3.4.]
__________________________________________________________________________
United States XSetup Display 04/05/90 09:51
STATES: Display
--------------------------------------------------------------------------
NAME of display DESCRIPTION for this display
____________ ________________________________________________
Choose a display style from the list below: 1
1. FULL-style (single record display)
2. BRIEF-style (multiple record display numbered with $RECNO)
Enter minimum lines required for this display: _1
Indicate all accounts, groups, or access lists that may use this display:
_________________________________________________________________________
_________________________________________________________________________
_________________________________________________________________________
___________________________________________________________________________
As mentioned in the introduction, you can enhance your basic application with "processing steps" to customize your application to your end-users' special needs. These processing steps would be either SPIRES protocol or SPIRES formats code, depending on their purpose. Processing steps are discussed in detail in later chapters. This section simply mentions some points in the file-selection and searching process where you might want to code and install extra steps.
Processing steps can be used at the following points in the file-selection and searching process:
- When an end-user first selects your file. (That is, just after an end-user has issued the SELECT command and after Prism has attached your file and set your format.)
- As part of processing an individual search type. [See 13 for information on protocol processing steps related to searching.]
- After a search has been processed. (That is, after the search result -- or zero result -- has been retrieved, but before it has been posted and displayed to the end-user.)
- When an end-user leaves your file (for instance, by selecting someone else's file).
Here are some of the possible uses for processing steps at the above points in a Prism session:
- A processing step at file-selection might ask end-users for specific information, such as an "authorization code", which would determine how freely they could use your file. (This processing step would be based on XEQ frames in your display format.)
- A second processing step at file-selection, connected to the one above, might validate the authorization code in a table behind the scenes. (This type of processing step would execute a Proc, or subroutine, in one of your Prism protocols.)
- Other processing steps might invoke protocol code to record statistics, or might adjust the end-user's environment in much the same way that SELECT-commands alter a user's environment in SPIRES. Or applications with multiple views of the data might ask users for their preferred view, then set it up behind the scenes.
- A protocol processing step might perform a "hidden search" to give end-users an automatic search result when they select the file. [See 13 for details on hidden searches.]
- A processing step when the end-user leaves your file might collect statistics or send your own account some kind of notification.
And there are many other possibilities besides these.
The following highly-simplified charts may help give an idea when extra processing steps might be applied during file selection and searching. The horizontal lines show the flow of a basic Prism session, while the arrows below the lines show places where you would insert processing steps or other code, such as a help record:
FILE-SELECTION:
(User \ \ \
selects -----------------------------------------------------
your / / /
file)
| /|\ | /|\
| | | |
| | | |
\|/ | \|/ |
PROCESSING STEPS WELCOME TO FILE
(in place of or in (a required help
addition to your record, unless you
welcome screen) have a step perform
the same function)
[See 6.4.1 for more on the welcome help record.] Note that you must have processing steps or a welcome help (or both) -- in other words, every file is required to have a welcome of some kind. You can also code a processing step for when the file is cleared (i.e., when the end-user leaves the file).
PROCESSING A SEARCH RESULT:
SEARCH (Prism \ \
performs requested -----------------------------------------
search) / /
if | /|\ if \ /|\
zero | | >0 \ |
result | | result\ |
\|/ | _\| |
Protocol step Protocol step
for zero result for >0 result
Though the diagram above doesn't indicate branching very well, note that only one of the two protocol steps would be executed for a given search, even if you coded both.
To learn the details of adding processing steps to your application, turn to the chapter on Adding Processing Steps. [See 9.] You will also need to be familiar with the manual "SPIRES Protocols" or "SPIRES Formats" (or both) -- use the PUBLISH command online to obtain copies.
Processing steps are also useful for reports and are required for data entry forms, so they will be covered in some detail in upcoming chapters.
Once you have 1) modified your SPIRES file definition, and 2) coded and tested your display format, your application is ready to be installed in Prism for testing. This initial installation is done by creating a "file profile" (or "application profile") to describe your application to Prism.
This chapter explains how to create your profile, using the ADD PROFILE entry form in the Prism Profile file.
If you have already carried out the steps described in the previous chapters, then successfully adding your file profile and writing some help records are the only tasks you still have to perform, in order to install a basic application for searching and display.
Your "file profile" consists of a compact description for Prism of the way your application will behave when end-users select it. In the profile you declare to Prism the basic design of your application, as you have previously coded it in SPIRES. For instance, in the profile, you tell Prism:
- The name and description of the file on the SELECT menu;
- What accounts, groups, or access-lists may select the file;
- What search types (indexes) are available for searching the file;
- Whether there are headers for display, additional displays besides BRIEF and FULL, or other special features, such as processing steps.
One way to understand your file profile is to contrast it with the SPIRES file definition that it's based on. While the file definition (the record stored in the SPIRES file FILEDEF) defines your SPIRES file as a whole, your file profile describes your specific application as it functions in Prism. It never alters the way a file behaves outside Prism. The file profile covers strictly the information Prism needs to know in order to run your application.
File profiles for Prism applications are stored in the Prism Profile file (itself a Prism application). You fill out entry forms in Prism Profile in order to install your file profile (or make changes to it later). The ADD PROFILE entry form is used to create your basic profile.
ADD PROFILE creates a profile for a basic searching application. You specify general information about your file, plus details about your BRIEF and FULL displays and your indexes.
Later you can use other entry forms in Prism Profile to add information to your file profile. For example, the MOD ACCESS entry form lets you easily change the list of people allowed to select your application. Some application maintenance tasks may be done either in Prism Profile or with the XSETUP command, from within your own application. For example, the XSETUP REPORTS command (or the MOD REPORTS entry form in Prism Profile) lets you install reports for your application. [See 8 for details about maintaining your application.]
The rest of this chapter will cover ADD PROFILE, page by page. But before we do that, it's worth mentioning the best way to give your user community access to your application.
Prism lets you name access lists, not just individual accounts or groups of accounts, when you extend or modify access to your Prism application in Prism Profile. This feature makes it much easier for applications with complex or changing communities of end-users to manage select-access, as well as access to indexes, entry forms, reports, additional displays or fields. Ideally you'll be able to manage access using one or more central records in the SPIRES file EXTDEF, instead of within many different screens scattered through Prism Profile.
Technically, an access list is a record in the SPIRES subfile EXTDEF, whose key is the name of the list. The EXTDEF record specifies all Data Center accounts (or groups of accounts) that are to be included in the access list.
For example, a developer using the account GQ.PUP could create an access list called GQ.PUP.TESTGROUP by selecting EXTDEF in SPIRES and adding a simple record like the following:
ID = gq.pup.testgroup;
ACCESS-ACCOUNTS = gq.abc,gq.def,gq.ghi; <--this list could
be much longer...
After adding the EXTDEF record, you can name the access list in any of the places in Prism where you ordinarily specify end-user access to your application. For details about creating access lists in EXTDEF, [EXPLAIN ACCESS LISTS.]
The access list GQ.PUP.TESTGROUP (shown above) could be entered in ADD PROFILE as follows:
______________________________________________________________ Prism Profile Entry Form: ADD PROFILE 06/15/88 10:50 -------------------------------------------------------------- Indicate accounts, access lists or groups to use this file: gq.pup.testgroup______________________________________________ ______________________________________________________________ ______________________________________________________________ (etc.) ______________________________________________________________
Once the above transaction is completed with the SEND command, anyone included in GQ.PUP.TESTGROUP will have access to the file. The same access list could be named in other places where Prism asks who should have access to components of your application. At any later time, simply adding an account to the list in the EXTDEF record will automatically extend access for that account to any Prism forms, reports, etc., that are associated with the access list. (And the same for withdrawing an account.)
Access lists can contain lists of University IDs in addition to (or instead of) Data Center accounts. University IDs go in the ACCESS-UNIVIDS element of the EXTDEF record:
ID = gq.pup.testgroup; ACCESS-UNIVIDS = 09999798, 09999954, 09984790;
Access lists with University IDs can be used to control access to reports, entry forms, indexes, fields, and displays, or to control access to your Prism file itself.
In order for this to work, $UNIVID must be set -- that is, you must identify the user of your application by University ID. [See 25 to read about tools to identify users by ID and PIN.]
Since you can't test your application until it's installed in ADD PROFILE, and since an untested application should be hidden from the public eye, you should be sure your application's availability is limited to a few accounts (maybe just your own) until it's tested and the necessary help records are installed. (The current default is to limit access to the installer's account only.) Later you can widen access to the file (either with the XSETUP PROFILE command or with the MOD ACCESS entry form in Prism). [See 8.1, 8.4.]
The ADD PROFILE form installs your basic application in Prism, enabling searching and display. ADD PROFILE lets you specify your file's name on the Prism menu, declare the indexes to be used in searching, determine which accounts are allowed to select the file in Prism, and accomplish many other tasks. The rest of this chapter will explain each screen of ADD PROFILE.
To invoke the ADD PROFILE form and begin installing your basic file profile record, type these commands after entering Prism:
YOUR RESPONSE: select prism profile YOUR RESPONSE: entry add profile YOUR RESPONSE: create
In the sample screens, required fields are marked by underscoring (______), while optional fields are marked by a row of periods (......)
Online, both required and optional fields are underscored on most terminals, and required fields are yellow (or bright on monochrome terminals) and optional fields green.
After completing the ADD PROFILE screens and issuing the SEND command, you can begin testing your new application. Issue the BEGIN command to initiate a new Prism session (and "refresh" the list of files to include the one you just added). Then SELECT your new file and start testing.
____________________________________________________________________________
Prism Profile Entry Form: ADD PROFILE 10/15/87 16:38
Profile, page 1
----------------------------------------------------------------------------
Enter the file's internal identifying code (e.g. PUBEVENT).
File-ID: _________________
Enter the following information as it should appear on the SELECT menu:
NAME (e.g. PUBLIC EVENTS) DESCRIPTION (e.g. Stanford Public Events)
_________________________ ________________________________________________
Enter the SPIRES file-name for this subfile (e.g. GQ.DOC.PUBLIC.EVENTS).
SPIRES file-name: _______________________
Enter an 'X' next to the categories appropriate for this file.
(Type HELP CATEGORIES for an explanation of Prism categories.)
_ FINANCIAL _ FACILITIES _ ONLINE FORMS
_ STUDENT/ACADEMIC _ DEVELOPMENT OFFICE _ MISCELLANEOUS
_ PERSONNEL _ MAIL/COMMUNICATION _ APPLICATION DEV.
____________________________________________________________________________
____________________________________________________________________________ Prism Profile Entry Form: ADD PROFILE 2/29/94 10:50 <file-id>: Contact/maintenance information ---------------------------------------------------------------------------- Enter the name and phone number of the person responsible for this application: ________________________________________________________ Enter the electronic mail address to which Prism logs and error reports will be mailed: gg.uuu____________________________________________________ Enter 'Yes' to receive online notification of system errors: Yes Enter accounts or access lists allowed to maintain all Prism records: ............................................................................ Indicate additional accounts or access lists to maintain only help records: ............................................................................ Enter the electronic mail address if you want to receive nightly reports of helps requested but not found: ________________________________________ Alternate file-id for help records: ________________ Enter 'Yes' if you want to control file selection by University IDs as well as accounts: No_ _____________________________________________________________________________
Depending on your answer to this question:
Enter 'Yes' if you want to control file selection by University IDs as well as accounts: No_
you will next see one of the following screens.
If you answered "no" to the question, you will see the first screen below, where you simply enter the accounts and/or access lists authorized to enter your file. Remember that an account must have access to the SPIRES subfile supporting your application before it can obtain access to the application in Prism. [See 2.1.]
Note: at first you should only give access to your own account and a few other test accounts. After testing the file and writing the helps, you can widen access to the file using the XSETUP PROFILE command or the MOD ACCESS entry form. [See 8.1, 8.4.]
____________________________________________________________________________ Prism Profile Entry Form: ADD PROFILE 2/29/94 10:50 <file-id>: Account based access ---------------------------------------------------------------------------- Indicate all accounts, groups, or access lists that may use this file: ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ _____________________________________________________________________________
If you answered "yes" to the question, you will see the screen below, where you may specify both account-based and University ID-based access to your Prism file.
____________________________________________________________________________ Prism Profile Entry Form: ADD PROFILE 2/29/94 10:50 <file-id>: University-ID based access ---------------------------------------------------------------------------- Show this file on SELECT menu for these accounts, groups, access lists: ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ Re-validate these accounts, groups, access lists after ID/PIN prompt: ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ _____________________________________________________________________________
- The user's account matches an account in the list in bottom of the screen.
- The user's account is in an account-based access list shown here.
- The user's University ID is in an ID-based access list shown here. [See 25 for complete information about University ID identification.]
The next screen lets you install automatic sorting or sequencing of search results in your file.
____________________________________________________________________________ Prism Profile Entry Form: ADD PROFILE 2/29/94 17:21 <file-id>: Sorting information ---------------------------------------------------------------------------- Sorting fields may be defined to allow the user to sort any search result, and you may specify fields by which results are automatically sorted. You do not have any fields yet defined. Use MOD FIELDS to define sorting fields that may be used by the user or for automatic sorting. If you would like search results to be sorted, but not presented as a sorted Prism result, you may specify element names for sequencing: ............. .............. .............. .............. Automatic sorting does not occur for large results. Specify here the upper limit within which automatic sorting will occur: 50. ____________________________________________________________________________
If you want Prism to automatically sequence search results in your application, list here the SPIRES element(s) to drive the sequencing. All the options allowed on the SEQUENCE command in SPIRES are also allowed here (e.g. DATE(D) for descending order by DATE). You may enter a semi-colon here in order to cause SPIRES to issue a SEQUENCE command with no element names following (which will achieve sequencing by record keys or locators).
The sequencing elements you install here are hidden from end-users. That is, there is nothing on the Prism screen to indicate that this sequencing has taken place. If you install sorting fields (described in later chapters) for your application, users can can override your sequencing by using the SORT command. But any time that they don't specify sorting of their own, your hidden sequencing (based on the elements you name here) will take effect. Thus, the hidden sequencing that you specify here prevents end-users from ever seeing your records completely unsequenced.
Here is another (perhaps better) way to provide for ordered search results in your application:
Once sorting fields are installed, an additional question appears on the XSETUP PROFILE screen corresponding to the one above:
Specify here fields to be used for automatic sorting: .............. .............. .............. ..............
The main advantage of sorting by fields instead of sequencing by elements behind-the-scenes is that they're visible to your end-users, so they'll understand why their records are sorted the way they are.
To specify an upper record-limit for automatic sorting of search results, enter the number here. For instance, if you enter a value of 100, search results of 99 records are automatically sorted, but results of 101 records are not. Sorting records can be expensive, so we recommend an upper limit of 50 records, but some other limit may work better for your application.
____________________________________________________________________________ Prism Profile Entry Form: ADD PROFILE 2/29/94 20:33 <file-id>: Results/displays/processing steps ---------------------------------------------------------------------------- Enter 'Yes' if you need to use $RESCNT for processing results: No_ Enter element to be used as Prism record identifier: ................ Enter the SPIRES format name for displays: <file-id> DISPLAY___________ Enter minimum lines required for brief displays: _1 Enter minimum lines required for full displays: _1 If Personal Searches, Reports and Fields should be saved using a file-id other than <file-id>, enter alternate file-id here: ................ Enter 'Yes' to see screens to add, modify, or delete processing steps. - when the subfile is selected or cleared: No_ - when search is completed: No_ Enter 'Yes' if the protocol processing steps for this file are compiled: No_ ____________________________________________________________________________
The next screen for ADD PROFILE is where you define indexes for your application. This screen occurs once for each index that you define:
____________________________________________________________________________ Prism Profile Entry Form: ADD PROFILE 2/29/94 13:27 <file-id>: New index ---------------------------------------------------------------------------- Enter the following information as it should appear on the FIND menu: NAME DESCRIPTION for this index Sample Search Value ________ ____________________________________ ________________________ Enter 'Yes' if this index supplies its own search value: No_ If not, enter the prompt used for this index: ____________________ Enter up to 3 lines of explanation to be displayed at the prompt: ___________________________________________________________________________ ___________________________________________________________________________ ___________________________________________________________________________ Enter 'Yes' to declare or modify special features for this index: No_ Indicate all accounts, groups or access lists that may use this index: PUBLIC______________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________
Your Prism index usually correspond to indexes in your SPIRES file definition. (The only exception to this is in a customized search type, which uses protocol processing to create or modify a search result.) [See 13 for details on protocol steps for search types.]
The name of your index may correspond to a search term in your SPIRES file definition, but this is not a requirement. (If the Prism name does not correspond to the SPIRES name, you specify the matching SPIRES name in a different space on the "Special features" screen.)
Note that you can install as many as 64 indexes.
The values you enter under "Name", "Description", and "Sample search value" appear on the FIND menu in your application, as in the sample screen below:
_____________________________________________________________________________
United States Search 04/05/90 09:37
Index selection for FIND 10 indexes available
-----------------------------------------------------------------------------
Choose one or more indexes by typing the name or number for each type of
information you have, e.g. ABBREV or 1
TYPE OF SEARCH DESCRIPTION EXAMPLE
1. ABBREV Postal abbreviation for a state CA
2. NAME Name of the state California
<etc.>
_____________________________________________________________________________
After selecting an index from the menu, one is asked for a search value, as below. The word in parentheses is the name of the selected index. The text after the name is your "Explanation" and the words after the explanation are your "Prompt".
_____________________________________________________________________________ United States Search 04/05/90 09:37 Selected indexes: ABBREV ----------------------------------------------------------------------------- (ABBREV) Enter the two-letter postal abbreviation for a state, e.g. CA. State Abbreviation: _____________________________________________________________________________
Other features are available for an index:
- Installing a stand-alone or qualifying index
- Supplying an alternate index name or a SPIRES index name different from the Prism one
- Specifying a processing step for the index
- Asking for "phrase processing" for the index
The screen for "special features" is shown on the next page. To install these features, answer "yes" to this question:
Enter 'Yes' to declare or modify special features for this index: yes
This screen appears if you ask to declare "special features" for an index:
_____________________________________________________________________________
Prism Profile Entry Form: ADD PROFILE 2/29/94 13:30
<file-id>: Index <name>
-----------------------------------------------------------------------------
1 <-- Indicate how this index is used by choosing one category
1. Regular search type
2. Stand-alone search type
3. Qualifying search type
Index name on FIND menu: ABBREV
Alternate name recognized by Prism (e.g. ACCT for ACCOUNT): ________________
SPIRES index name, if different from Prism name: ________________
If this index has a processing step, enter its name here: ________________
_ <-- Which, if any, special processing does this index require
1. Treat search values as phrases
2. Treat as two-part, Personal Field search
_____________________________________________________________________________
The following screens for "select/clear" processing steps appear between screens 2 and 3, but only if you asked to "see screens for declaring steps" when the file is selected or cleared. Skip these screens unless you are ready to install steps. [See 3.6, 9 for information on processing steps.]
_____________________________________________________________________________
Prism Profile Entry Form: ADD PROFILE 10/15/87 13:42
<file-id>: Select/Clear Steps, File Select
-----------------------------------------------------------------------------
Please identify processing steps that Prism should execute. For TYPE,
enter "S" for a screen step, "P" for a protocol step. TITLE is required for
screen steps since that title is used to label the screen.
Processing steps for when file is selected:
STEP# STEP ID TYPE TITLE/COMMENT
1 ................ . ................................
2 ................ . ................................
3 ................ . ................................
Processing step for when file is cleared:
STEP# STEP ID TYPE TITLE/COMMENT
CLEAR ................ P ................................
_____________________________________________________________________________
If you've a coded a protocol step to be invoked when end-users leave your file, identify its step-id here and add a comment if you wish.
On the next two screens (condensed to one page below), declare whether your steps for file selection or clearing should only be invoked under special conditions, and if so, what the conditions are.
______________________________________________________________________________
Prism Profile Entry Form: ADD PROFILE 10/15/87 14:32
<file-id>: Select/Clear Steps, File Select
------------------------------------------------------------------------------
SPECIAL CONDITIONS: Enter "Yes" to declare or change conditional statements.
Processing steps for when file is selected:
STEP# STEP ID TYPE CONDITIONS
1 <step1>......... S No. <----Change "No" to "Yes"
2 <step2>........ P No. for any step that you
3 <step3>......... P No. want conditionally
performed.
/
Processing step for when file is cleared: /
/
STEP# STEP ID TYPE CONDITIONS /
/
CLEAR <laststep>...... P No. <----/
______________________________________________________________________________
______________________________________________________________________________
Prism Profile Entry Form: ADD PROFILE 10/15/87 14:32
<file-id>: Processing Steps -- Page 3
------------------------------------------------------------------------------
DO ONLY IF: This condition must be true for the step to be done a first time.
1 <step1> DO ONLY IF: .......................................
2 <step2> DO ONLY IF: .......................................
CLEAR <laststep> DO ONLY IF: .......................................
_____________________________________________________________________________
The blank beginning "DO ONLY IF:" appears by those steps for which you requested "special conditions" on the previous page. Specify here the condition that must be true for the step to be performed: allowed syntax includes anything that would be allowed between an IF and THEN in SPIRES.
The next series of screens only show up if you earlier requested processing steps for "when search is completed":
______________________________________________________________________________
Prism Profile Entry Form: ADD PROFILE 10/15/87 14:27
<file-id>: Result Steps
------------------------------------------------------------------------------
Please identify processing steps that Prism should execute.
Processing step to be executed for RESULT = 0
STEP# STEP ID TYPE TITLE/COMMENT
1 ................ P ................................
Processing step to be executed for RESULT > 0
STEP# STEP ID TYPE TITLE/COMMENT
1 ................ P ................................
_____________________________________________________________________________
If your Prism application is large or complex, you may need to know about upper limits relating to your file profile:
To see how large your profile is, use the $RECINFO function in SPIRES. For example:
> spires
> select prism profile
> show eval $recinfo(states, size) <--- for a profile with file-id
of STATES
4851 <--- profile size in bytes
>
EXPLAIN $RECINFO for more about this function.
Once the file profile is installed through ADD PROFILE, your logical next steps are to test your application, add help records, and install additional components such as reporting or sorting fields, entry forms, or additional displays.
After completing your ADD PROFILE transaction, start a new Prism session by typing BEGIN. Then you will be able to select your new application and start testing. Chapter 7 explains several debugging tools that may be useful during testing.
All maintenance of your application is done either with the XSETUP command, or with entry forms in Prism Profile. For example, you would use the command XSETUP HELP to add and modify help records for your application. Chapter 8 explains how to use XSETUP and gives general information about maintaining your application once it is installed.
Here is a summary of additional application features you might want to read about:
- Installing "fields" so that your application users can sort search results or define Personal Reports. [See 5.]
- Adding help records -- every application should have at least a minimum set of required help records before being made accessible to its user community. [See 6.]
- Defining additional displays besides BRIEF and FULL. [See 3.4.]
- Adding processing steps to customize the Prism environment. [See 9.]
- Customizing the Guided Mode options text at the bottom of the Prism screen. [See 14.]
- Installing reports or entry forms. [See 10, 11.]
This chapter shows how to install fields in your Prism application for your end-users. Fields in your application benefit end-users in these ways:
- Installing fields for sorting enables your users to sort search results in your file. They can use your sorting fields as their sorting criteria when they issue the SORT or SETUP SORT command. You can also provide default sorting of search results, using sort fields. [See 4.1.3.]
- Installing fields for reporting enables your users to define Personal Reports. They can use your reporting fields as the basic building blocks of their report when they issue the SETUP REPORT command.
Note that Personal Reporting, where end-users create their own report layouts, is only one kind of reporting available in Prism. You as a developer can also install "pre-defined" reports in your application. [See 10.] For details on the end-user's view of Personal Reporting, see the document "How to Define Personal Reports in Prism," available via the PUBLISH command in WYLBUR.
Sorting and Personal Reporting are basic components of any Prism application, and it's advisable to install both sorting fields and reporting fields. Your application's users won't be able to sort search results or make Personal Reports until you have installed fields.
Fields are easy and quick to install in the great majority of cases. You are not required to change your SPIRES file definition in order to support Prism fields.
Besides reading in this chapter about how to install fields, you may need to refer to the section that describes the PRISM DEFINITIONS subfile in SPIRES. [See 7.10.] This subfile is useful for debugging and some maintenance tasks for Personal Reports that your application's users create.
And the XSETUP PROFILE screens include a question related to Personal Reports, Personal Searches, and Tasks. [See 4.1.4.] There, you may specify an alternate file-id (besides the main application file-id) to be associated with "personal objects" created in your application. This allows multiple applications to share "personal objects" (for example, Personal Reports created in a demo application could be accessible in the production version of the application).
Before you install fields in your file, you'll want to understand just what fields are, what they're for, and how they differ from elements in your file definition.
A Prism end-user will see the Prism fields in your application as the basic pieces of information making up that application's data. To that end-user, the field represents information that probably occurs in every record within your application and that can be used to SORT records or to make customized reports.
For instance, in a name-and-address file, a user might expect to find fields such as NAME, ADDRESS, STATE, and PHONE. These fields become the building blocks out of which the user creates customized reporting and sorting.
This may make fields sound much like file definition elements, and in fact, as you'll see, every field you install does need to map to an element in your file definition (just as every search type you install has to map to a searchterm in your file definition).
But fields also let you present special packaged views of your SPIRES elements, where the field values are computed or derived from one or more than one of your elements. As a simple example, you can take an element with an encoded name in SPIRES and rename it in a more user-friendly way in Prism: for instance, the element ZIP.CODE could be installed in friendlier form as ZIP CODE -- i.e., without the period. Or you can use the dynamic-element facilities described later in this chapter to install, say, a field called ADDRESS that is in reality composed of multiple SPIRES elements: say, STREET, CITY, STATE and ZIP.CODE.
A sorting and reporting field in Prism lets you package your end-users' view of one or more elements in your SPIRES file definition.
To install fields for your application, use the XSETUP FIELDS command (or the MOD FIELDS entry form in Prism Profile). XSETUP FIELDS is one of a family of XSETUP commands with which you may maintain your application. [See 8 for more information about XSETUP.] As with all XSETUP commands, type XSETUP FIELDS while you have your own application selected.
An alternative to XSETUP FIELDS is the MOD FIELDS entry form in Prism Profile. Both tools provide the same function (and the screens shown for both are almost identical), but XSETUP FIELDS offers the convenience of being able to maintain your application without having to move to Prism Profile.
You may install up to 200 fields for sorting and reporting. In any given Personal Report, a user may include up to 24 fields (although you may give him up to 200 fields to choose from).
To create a field that directly corresponds to a single element, the only thing you need to do is to install the field, using XSETUP FIELDS. [See 5.4.]
In XSETUP FIELDS, you give the field a NAME, as well as a DESCRIPTION to tell how the field is used. The field's name does not have to correspond to the name of the SPIRES element(s) supporting it. The DESCRIPTION will be used in online help for the field, so needs to be as clear as possible.
NAME of field DESCRIPTION of this field
NAME__________ The person's name______________________
Enter an 'X' next to the Prism processes in which this field
is used:
X REPORTING _ FILTERING X SORTING
On the same screen where you give your field a name and description, you also connect the field explicitly to a single element in your SPIRES file definition:
Enter the file element name: PNAME___________
For instance, the Prism field NAME might correspond to the SPIRES element PNAME.
And that's all there is to creating a field that corresponds to a single element, except that for reporting fields you'll be asked to specify field-info, information that helps Prism format the field within a report. [See 5.2, 5.4.] The next page discusses some slightly more complex fields.
To create a Prism field that corresponds behind the scenes to several SPIRES elements, you install the field to correspond to a particular element (the primary element for the field) and on the same screen ask for "special features". For instance, to install a field called LOCATION that maps to two SPIRES elements, CITY and STATE, where CITY is the primary element:
NAME of field DESCRIPTION of this field
LOCATION______ Restaurant's Location_______________
: :
: :
Enter the file element name: CITY____________
Enter 'Yes' to add special features for this field: Yes
Then on the "special features" page you use the SPIRES dynamic element facility to define your customized field. [See 5.4.] For instance, for the field LOCATION:
For field LOCATION enter the dynamic element definition: Define element LOCATION...... for CITY as: @@CITY', '@@STATE........................................... ............................................................
Here the external values for CITY and STATE are concatenated together, and separated by a comma, to create what will look like a single value to the Prism end-user.
By the way, the field above corresponds to the following SPIRES command:
-> DEFINE ELEMENT LOCATION FOR CITY AS @@CITY', '@@STATE
(For details on dynamic elements and the DEFINE ELEMENT command, see the manual "SPIRES Technical Notes".)
Note that in addition to creating fields that map to multiple elements, dynamic element processing gives you access to all sorts of other features -- for instance, you can use SPIRES variables and functions to create or reformat values. For example, you could create a field DATE TODAY based on the SPIRES variable $DATE, or a field MONTHLY COST based on an annual value divided by twelve (i.e., @ANNUAL/12).
Instead of creating complex fields by asking for dynamic element processing, you may prefer to create virtual elements within your SPIRES file definition. For instance, the Location field shown earlier might be created as a virtual element in the filedef, and installed without "special features":
VIRTUAL;
ELEM = LOCATION;
OUTPROC = $CALL(Loc);
USERDEFS;
USERPROC = LOC;
UPROC = Set Value = $GetUval(City) ', ' $GetUval(State);
Use virtual elements instead of "dynamic element" fields if you have multiple Prism applications pointing to the same file definition. (For instance, if the same field were installed for 5 different Prism files, you'd want to define it once in your filedef rather than 5 times in Prism Profile!) For more information on virtual elements, see the manual "SPIRES File Definition".
You install a reporting field the same way as a sorting field, except that for reporting fields you need to declare additional information besides the name, description, and associated SPIRES element(s) described earlier. (By the way, remember that you can install a single field for both reporting and sorting.) The additional information mostly indicates what kind of formatting should be applied to the field in reports: for instance, its width, its value-type, its heading, etc. We call this information "field-info" below -- it's similar to element information in SPIRES, but there are important differences too.
For every reporting field in Prism, you need to specify a default width and a default heading for the field -- these are needed so that end-users can prepare an attractive report without specifying a width or heading of their own. In addition, for every reporting field, you need to tell Prism whether the field's values are numeric so that Prism knows whether or not to prompt a user for numeric summary statistics such as average, minimum, and maximum. In addition to these required pieces of field-info, there is other optional information that you'll probably want to provide.
Field-info that you can specify in Prism includes:
- What a field's heading and/or column-heading should be. (Corresponds to the HEADING and COL-HEADING elem-info in SPIRES.)
- A field's value-type (such as numeric). (Corresponds to VALUE-TYPE elem-info in SPIRES.)
- What a field's width should be. (Corresponds to WIDTH elem-info in SPIRES.)
- How a field's value should be adjusted and indented, and the maximum number of rows that a record using this field might take up. (Corresponds to ADJUST, INDENT, and MAXROWS elem-info in SPIRES.)
- What edit mask a numeric value should use. (Corresponds to EDIT elem-info in SPIRES.)
For details on all elem-info terms used above, you can use EXPLAIN in online SPIRES: e.g., EXPLAIN EDIT INFO-ELEMENT.
Although field-info is similar to SPIRES elem-info, there are often good reasons (discussed below) for specifying new values for your fields in Prism rather than relying on elem-info from SPIRES.
As a convenience, instead of specifying special field-info for your Prism field, you can ask Prism to use the element information stored in your SPIRES file definition for your field's primary element. This gives you the ease of storing the information in a single place but is only appropriate if 1) your elem-info is completely appropriate for your field without any changes, and 2) changes you make to the elem-info over time will always be appropriate for the Prism field as well.
To use SPIRES elem-info exactly as it's stored for the primary element, answer "Yes" to the following prompt in XSETUP FIELDS.
Use ELEMINFO? Yes
If you answer "Yes" to this prompt, Prism does not store your current elem-info but instead will look up the elem-info dynamically at a later time, when an end-user asks for the field in question.
Even if you don't want to use SPIRES elem-info without changes, you can still base your Prism field-info on the elem-info for your primary element, since XSETUP FIELDS will prompt you with the elem-info values listed below. You can change any of these values for your Prism field, and probably should change many of them, such as the mask and perhaps the width, for reasons discussed below.
Elem-info Values Used As the Basis for Prism Field-Info ADJUST COL-HEADING EDIT HEADING INDENT MAXROWS VALUE-TYPE WIDTH
Because SPIRES elem-info is always tied to a particular element it will not be appropriate for many Prism fields, especially fields that use dynamic element processing. [See 5.1.] For instance, the field LOCATION created earlier probably should not use the WIDTH elem-info for CITY, but should create brand-new Prism field-info for width. The reason is that a width value sufficient for a single element (CITY) would surely be too narrow for a field created out of two SPIRES elements, CITY and STATE.
Another reason for caution: if you later update elem-info in your file definition, Prism reports that were relying on the older values will suddenly start using the updated elem-info, with a possible adverse effect on the look of the reports. (More precisely, the existing report's elem-info will be automatically updated the next time the user modifies the report definition.)
If you do change prompted elem-info values, remember that the changed values are only used in Prism and have no effect in SPIRES.
Take care when specifying an edit mask for a numeric or dollar field that the mask is wide enough not just for the field itself, but also for any summary statistics created using that field. A rule of thumb is to make the edit mask a few columns wider than individual values for the field, since a statistic that summed all the values might call for a wider mask.
If your SPIRES filedef uses a system proc such as $EDIT or $DOLLAR.OUT in order to format an element value with an edit mask, be aware that this outproc by itself will not act as an edit mask for summary statistics in your reports. For proper formatting of summaries, you should also install either Prism field-info or SPIRES elem-info in addition to the outproc.
Personal Reporting in Prism offers vertical (down the page) as well as horizontal (across the page) reports. In a vertical report each field is generally given a row of its own, while in a horizontal report, fields are formatted in a table so that each row generally includes a number of different fields. (Roughly speaking, output created with the SPIRES tools Report Definer and $REPORT are horizontal -- output created with the SPIRES tool $PROMPT could be considered vertical.)
You should note that if you fill in field-info for both the "heading" and the "column heading", the field-info for "Heading" will be used as in vertical reports, and the field-info for "Column Heading" will be used in horizontal reports. [See 5.4.] (Or if you use elem-info, then the HEADING elem-info will be used for vertical reports, COL-HEADING for horizontal reports.)
(Horizontal Report)
Name Location Phone
---- -------- -----
Sophie's Choice Palo Alto, CA 765-4321
Le Castel San Francisco, CA 123-4567
etc.
(Vertical Report)
Restaurant Name: Sophie's Choice
Location: Palo Alto, CA
Phone: 765-4321
Restaurant Name: Le Castel
Location: San Francisco, CA
Phone: 123-4567
etc.
As in $REPORT and Report Definer, values in Prism horizontal reports that are too long for the specified field-width will ordinarily wrap to subsequent lines of the report. If you want these values to be truncated to fit into your specified field-width, enter the value "TRUNCATE" as the field's adjustment value on the field-info screen in XSETUP FIELDS. [See 5.4.]
Enter adjustment value: TRUNCATE
End-users who use Personal Reporting to "export" (download) their data can also ask for truncated data -- see the document "How to Define Personal Reports in Prism" for details.
If you prefer to have your long values wrap to subsequent lines rather than be truncated, you can create attractive indentation in order to format the data effectively. [See 5.4.] If you specify a negative value, you'll get a hanging indent, as shown below:
Indent: -2
produces values that look like this:
The Tragical History
of Doctor Faustus
Indent: _2
produces values that look like this:
The Tragical History
of Doctor Faustus
A field defined for Personal Reporting in a Prism application may also have a filter associated with it. If a user chooses a field for his report that has an associated filter, then a "filtering" option is presented during SETUP REPORT. The user could choose to apply a filter to his report to get more control over which data appears in the report -- more control than is possible simply by refining the search result.
Filters are useful in files with complex data structures or hierarchies, where users might typically want to see in a report only selected occurrences of a particular structure or element.
Internally, when a user chooses the filtering option, Prism is issuing SET FILTER commands in SPIRES. Filtering in Prism reports is useful in the same types of situations where SET FILTER is useful in SPIRES reporting. (See the manual "SPIRES Technical Notes" for information about the SET FILTER command.)
Here is a simple example to illustrate a situation where filters would be useful. Consider a record like the one below, and assume that reporting fields have been defined for the elements shown here.
NAME = John Smith; COURSE.NUMBER = 101; COURSE.QYY = 188; COURSE.ATTENDED = Y; COURSE.NUMBER = 111; COURSE.QYY = 188; COURSE.ATTENDED = Y; COURSE.NUMBER = 201; COURSE.QYY = 288; COURSE.ATTENDED = N; COURSE.NUMBER = 201; COURSE.QYY = 388; COURSE.ATTENDED = Y;
A typical report might look something like the one below. Without filters, the report includes all occurrences of the course structure for any given person.
Student Name Course Num Quarter Attended?
--------------- ----------- -------- ---------
John Smith 101 188 Y
111 188 Y
201 288 N
201 388 Y
The search to gather the report population might have been FIND COURSE 111, but all courses are shown in the report, not just 111. A filter on the COURSE.NUMBER element would allow the user to specify that the report should include only information about a particular course. Or he might want to see only courses for a particular quarter, or courses that the student actually attended.
You should consider your file structure and the likely reporting needs of your users in deciding which filters to provide. A filter can only be defined for a reporting field, but all reporting fields don't have to have filters. Think about the reporting problems that your users have told you about, and whether filters will or will not solve those problems.
Technical note: There is no limit to how many of your reporting fields may have filters. However, within SETUP REPORT, a user may select only up to 5 filters for a given report. And Prism may generate up to 16 SET FILTER commands internally. (One filter choice by the user may result in multiple SET FILTER commands in some circumstances.) [See 5.4.]
In SETUP REPORT, if a user chooses report fields that have filters associated with them, a "filtering" option is available. If the filtering option is chosen, the user sees a list of filters available for the report. For example:
This report may be filtered by the following fields. Enter
an "X" next to the ones you want to add.
_ COURSE NUM Include only entries for specific courses
for which a student registered (instead of
all courses).
_ ATTENDED? Include only entries for courses that
students actually attended, or courses that
they didn't attend.
_ QUARTER Include only courses for a specific QYY
(instead of courses for all QYYs).
The left column contains names of report fields with filters available. The right column consists of filter descriptions that you provide to explain how the filter will alter the appearance of the report. Note that your filter descriptions should be as clear and descriptive as possible, so that users can choose the filters that are most likely to meet their reporting needs. [See 5.4 to learn where this text is supplied in XSETUP FIELDS.]
Prism looks at the list of fields that the user chose for the report. Any chosen field that has a filter associated with it will appear on the list of filter choices. In addition, if a chosen report field is in the same structure as another report field with a filter, then that second field/filter will be on the list of filter choices, even if that field has not been selected for the report.
For example, there are filters for the COURSE NUM and ATTENDED? fields. The corresponding elements for these fields (COURSE.NUMBER and COURSE.ATTENDED) are in the same structure. If the user chooses COURSE NUM for his report (but not ATTENDED?), the list of filters will include both COURSE NUM and ATTENDED as filter choices, because the two elements are in the same structure and they both have filters associated with them.
Once a particular filter is chosen, Prism displays another screen where the user may specify the criteria by which the report should be filtered.
Selected filters: QUARTER, ATTENDED?
For QUARTER, please indicate how you wish to filter your report
_ <-- Enter an X here to filter by any QYY search values in
effect when your report is displayed or printed.
OR, enter specific values to be used for filtering this report:
(QUARTER) Specify a QYY to designate which courses should
display in the report. For example, if you enter 188 below,
then your report will include only courses that a student
registered for in quarter 188.
___________________________________________________________
As shown in the screen example above, users have two choices for how to specify filtering criteria. When you install the filter, you determine which of these choices are presented to the user (or whether both options are presented, as above).
In some cases, there may be a correspondence between a report/filter field and an index in your application. If there is, you may allow a user to specify that if he has used that index to gather his report population, then the filter should be set to match whatever search value he used.
For example, if this student file has a QYY index, the user can specify that Prism should use his QYY search value as the filter value in filtering the course structures. A different QYY search would then produce a different effect in the report.
In addition (or instead) you can provide a place where the user can enter a specific value to be used for the filter every time the report is produced. Note that you supply the text for the prompt when you install the filter. This text should give the user guidance in choosing the specific filter value to enter to achieve the desired result in the report.
The next section shows how you enable these options in XSETUP FIELDS.
To add or modify fields in Prism, use the XSETUP FIELDS command. As with all XSETUP commands for application maintenance, issue the command from within your own application.
As an alternative to XSETUP FIELDS, you may use the MOD FIELDS entry form in Prism Profile to install or maintain field definitions. Both methods present the same screens to fill in; XSETUP FIELDS offers the advantage of being able to modify your application without having to move to Prism Profile. [See 8 for details about XSETUP.]
Here is an example of the first screen of XSETUP FIELDS, if you already have at least one field installed. (If you don't yet have any fields, you are taken directly to the screen shown on the next page.)
____________________________________________________________________________
Restaurants XSetup Field 04/05/90 16:05
Select Function
----------------------------------------------------------------------------
_ <-- Type the number of the function you want to perform (1-3).
1. DEFINE a new field.
2. MODIFY or REMOVE an existing field.
3. CHANGE the order of fields.
___ <-- For MODIFY or REMOVE, type a number from the list below.
1. NAME Name of the restaurant
2. CITY City where restaurant is located
3. STATE Two-letter code for the restaurant's state
<etc.>
____________________________________________________________________________
Here, you indicate the task you want to do -- defining or modifying a field definition, or changing the order in which fields are listed.
The list in the bottom portion of the screen includes all fields currently defined for your application.
Here is the screen where you give the details about an individual field:
____________________________________________________________________________
Restaurants XSetup Field 04/05/90 16:05
RESTRNTS: Field
----------------------------------------------------------------------------
To remove, enter 'R': _
NAME of field DESCRIPTION of this field
location______ Combined city and state location of restaurant__
Enter an 'X' next to the Prism processes in which this field is available.
x REPORTING _ FILTERING x SORTING
Prism field definitions must be associated with a single element in your
file definition, either as a one-to-one match or via a dynamic element.
Enter the file element name: city_____________________________
Comments: _______________________________________________________________
Enter 'Yes' to add or modify special features for this field: Yes
(Special features are dynamic elements and alternate sequencing.)
Indicate all accounts, groups or access lists that may access this field:
public______________________________________________________________________
____________________________________________________________________________
____________________________________________________________________________
If you previously asked for special features for your field, this screen appears:
____________________________________________________________________________
Restaurants XSetup Field 04/05/90 16:05
RESTRNTS: Field LOCATION Special Features
----------------------------------------------------------------------------
Dynamic element definition for field LOCATION:
Define element LOCATION...... for CITY as:
@@CITY', '@@STATE..........................................................
...........................................................................
Enter the dynamic element type (default=STRING)* String_
_ <-- Enter "X" if default sort order is descending
_ <-- Enter "X" if Prism should sort using internal form of values
(NUMERIC, DATE, TIME and DOLLAR values sort internal automatically)
If other SPIRES elements are to be used for sequencing enter below:
__state______________________________
__city_______________________________
_____________________________________
____________________________________________________________________________
Use Dynamic Elements if you want to create a field based on computed or derived values, or a field that maps to multiple elements in your file definition. [See 5.1.]
Anything allowed in a DEFINE ELEMENT command in SPIRES is allowed here. For instance, the field above corresponds to the following DEFINE ELEMENT command in SPIRES:
DEFINE ELEMENT LOCATION AS @@CITY ', ' @@STATE
The field LOCATION concatenates the CITY element and STATE element in the external form of these elements. For details on dynamic elements, EXPLAIN DYNAMIC ELEMENTS in online SPIRES or see the description of dynamic elements in the manual "SPIRES Technical Notes".
The descending sort order option instructs Prism to send the appropriate (D) option on the SEQUENCE command that it constructs for SPIRES. In addition, when this field is listed for users on sorting screens, a (D) label will indicate that the field sorts in descending order by default.
In general, default descending order should be used sparingly, only in cases where the most logical or useful sorting order is clearly descending (e.g. reverse chronological). Users may ask for descending order themselves during sorting and reporting operations, on a case by case basis, regardless of what you specify here in the field definition.
The internal sorting option: In SPIRES, sequencing works on internal forms of element values unless you specify otherwise. In Prism, if a sorting field is marked with a "value-type" of NUMERIC, DATE, TIME, or DOLLAR, internal values are used for sorting. Otherwise, external forms are used -- unless you mark this space in the field definition, to request internal forms. (Value-type for a field is chosen on the next screen in MOD FIELDS.)
Under Other elements for sequencing specify any special sequencing you need for this field. For example, since the field LOCATION above is composed of the CITY and STATE elements, you might wish to tell Prism that sorting by LOCATION really means to sequence records by STATE and CITY, in that order, not just by CITY.
Note that you can specify the element's structural path, if this is necessary for distinguishing two elements with similar names. (EXPLAIN STRUCTURAL ELEMENT PATH in online SPIRES or see the "Global FOR" manual for more details on structural paths for elements.)
Note: Prior to 6/93, developers used (D) and (I) in the "alternate sequence" space to get descending sorting or sorting by internal values. Use the "Enter X" spaces to accomplish this, in preference to the older practice.
Specify field information here for reporting fields. (This screen will not appear for fields installed for sorting only.)
____________________________________________________________________________
Restaurants XSetup Field 04/05/90 16:05
RESTRNTS: Field LOCATION Field Info
----------------------------------------------------------------------------
Use ELEMINFO? No_ If 'Yes' Prism will use SPIRES ELEMINFO for this field's
default options. If 'No', then values entered below will
be kept by Prism for use by Personal Reporting.
--------------------Prism field information for LOCATION-------------------
Heading: City and State______________________
Column heading: Location............................
Column adjustment* LEFT____ Width of field: 25_ Indent: -2
Edit mask: .................................................................
Value type for this field* Text____
NUMERIC and DOLLAR types enable statistics for reports.
NUMERIC, DOLLAR, DATE, TIME sort by internal values.
If a report using this field might require more than 100 rows for a single
record, enter a higher limit (i.e., greater than 100): 100
____________________________________________________________________________
This screen prompts you with any elem-info values that you have stored in your file definition for the primary element supporting your field. If you want Prism to use elem-info for your field, answer "Yes" to the prompt at the top of the screen, and do not change any of the prompted values on the rest of the screen.
If you answer "Yes" to the elem-info prompt, Prism uses your filedef's elem-info and ignores anything else you type on this screen. Thus if you choose to use your filedef elem-info, there is no reason to fill out the rest of this screen. [See 5.2.]
In order for you to use SPIRES elem-info, your file definition must have at least the following elem-info defined: HEADING, VALUE-TYPE and WIDTH.
To enter customized Prism field-info, answer "No" to the prompt at the top of the screen, and change the values on the rest of the screen as you wish. (This customized Prism field-info information will not be stored or used anywhere outside Prism.)
If your filedef has values for corresponding elem-info, these values are prompted but can be changed. Use EXPLAIN online for more information, e.g. EXPLAIN ADJUST INFO-ELEMENT.
Indent: -2 Indent: 2 Indent: __ (blank)
xxxxxxxxxxxxx xxxxxxxxx xxxxxxxxxxx (i.e. this is the
xxxxxxxxxxx xxxxxxxxxxx xxxxxxxxxxx default)
If you indicated that a reporting field should also be used for filtering, you would see the screen below, on which you give the details about how the filter is defined.
_______________________________________________________________________________
Students XSetup Field 04/05/90 16:05
STUDENTS: Field COURSE NUM, Filtering Information
-------------------------------------------------------------------------------
Field COURSE NUM, from structure COURSE.STR, element COURSE.NUMBER
Prism should set filter for COURSE.STR_________________________
Filter description: ________________________________________________________
________________________________________________________
You may let users filter 1) by using search values in effect when the report is
generated and/or 2) by typing specific values in the report definition.
1) Index corresponding to NAME field: ________
2) Instructions to show when user is prompted for specific filter values:
____________________________________________________________________________
____________________________________________________________________________
____________________________________________________________________________
_______________________________________________________________________________
Prism prompts information in the first line about the element corresponding to this reporting field. If the element is in a structure, Prism prompts the name of the containing structure in the first input field on the screen, labeled Set filter for...:.
If you wish, you may change that value, to filter on a higher level structure, if applicable. By changing the structure name here, you control the effect of the filter. For example, suppose your database records had structures like this:
NAME.STR; NAME = John Smith; PHONE.STR; NUM = 555-11111; TYPE = HOME; PHONE.STR; NUM = 723-1111; TYPE = WORK;
If you were defining a filter for a reporting field based on the TYPE element, you could tell Prism to set the filter for either the PHONE.STR or the NAME.STR structure. If you specified that Prism should set the filter for NAME.STR, then the filter would show only names where a particular TYPE of phone number was present (e.g. SET FILTER FOR NAME.STR WHERE TYPE = HOME). If the filter were set for PHONE.STR, then only phone numbers of a particular type would be shown (e.g. SET FILTER FOR PHONE.STR WHERE TYPE = HOME).
The Filter description appears beside the field name when the user is presented with a list of filter fields to choose from. This description should clearly explain what reporting problem the filter will solve. If there is any question about which report data will be filtered, you should try to make that clear in this description. That is, for the phone number example above, the description might say whether the TYPE filter will work on phone number information or on names. [See 5.3 for an example of the SETUP REPORT screen showing the descriptions.]
The last two questions on this screen (Index name and Instructions) determine how the user may specify his filter values. You may enable one or both of two methods.
If the filter field corresponds to an indexed element, you may enter the index name in the first blank. This will let the user specify that if he has used that index to gather his report population and the report includes this filter field, then the filter should be set to match whatever search value he used.
For example, if this student file has a QYY index, the user can specify that a report should use the QYY search value as the filter value in filtering the course structures. A different QYY search would then produce a different effect in the report.
This kind of filter specification is particularly useful for reports that are likely to be produced many times, with different populations. In many cases, the changing search criteria to gather the different report populations can also serve to provide the filtering criteria.
In addition (or instead) you can provide a place where the user can type in a specific value to be used for the filter. This technique will be useful for people who want to create reports designed for one specific population, where most or all of the report specifications are static. The user might be able to specify in SETUP REPORT the exact search to gather the report population and the specific filter criteria appropriate for the report.
The text you supply under "Instructions" gives the user guidance in choosing the specific value to enter to achieve the desired result.
[See 5.3 for an example of how users are presented with these two choices.]
If the user enters a truncated value for the filter (e.g. "stan#"), Prism will use the PREFIX operator in the SET FILTER statement that it prepares internally:
SET FILTER FOR DONATION.STR WHERE LOCATION PREFIX STAN
If your filter is associated with an index, and the index is a word index (VALUE-TYPE = WORD in your file definition) then Prism will use the WORD operator in SET FILTER statements:
SET FILTER FOR DONATION.STR WHERE LOCATION WORD BANK
This would have the intended effect for LOCATION values such as "Stanford Blood Bank" or "Bank of America".
One filter choice by the user might result in multiple SPIRES filters in some circumstances. Specifically, when there are multiply-occuring elements/structures on the structural path between the field element and the filtering element, Prism will set multiple filters. For example, consider this situation:
DEGREE.STR;
DEGREE = PHD;
MAJOR.STR;
MAJOR = E51;
ADVISOR = Smith, John;
DEGREE.STR;
DEGREE = AB;
MAJOR.STR;
MAJOR = D11;
ADVISOR = Doe, Mary;
MAJOR.STR;
MAJOR = D10;
ADVISOR = Green, Jean;
In XSETUP FIELDS, you might define a MAJOR filter so that the filter is set on the DEGREE.STR structure instead of on MAJOR.STR:
_________________________________________________________________
Students XSetup Field
STUDENTS: Field COURSE NUM, Filtering Information
-----------------------------------------------------------------
Field MAJOR, from structure MAJOR.STR, element MAJOR
Prism should set filter for DEGREE.STR________________________
Filter description: Students with a specific major____________
__________________________________________
:
:
2) Instructions to show when user is prompted ...
Enter a major code if you want to see information only about__
that major and the degree associated with the major.__________
______________________________________________________________
_________________________________________________________________
With this filter definition, if a user chooses the MAJOR filter and enters "D11" as the filter value, Prism would generate this command:
SET FILTER FOR DEGREE.STR WHERE MAJOR = D11
and also:
SET FILTER FOR MAJOR.STR WHERE MAJOR = D11
Once a field has been installed in your application, end-users will "store" that field as part of their personal setup for sorting or reporting. This means that once a field has been installed in production, you need to take great care before removing the field, in order that sorting and reporting function smoothly for users.
As a precaution, XSETUP FIELDS gives you a warning error if you mark a field for removal that is currently part of an end-user's setup for reporting or sorting. Likewise, it will give you a warning error if you remove an account or group from the list of accounts allowed to see a field, whenever that removed account is currently using the field. These are warning errors only, so you will still be able to remove the field -- but it's advisable to notify your users before removing a field that they might be depending on. (Or it might be worth reconsidering whether it should be removed at all!)
To help you keep track of the accounts that are using your fields, Prism Profile provides a pre-defined report called CHECK FIELDS. It's a good idea to run this report before removing your fields, so you can get in touch with the users who will be affected by the removal.
1) COMMAND> prism//select prism profile <--chained commands 2) YOUR RESPONSE: report check fields <--to bypass report menu
The report is for printed output only (i.e., online display is not permitted). After choosing the report from the menu, you issue the PRINT command. The report asks you for your print parameters, then prompts for the file-id (or Prism-id) of the application for which you want a listing of fields currently in use. For instance, to find out whether end-users are relying on any fields in the application with file-id Testprofile:
Enter the Prism file ID for which you want a report: Testprofile______
The resulting printed output looks something like the abbreviated example below.
CHECK FIELDS Report for <application name>
Fields used for Personal Reports and SETUP SORT
Field Accounts Printing field Filter field Field Used
Name Using in these in these in SETUP Sort
Field Reports Reports
-------------- -------------- -------------- -------------- -------------
ABBREVIATION GZ.ABC MONTH.END
HE.MAN NEWTOTALS
REGION FI.SHY Yes
YEAR GO.CAR CURRENT CURRENT
In this example, CHECK FIELDS indicates that several users have included fields either in Personal Reports or in SETUP SORT within your application. You should contact these users before removing fields that they have used.
If you remove fields that have been used in SETUP SORT, the users' search results will no longer be sorted (even if their SETUP SORT still includes valid field names as well as newly-invalid ones). When the user goes to the SETUP SORT screen, the invalid field names will still be listed, but he will be required to remove the name before completing the transaction.
If you remove fields that have been used in Personal Reports, the user will still be able to set the report and even display it, as long as the he still has access to the filedef element that was associated with the field. The reason for this is that when Personal Reports are defined, a copy of the field definition is associated with the report definition (in an internal, compiled form). But the user will run into difficulties when he tries to modify the Personal Report layout that includes the now-invalid field. At that time, he will get error messages within SETUP REPORT indicating that the field name is unrecognized. (Of course, the user may simply remove the field name from his report definition, in response to the error messages.)
From the end-user's standpoint, Prism help records are the screens of explanation that show up in Prism whenever he or she types HELP. From the application developer's point of view, each Prism help record is an individual record stored in a SPIRES subfile called PRISM HELP. Your file's welcome screen (the screen end-users first see when they select your file in Prism) is also a help record stored in this same SPIRES subfile.
Most Prism help records cover general activities such as how to search in Prism or how to do data entry. These explanations are available to all Prism users, no matter which file they have selected. These general help records are maintained by staff in the Data Center as an essential part of Prism. This general Prism help exists as a underlying base for the online documentation of your application.
However, users also need explanations of features specific to your file, such as descriptions of your search types or entry forms, or suggestions for how to accomplish certain tasks. You must write and install these file-specific help records yourself.
Help records are an essential part of your application, because they provide assistance when end-users need help about how to do a particular task in your file. It's also important to follow the guidelines in this document about which help records to provide, so that users can successfully request the same kind of help, no matter which Prism file they are working in.
Every Prism file needs to have the following file-specific help records:
- A welcome screen, displayed when the end-user selects the file. (Sometimes a screen processing step can substitute for a welcome help record.) [See 9.]
- A help record describing the file, so that users can type HELP <file-name>, either before or after they select the file. Note that the default message-line message shown when a user selects a file instructs him to ask for this help!
- A help record describing each search type in the file.
- A help record describing each additional display besides BRIEF and FULL in the file and, optionally, a context help for each display.
If your file supports reporting and/or data entry, you must create additional help records besides the ones listed above. These are summarized at the end of this chapter and described in detail in later chapters. [See 10 for report helps, 11 for entry helps, 9 for helps for other input screens.]
See the back of this manual for an appendix summarizing required Prism helps. Even more useful is the HELP LIST report available in the Prism Profile file. The HELP LIST report provides a checklist of all recommended help records for your application, based on information installed in your file profile about the indexes, reports, entry forms, etc. in your application. The report is particularly helpful because it lists the actual keys of the help records recommended for your application, as well as a notation if the help record already exists in the Prism help file.
To produce the report, issue these commands in Prism:
YOUR RESPONSE: select prism profile YOUR RESPONSE: report help list YOUR RESPONSE: find fileid <your file-ID> YOUR RESPONSE: display report
The person installing a Prism application may request to receive reports of all unsuccessful HELP commands issued in your application. That is, anytime a user types HELP (either with or without a term following) and Prism does not find a help record to satisfy the help request, an entry is generated in the Prism log. This report summarizes all these log entries for you. You could use this report to see what help terms users expect in your application (but which you did not anticipate). Based on the report, you might add new help records or add new aliases to existing helps.
It is this question in the profile that provides the report:
Enter the electronic mail address if you want to receive nightly reports of
helps requested but not found: ________________________________________
Use the XSETUP PROFILE command to request the report, if it was not already requested when your application profile was first created. Note that the report may be sent to an e-mail address other than the one for system error reports.
Prism automatically provides several file-specific help records for every application in Prism:
- A list of search types in the file, accessible by typing "HELP INDEXES IN THIS FILE".
- A list of additional displays (if any) -- HELP DISPLAYS IN THIS FILE.
- A list of reports (if any) -- HELP REPORTS IN THIS FILE.
- A list of entry forms (if any) -- HELP ENTRY FORMS IN THIS FILE.
- A list of report fields (if any) -- HELP REPORTING FIELDS IN THIS FILE.
- A list of sorting fields (if any) -- HELP SORTING FIELDS IN THIS FILE.
The lists in these help records are created from information in your application's profile. You do not have to do anything in order for these helps to be available. If your application does not have any of these features (e.g. if it has no reports) the help record contains a sentence to that effect.
Prism also provides helps for an individual user's current search, and for his Personal Reports and Personal Searches:
- HELP CURRENT SEARCH
- HELP <Personal Report name> REPORT
- HELP <Personal Search name> SEARCH
The helps for Personal Reports and Personal Searches contain descriptions of the report and search definitions. As with the helps described above, you do not have to do anything in order for these helps to be available to users of your application.
Besides the required helps listed earlier, you may want to create help records describing other general features of your application. For example, it might be useful to explain how to perform certain tasks supported by your file, such as "Compiling Statistics from this File".
End-users also find it helpful to be able to find explanations of terms or labels used in your displays or entry forms. For example, if the term "commodity code" appears on your entry forms, you might create a help record accessible by typing "HELP COMMODITY CODE". It's useful to provide an explanation and/or list of any coded values used in your application.
There are two types of help records in Prism: context help and term help (also sometimes referred to as topical help or qualified help). Context help screens are those that are seen when a user simply types the word HELP (or presses the f1 function key or types "?") and asks for assistance for what he was just doing or looking at. Term help records are those that are seen when a user types HELP followed by some term, e.g. HELP NAME INDEX.
There are many different "contexts" defined in Prism. In each context, a particular context help record is applicable. In the PRISM HELP subfile, context help records are those that have a key (or alias) beginning with a question mark. (The PRISM HELP subfile is described in the next section.)
Many context helps are part of the general Prism help system, and you don't have to worry about them at all. However, in many situations, Prism looks first for file-specific help records to serve as context helps. In fact, Prism usually uses a "hierarchy" to determine which help to look for first. In general, Prism looks first for the most specific help applicable to the user's situation. This is often a file-specific help record. If that help record is not found, then Prism usually presents a general Prism help record (which is perhaps less helpful than a file-specific explanation would have been).
The effectiveness of the Prism help system for users is very much dependent on your providing a complete set of file-specific help records so that most queries can be answered with the HELP command.
The easiest and most efficient way to create and maintain your help records is with the XSETUP HELP command. While you have your application selected (the one for which you want to create help records) type XSETUP HELP. You will see a screen similar to the one following, giving you a choice of tasks as well as an alphabetical list of existing help records for your application (if any).
___________________________________________________________________________
United States XSetup Help 12/13/89 13:08
Select Function
---------------------------------------------------------------------------
_ <-- Type the number of the function you wish to perform (1-3)
1. DEFINE a new HELP record
2. MODIFY an existing HELP record
3. REMOVE an existing HELP record
__ <-- For MODIFY or REMOVE, type a number from the list below.
1. ?INPUT/FORM/UPDATE/UPDATE
2. ?INTRO/REPORT/CAPITALS
3. ?WELCOME
___________________________________________________________________________
If you choose to modify a help record, Prism retrieves the requested help record, puts it in your active file, and pauses to let you make the modifications:
-HELP record STATES:?WELCOME is in your active file -Make your changes, then type GO to resume -To cancel HELP modification, type CLEAR ACTIVE and then GO Command>
When you type GO, Prism updates the help record and returns you to Prism where you left off. As the message indicates, if you change your mind about modifying the help record in your active file, simply type CLEAR ACTIVE before typing GO.
Similarly, to add a new help record with XSETUP HELP, Prism pauses to let you type the help record into your active file. Then when you type GO, the record is added and you are taken back into Prism.
All Prism help records are stored in the SPIRES subfile called PRISM HELP. It is possible to create and maintain your help records outside of Prism, in native SPIRES, by selecting PRISM HELP. In fact, prior to December 1989 (when the XSETUP command was introduced) you were required to maintain help screens outside of Prism. [See 6.2.4 to learn how to use the PRISM HELP subfile in SPIRES.]
When composing the text of your help records, you must follow a few specific formatting rules. The first line must contain an asterisk in column one, followed by a blank space in column two, followed by the help term (the word or phrase for which help is offered) starting in column three. The help term is the key of the help record in the PRISM HELP subfile: e.g., STORES ORDERS FILE or DEPT INDEX.
* HELP TERM <--asterisk required
in column one
text (79 columns maximum)
:
:
:
(18 lines per screen, except for welcome and intro
screens, which are 15 lines)
When modifying a help record via XSETUP HELP (or when you TRANSFER a help in SPIRES), you will see this line at the end of your help:
$END OF RECORD
Prism places that control line automatically, so that the end of a help record can be recognized in some standard SPIRES updating operations. [See 6.2.4.] You don't have to type that line in new helps that you create. When modifying helps, you can simply ignore the line (except that it should remain as the last line in the help record).
For best results use Page WYLBUR to type your help records. Set your VIEW screen to be unnumbered, and set your margins to 79 columns, e.g. by issuing the WYLBUR command SET VIEW UNNUMBERED MARGIN=79. With these settings you will get an accurate idea of how the help records will look in Prism.
On standard 24-line terminal screens, there are 19 lines available in the data area to display help text. It's recommended that the second line of your help record be a blank line, to create a blank line at the beginning of the online help display. That leaves 18 lines for the text of your help record.
You may create multi-screen help records if necessary, although you're encouraged to limit most help records to one screen in length. Users often miss the online cues that signal that a help record continues to a second or third screen, and so they might miss valuable information. Consider breaking longer help text into several one-screen help records that refer to each other, as an alternative to creating one multi-screen help record covering multiple topics.
The online "page breaks" for your help records will occur every 19 lines. You may control where these page breaks occur by including a $PAGE control word in your help record. For example:
* HELP TERM
[1st line of text]
:
[16th line of text]
$PAGE
[1st line for the 2nd screen]
:
[See 6.3 for a discussion of other control words for help records.]
The accounts listed in your application profile as authorized maintainers of "all Prism records" for your application are allowed to use the XSETUP command in the application. Accounts listed as help maintainers only may use XSETUP HELP, but not the other varieties of XSETUP.
XSETUP HELP provides maintenance access to help records stored under the file-id of the application where the command is issued, of course. But you may also use XSETUP HELP to maintain help records shared between applications, if the current file-id is stored in a $XFILE statement in the help record. In other words, XSETUP HELP provides access to any help record that is accessible in the application, no matter which file-id it is stored under. [See 6.3.8 for information about $XFILE.]
As shown in the earlier example, if you simply type XSETUP HELP, you will be presented with a list of all existing help records for your application. As a shortcut, you may type XSETUP HELP followed by a help term to tell Prism that you want to modify that specific help record. For example, XSETUP HELP ?WELCOME means that you want to modify your welcome screen.
If the help term you specify in your XSETUP HELP command is not unique, you'll be shown a menu to choose from. This menu is constructed from both IDs and aliases in help records. The menu includes a note if the help term happens to be an alias in a help record. [See 6.3.1 for information about help aliases.] For example, here's what the menu might look like in response to the command XSETUP HELP ?INDEX:
_________________________________________________________________________
Prism Profile XSetup Help 12/16/89 13:40
Select a function
-------------------------------------------------------------------------
_ <-- Type the number of the function you wish to perform (1-3)
1. DEFINE a new HELP record
2. MODIFY an existing HELP record
3. REMOVE an existing HELP record
_ <-- For MODIFY or REMOVE, type a number from the list below
1. ?INDEX/ACCOUNT [Alias in ACCOUNT INDEX]
2. ?INDEX/FILEID [Alias in FILEID INDEX]
3. ?INDEX/NAME [Alias in NAME INDEX]
4. ?INDEX/PC [Alias in PC INDEX]
_________________________________________________________________________
The list of help records shown when you simply type XSETUP HELP consists of the IDs (keys) of your help records only and does not include any aliases. That is, there is only one entry in the list for each of your help records.
However, you can use any help term, whether it is an ID or an alias, in your XSETUP HELP command, e.g. XSETUP HELP NAME INDEX in order to work on the help record for "NAME INDEX".
Although the XSETUP HELP menu does not explicitly include a "derive" function, you can indeed base a new help record on an existing one. To do so, choose the "modify" function for the help record that is similar to the new one you want to create. Then, when you are working with the help record in your active file, change the key of the record as well as making your other modifications. When you type GO, Prism will ask an additional question to verify that you really want to add a new help record:
-Help name is changed: from ?INPUT/FORM/UPDATE DEPT/UPDATE to UPDATE DEPT FORM Add this as a new help record? (Yes/No)
If you answer "yes" the new help will be added, leaving the original help record unchanged.
As mentioned earlier, all Prism help records, are stored in the SPIRES subfile called PRISM HELP. In most situations, it is easy, convenient, and efficient to maintain your help records with the XSETUP HELP command in Prism. However, it is also possible to work with your help records outside of Prism, in SPIRES.
Even if you do most of your help maintenance with XSETUP HELP, you may find the following tasks (available only in SPIRES) useful:
- Searching for and displaying help records other than your own (general Prism help records or helps used in other applications).
- Preparing reports about your help records, e.g. with $REPORT.
- Removing several help records at once (rather than one by one via XSETUP HELP).
- Using the INPUT ADDUPD command to add or modify a batch of help records at once.
- Working with help records for two or more file-ids at once.
When you select the PRISM HELP subfile, you will be asked to enter the file-id of a Prism file whose help records you are authorized to maintain.
> spires <--(Command issued outside Prism)
:
-> select prism help
-Enter your Prism file's file-id (press RETURN for help)
:File-ID? pevents
->
Note: In order to select PRISM HELP at all you must have help maintenance privileges for at least one Prism file. That is, your account must be listed in a Prism profile record, even if it's a simple, incomplete profile.
As a shortcut, to bypass the "File-ID" prompt, you can include the file-id in your SELECT command:
> spires
:
-> select prism help, pevents
->
The file-id that you enter when you select PRISM HELP determines which help records you may add and update. But you can look at help records for all Prism files, as well as the general Prism help records.
Type SHOW INDEXES to see the available indexes. The HELP index lets you search by words in the help terms (record keys and help aliases). The FILEID index lets you retrieve help records by the file-id of the application to which they belong. (Note: PPRISM is the file-id used for the general Prism help records.) Examples of searches:
-> find help date <-- retrieves helps with "date"
as part of the key or alias
-> find help date index and fileid pevents
-> find fileid pprism <-- retrieves all general Prism
help records
When you have composed the text of your help record, use the ADD command to add the record to the PRISM HELP subfile. Likewise, use TRANSFER and UPDATE to make modifications to help records created earlier, or the REMOVE command to remove help records. [See 8.6 for information about removing all your helps, as part of removing an entire application from Prism.]
When you add or update help records, the PRISM HELP subfile automatically adds your specified file-id as a prefix to the key of the help record. This file-id prefix ensures that the records are associated with the appropriate Prism file.
Technically, the key of each help record actually includes the file-id. For example, the key of the Public Events welcome screen is not ?WELCOME but PEVENTS:?WELCOME. However, when you specify help records by key with TRANSFER, DISPLAY, and REMOVE commands, you do not need to include the file-id. For example, if you specified a file-id of PEVENTS when you selected the PRISM HELP subfile, you would type TRANSFER ?WELCOME to transfer the welcome screen into your active file for modifications.
You may include two file-ids in your SELECT command if you wish to maintain help records for two applications (for example, a test and production version of an application) without having to reselect the file for the different file-ids:
> spires : -> select prism help, tevents/pevents ->
If you have specified two file-ids, you must work with full and complete help keys, including the file-id, e.g.
-> tra pevents:?welcome
or
-> dis tevents:public events file
When typing a new help in your active file, include the file-id and colon in the first line with the help key:
* tevents:?welcome
Note that when you are doing Global FOR operations, you only have access (in effect) to helps for the first file-id of the pair you specified. For example:
-> select prism help, tevents/pevents -> find fileid pevents or tevents -Result: 20 HELPS -> for result +> remove all <-- this would only remove TEVENTS (1st file-id) +> Removed: 10 record(s)
One situation in which you might need to work with help records for two file-ids is when you have helps for a test and production version of an application. The following example illustrates a technique for easily migrating all of your test help records to production.
-> select prism help, tevents/pevents -> find fileid tevents -Result: 10 HELPS -> for result +> in active display all +> endfor -> change 'TEVENTS' to 'PEVENTS' -> input addupd
Of course, the changes you make to the batch of help records in your active file could be more extensive than simply changing the file-id. The $END OF RECORD separator between help records ensures that the INPUT ADDUPD command will work to add and update the batch of helps.
Another subfile, PRISM HELP MAINT, lets you work on helps for any number of your applications, without having to re-select the subfile for each application. When you select PRISM HELP MAINT, you are not asked for a file-id at all. As described above, you must include a file-id when you name the key of a help record, or when you work with the text of the help record.
No format is set automatically when you select this subfile. Type SET FORMAT FULL to work with formatted helps as you're used to with the PRISM HELP subfile or XSETUP HELP.
-> select prism help maint -> set format full
In some cases, you may be able to base one of your new help records on an existing help (either for your file or for some other file). For example, the search FIND HELP NAME INDEX will retrieve help records that already exist for NAME indexes in various Prism files. The command IN ACTIVE TYPE will put the record(s) in your active file, where you can modify it until it meets your own needs. You can then add it as a new record for your own Prism application.
It's a good idea to look at your help records in Prism, to make sure they are formatted the way you want. If you are maintaining helps with the XSETUP HELP command, this is quite easy, since you remain in Prism to do your work. But if you are working in SPIRES, you can see a simulation of what the Prism help record looks like by using a display format called BOX.
For example:
-> USING BOX DISPLAY <help-record-key>
This display is fairly close to what you see in Prism (but not identical). In particular, the BOX display lets you see the effect of the $BOX and $LINE control words.
Prism offers some useful control words to help you format and customize your help records. The control words don't actually appear in the help record when end-users see it in Prism, but instead give Prism instructions on how the record should be displayed or accessed in Prism.
Each control word is prefixed with a dollar-sign (for instance, $ALIAS) -- and the control word always begin in column one of the line where it appears. The next pages describe each control word in detail.
The $ALIAS control word makes a single help record accessible by more than one term or phrase. For example, if you wanted a user to be able to call up a help by typing either HELP HOUSING CODES or HELP BUILDING CODES, you could add the record with BUILDING CODES as its key and a $ALIAS of HOUSING CODES (or the other way around).
* BUILDING CODES <----- either HELP BUILDING CODES
$ALIAS HOUSING CODES <---- or HELP HOUSING CODES
text invokes this screen
:
Prism matches word stems when processing a user's HELP command. For example, all of the following commands would retrieve the help record shown above: HELP BUILDING, HELP HOUSING, HELP B CODE, HELP HOUS COD. For this reason, you shouldn't add aliases with identical stems. That is, for the record shown above, it is not necessary to add $ALIAS BUILDING.
This section describes how Prism presents HELP menus to users and why you should give some thought to which help term you use as an alias and which you use as the key of the help record.
When a user types HELP followed by a term, Prism will present a menu of choices, if there are multiple helps matching that term. For example, there are quite a few help records about displaying, so if you type HELP DISPLAY, you'll see a menu similar to this:
To choose a help, type its number below and then press RETURN 1. DISPLAY COMMAND 2. DISPLAY CURRENT COMMAND 3. DISPLAY FULL COMMAND 4. DISPLAY REPORT COMMAND 5. DISPLAYING DATA 6. DISPLAYS IN THIS FILE
The entries in this list come from both the main help terms (the keys of help records) and aliases.
Consider a help record with these help terms:
* BUILDING CODES $ALIAS HOUSING CODES $ALIAS BUILDING SIZE CODES
If a person types HELP BUILDING, you might expect Prism to show two choices from this help record (BUILDING CODES and BUILDING SIZE CODES). But since both of those help terms point to the same help record, Prism would only use one term when deciding whether a HELP menu is needed, in many cases (the exception is explained in the next paragraph). If a HELP menu is needed (e.g., if there were also other helps with names starting "building") Prism will first choose to show the key of the help record in a HELP menu (assuming that the key is one of the terms that would go in the list). Otherwise, the first help term alphabetically will be used.
What does "in many cases" mean? Well, Prism is smart enough to choose only one help term for a given help record if the candidate terms fall next to each other alphabetically. But if there is an intervening term from a different help record in the alphabetical list, then the redundant entries on the menu are not weeded out.
The main point of this long explanation is that you should give some consideration to which term you use as the key of the help record and which you use as an alias. Prism does display the main term (the key) in preference to an alias in some cases. [See 6.3.5 for another example of when Prism uses the key instead of the alias.]
$BOX allows you to draw boxes in your help records, using your terminal's ruling font to align it correctly. For instance, the $BOX lines below will draw a box with left margin at column 1, right margin at column 21, and "height" great enough to surround the lines of text typed between the control words.
$BOX 1 21 1...+....0....+....0.
Line the first PRODUCES-> ____________________
Line the second |Line the first |
$BOX END |Line the second |
|__________________|
As shown above, $BOX is always used in a pair -- a $BOX line to specify the starting and ending columns for the box, and a $BOX END line to specify the end of the box.
Be careful not to place text at the "edge" of a box. For example, if your box starts in column 1, don't start the text until column 3.
$BOX and $LINE (described next) use up physical lines, whereas the other control words do not in themselves affect the length of help records. So when you are counting lines to figure how long a help screen will be in Prism, remember to include any $BOX and $LINE lines.
If you are maintaining your help records in SPIRES (rather than via XSETUP HELP) you may use the BOX display to see the effect of the $LINE (and $BOX) control words. For example:
-> USING BOX DISPLAY <help-record-key>
The $LINE control word lets you draw unbroken horizontal lines in your help records. $LINE can help you format your help record when a box would take up too much space or draw too much attention to itself. For instance, to draw a line across the 79 columns of the screen enter this line:
$LINE 1 79
The lines can be of any length. The numbers after $LINE refer to the starting and ending columns of the line. For example, to draw a line on the right half of the screen only: $LINE 41 79.
$LINE, like $BOX, takes up physical space in your help record. Count it as an extra line when checking your record's length.
If you are maintaining your help records in SPIRES (rather than via XSETUP HELP) you may use the BOX display to see the effect of the $LINE (and $BOX) control words. For example:
-> USING BOX DISPLAY <help-record-key>
The $ELEMINFO and $INDEXINFO control words let you bring ELEMINFO and INDEXINFO descriptions from your SPIRES file definition directly into Prism help records. These SPIRES-derived explanations can be surrounded by newly-written text expanding the explanation and making it more relevant to Prism.
$ELEMINFO and $INDEXINFO control words should be followed on the same line of the help record by the name of the element or index to which they apply. (Neither of these control words can be used inside a box.) Upon output, each occurrence of the element or index information will start in column one, wrapping to a new line if necessary.
For example, this help record...
* CUISINE INDEX $INDEXINFO CUISINE
would produce something like the following display in Prism:
_______________________________________________________________ CUISINE INDEX Type of food (e.g. French, Chinese, etc.) _______________________________________________________________
Note that you need to provide your own blank lines above and below the added text; $ELEMINFO and $INDEXINFO do not provide them.
The $CATEGORY control word causes a help record to be listed in the HELP TOPICS screen in Prism. HELP TOPICS is an important help record in Prism. It provides users with a categorized menu of the different topics for which help is available at that point in their terminal session.
When users learn about Prism, they are taught to type HELP (or press the f1 function key) whenever they need help about the screen they are on. This takes the user to the HELP TOPICS screen. (This screen is always accessible by typing HELP TOPICS too.)
Here's an example of what the HELP TOPICS menu looks like:
Choose the help you need by typing a number from the list below:
1. Help for the report you have chosen
2. General help about where you are and what you can do next
3. Help about HELP
More information about the United States file
4. Searching in this file...
5. Displaying data in this file...
6. Entering data in this file...
7. Reporting in this file...
8. Other information about this file...
More general information
9. Printing, downloading, or mailing data...
10. General instructions for using Prism...
Each of the categories numbered 4 through 9 leads to a menu that lists both general Prism help records and file-specific records for your application, provided they contain a $CATEGORY control word designating one of the following categories:
$CATEGORY Searching $CATEGORY Display $CATEGORY Entry $CATEGORY Reporting $CATEGORY Other $CATEGORY Printing
It's strongly recommended that most or all of your help records (except your context helps) include a $CATEGORY control word, so that they will be included in HELP TOPICS. The effectiveness of HELP TOPICS depends largely on whether it includes a fairly comprehensive list of file-specific help records to complement the general Prism help records.
For example, to have a help record about the SUMMARY display for your application appear in the "Displaying data..." section of HELP TOPICS, add this control word to the help record:
* SUMMARY DISPLAY $CATEGORY DISPLAY text :
One help record may appear in several categories, if applicable. Separate multiple categories by commas: $CATEGORY DISPLAY, REPORTING.
If the help record includes $ALIAS help terms, note that the help term in the key of the record is the term that will be used in the HELP TOPICS menu. Keep this in mind when deciding which help term to place in the record key and which to use with $ALIAS.
Note: You cannot add the $CATEGORY control word to a help record whose key begins with a question mark (which designates it as a context help record). To get around this limitation, assign the help record a key with a regular help term and include the context help term as an alias. For example:
* SUMMARY DISPLAY $ALIAS ?DISPLAY/SUMMARY $CATEGORY DISPLAY text :
Note: Prior to the summer of 1988, the help record with the key of ?TOPICS determined which help terms were listed on HELP TOPICS. The ?TOPICS help record is now obsolete and is not required (it is not used by Prism at all). The function of ?TOPICS has been replaced with the $CATEGORY control word.
The $BIND and $XBIND control words associate help records with a particular display, report, or entry form. This means that when a user types HELP followed by some term, Prism will first look for help records matching the user's help command, that are associated with his or her current display, report, or entry form. This ensures that a user is first presented with help that is most specific to his or her situation.
For example, say that a screen of your entry form has a field labeled "ST:". You might write a help record with the key of ST FIELD to provide an explanation of what's supposed to be entered there. If you add the $BIND control word to this help record, when a user in that entry form types HELP ST, he will be presented with that help (or with a menu listing any other helps with help terms starting "ST" that are "$BINDed" to that entry form). Without $BIND, when the user types HELP ST, he will get a menu of all help terms starting with "ST" (which would probably be an overwhelmingly long list).
$XBIND is similar to $BIND, except that it marks a help record as exclusively bound to a display, report, or entry form. If the user is not actually using the display, report, or entry form to which the help applies, then the help is not accessible at all to the user.
That is, a help record with $XBIND is exclusive to a particular context and is not available at all if the user is outside of that context. A help record with $BIND is presented first in a given context, but is also available at other points in the application.
To specify $BIND or $XBIND, add a control statement like this:
$BIND <context> <object-name>
or
$XBIND <context> <object-name>
where "<context>" is either DISPLAY, FORM, or REPORT, and "<object-name>" is the name of the display, report, or entry form to which you want the help record bound.
Using the ST example from above:
* ST FIELD $BIND FORM MICRO ORDERS text :
Here, the ST FIELD help record is bound to the MICRO ORDERS entry form.
In order for binding to work, you must also have provided a context help for the display, entry form screen, or report. For example, in the sample above, you must have a context help for the input screen in the MICRO ORDERS entry form on which the ST field appears, in order for the binding to work.
You may include multiple $BIND or $XBIND statements in one help record, if the help is applicable to several different "objects". You may not have both $BIND and $XBIND in the same help record, however.
Currently, you cannot use $BIND or $XBIND for help records relating to an input screen presented at file selection time.
And the binding specified with $BIND FORM and $XBIND FORM only works within an entry transaction (i.e. after CREATE or GET command is issued) and not when an entry form is simply selected.
The $COMMENT control word lets you record comments in the help record. These comments will not appear when the help record is displayed in Prism, but are only visible when you are looking at the record in the PRISM HELP subfile. $COMMENT is useful to provide internal documentation or instructions, particularly if several different people may be maintaining helps for your application.
$SUBJECT lets you include an internal search term for a help record. These terms are indexed in the SUBJECT index in the PRISM HELP subfile. These search terms might be useful to organize your help records into meaningful groups, or to make it easier to find a particular record in PRISM HELP at a later date. Note that $SUBJECT search terms have no effect on how the help record is accessed from within Prism; they only apply to the SUBJECT index in PRISM HELP.
Here are examples of $COMMENT and $SUBJECT:
* HOW TO PRODUCE STATISTICS FROM THIS FILE $ALIAS STATISTICS $COMMENT Related help: YEAR END PROCESSING $SUBJECT yearend text :
The $XFILE control word lets you share a help record between several different Prism applications. For example, if you are responsible for helps for both a production and test version of a file, you can maintain one set of helps only and include $XFILE to make those helps accessible to the other file.
* DEPT INDEX $ALIAS DEPARTMENT INDEX $CATEGORY SEARCHING $XFILE FISCALX text :
In this example, the DEPT INDEX help will be accessible in the file with file-id of FISCALX, as well as in the file for which it was originally created.
Note that the XSETUP HELP command lets you maintain all help records for an application, whether they were created under the application's file-id directly or whether the $XFILE control word makes them accessible to the application.
Rather than including $XFILE in each help to be shared between applications, you can specify once in the application's profile that help records stored under a different file-id should be used for the application. It is this question in the profile that accomplishes the task:
Alternate file-id for help records: ________________
Use the XSETUP PROFILE command to add this alternate help file-id to your application profile.
Even if you've specified an alternate file-id for help records, you can still create help records under the "main" file-id. In processing HELP commands, Prism will look first for helps stored under the primary file-id and then at helps stored under the alternate file-id. (If the same help term is in both places, the help record under the primary file-id will take precedence.)
The $FRAME control word allows a help record to invoke a frame in a SPIRES format, in order to supply dynamic information based on variables or do processing not possible in a normal help record.
The syntax of the control word is:
$FRAME frame-name [IN format-name] [HEADER <frame-name>] [PARM <literal>]
If you omit the "IN format-name" option, Prism assumes the frame is in your display format. The format containing the frame may be any format defined against the file's primary goal record, or a general file format.
The FRAME-TYPE must be XEQ, and it must place its data starting on row X or row *+1.
Put the $FRAME statement where you want the format-supplied text to appear in the help record. For example, this help record combines text in the help record with text from a format:
* DIRECTORY OF CONSULTANTS Use the following list to figure out who to call when you have a question: $frame consultants
The HEADER option names a frame to generate a header for the help screen. The header is executed whenever the help display enters screen overflow processing. As for a FULL display header, you must cause the header frame to be executed if you want it to appear on the first page of the help. [See 3.3 for information about FULL display headers.]
The <literal> after the PARM option will go into the $PARM variable, for use in the named format frame.
To trace execution of your help format frame, use the debugging command SET FTRACE HELP ftrace-options. [See 7.4.3.]
The $CONTEXT control word generates sentences about the user's current context in a Prism session, e.g. the current search or the currently-selected report. $CONTEXT has several options:
$CONTEXT FILE the currently selected file
$CONTEXT SEARCH1 the user's current search (or previous search, in
some circumstances); truncated if longer than 1 line
$CONTEXT SEARCH2 same as SEARCH1, except truncated after 2 lines
$CONTEXT RESULT the user's current (or previous) result
$CONTEXT DISPLAY the display the user was viewing last
$CONTEXT ACTIVITY the entry form or report that's currently selected
Here are examples of the lines of text that are generated by the various $CONTEXT control words.
$CONTEXT FILE
Your selected file: United States
$CONTEXT ACTIVITY
Your entry form: REQUISITION (SNAP Purchase Requisition)
Your report: PHONE LIST (List of names, work locations, and work phones)
$CONTEXT SEARCH1
Your search: DEPT CONTROLL#
Your search: you do not have a search result
$CONTEXT RESULT
Your result: 5 records
Your result: 5 records (sorted by REGION, NAME)
$CONTEXT DISPLAY
You were looking at record 3, using the FULL display.
You were looking at the BRIEF display.
$CONTEXT was implemented originally for use in general Prism context help records, so you can find examples by looking at those help records. By convention, in these helps, the $CONTEXT information has been placed inside a box (79 characters wide) at the very beginning of the help record. In some cases, the $CONTEXT lines are supplemented with other text. For example:
these entries at the beginning of the help record ... * ?INPUT.UPDATE $box 1 79 You typed GET and are in the middle of modifying a record in this file. $CONTEXT FILE $CONTEXT ACTIVITY $box end <text of the help record> ---------------------------------------------------------------------------- ... produce this boxed text: *--------------------------------------------------------------------------* | You typed GET and are in the middle of modifying a record in this file. | | Your selected file: SNAP Purchasing | | Your entry form: REQUISITION (SNAP Purchase Requisition) | *--------------------------------------------------------------------------* <text of the help record>
Note that Prism will shift the generated text over so that it fits in a box that starts in column 1 and ends in column 79. However, it is not possible to generate $CONTEXT lines in boxes in other positions or of other sizes.
The $HEADER control word creates a running header for each screen (page) of a long help record. For example, these lines in your help record:
* GL CODES
$HEADER
GL code Meaning
------- -----------------------
$HEADER END
text
text
:
will create a 3-line header at the top of each screen of the help record. Note that you should include a blank line if you want one.
Other control words used in Prism help records are:
- $PRISM, which lets you declare one of your file-specific help records accessible to end-users anywhere in Prism. Currently this control word is only available for the <file-name> FILE help record. [See 6.4.2.]
- $DEBUG in a help record makes that help accessible only when DEBUG is set. You could use it for help designed specifically for other developers. [See 7.]
- $PAGE causes an automatic page break following the point where it occurs in the help record. [See 6.2.1.]
$ALIAS Creates alternate access points for the record
$ALIAS <help term>
$BIND Associates a help with a specific display,
report, or form
$BIND <context> <object-name>
context = DISPLAY, FORM, or REPORT
object-name = name of display, entry form or report
$BOX Creates boxes within help records
$BOX n,n (n = column positions)
text
$BOX END
$CATEGORY Causes a help to be listed on HELP TOPICS
$CATEGORY <category name>
category = searching, display, entry, reporting, other, or
printing
$COMMENT Creates comments for internal documentation
$COMMENT <comment text>
$CONTEXT Generates sentences about user's current context
$CONTEXT <name>
name = file, activity, search1, result, display
$DEBUG Hides help record except when DEBUG is set
$ELEMINFO Adds file definition ELEMINFO to help text
$ELEMINFO <element name>
$FRAME Allows help to invoke an XEQ frame in a format
$FRAME <frame-name> [IN <format-name>]
$HEADER Creates a running header for each screen of a help
$HEADER
header text
$HEADER END
$INDEXINFO Adds file definition INDEXINFO to help text
$INDEXINFO <index name>
$LINE Creates lines within help records
$LINE n,n (n = column positions)
$PAGE Causes page break
$PRISM Makes help record accessible outside your file
$SUBJECT Assigns internal search terms for a help
$SUBJECT <subject terms>
$XBIND Makes a help available exclusively with a
specific display, report, or form and not
in any other contexts.
$XBIND <context> <object-name>
context = DISPLAY, FORM, or REPORT
object-name = name of display, entry form or report
$XFILE Makes help record available in several different files
$XFILE <file-id>
Prism is a very "help-ful" system. When using Prism to get work done, you'll find that Prism gives you help in many different ways:
- descriptive lists of commands to issue, in the guided mode options;
- specific instructions in menus, welcome screens, confirmation screens and occasionally in the message line;
- descriptions and examples in menus, such as the menu of search types (indexes);
- general information in the status lines, such as the name of the file you selected, the number of records in your search result, what search commands you've issued, etc.; and
- a HELP command, available on every screen, which provides more help about your current situation, or leads to general help about other areas of Prism (HELP TOPICS).
Prism doesn't provide all this assistance on its own. The success of the help system depends on you, the help writer -- the person who designs, writes and enters the different pieces of help material for each application.
When a new version of Prism is installed on Saturday, August 13, 1988, the added features will include a revamped help system. This paper will discuss:
- how the new help system will be easier for users to learn, understand and remember to use;
- what help writers, documentation writers and trainers for Prism applications should know about how it works; and
- what help writers need to do to take advantage of the changes.
Note that the changes are entirely upward-compatible; that is, if you do nothing to the help records for your application, the HELP command will work as it did before. However, many applications -- especially larger ones, and those with infrequent users -- will be able to help their users in more sophisticated ways by adding new help records, and new aliases and control words into existing help records, as described later.
Below is a summary of the changes being made to Prism's help system; to be introduced August 13. Most are discussed in further detail later.
INDEXES IN THIS FILE DISPLAYS IN THIS FILE REPORTS IN THIS FILE FORMS IN THIS FILE REPORTING FIELDS IN THIS FILE SORTING FIELDS IN THIS FILE
- For unqualified help, Prism will first look for local context help (i.e., a specific help record, new in most cases). If you ask for HELP again (or if no local record exists), Prism will look for a general Prism record for the current context.
- For qualified help, Prism will look for a "term" help record tied to the current input screen, display, report, etc., via the new control words $BIND and $XBIND. If this isn't the help you were looking for (or if it didn't exist), then Prism will look for a global "term" help record, for either the application or Prism in general.
The next section describes in more detail how the new help system will appear to the user. What the help writers, trainers and documentation writers need to know about help is covered in the sections following that.
Users find that Prism provides them with help in many different forms:
- descriptive lists of commands to issue, in the guided mode options;
- lists of commands to issue (and function keys to press) in the function key and "Also:"
This new feature is a line of additional commands not tied to function keys that can be issued in the user's current situation. It appears directly below the function key line. lines at the bottom of each screen;
- specific instructions in menus, welcome screens, confirmation screens and occasionally in the message line;
- descriptions and examples in menus, such as the menu of search types (indexes);
- general information in the status lines, such as the name of the file selected, the number of records in the current search result, what search commands were issued, etc.; and
- a HELP command, available on every screen, which provides more help about the user's current situation, or leads to general help about other areas of Prism (HELP TOPICS).
When users think of Prism help, they most likely think of the HELP command, available on every screen in Prism. They are constantly reminded of it, due to its ubiquitous presence as the F1 function key. In any situation, they can press F1, or issue the HELP command, and get more help about their current situation.
What Prism shows the user in response depends on where the user is, and how he or she asked for it.
As help writer for a Prism application, you have several ways to take advantage of the benefits of the new help system:
If you want to... then do the following:
- have new or existing help records - add $CATEGORY control words to
show up in the help menus for the HELP records.
various categories of the HELP
TOPICS menu,
___________________________
- have a particular help record for - add new "?INDEX/index-name",
an index, a display or a report "?DISPLAY/display-name" and
come up when HELP is issued from "?REPORT/report-name" records
that context, (or add those names as aliases
to existing records).
___________________________
- tie particular help records for a - add $BIND or $XBIND control words
given topic to a specific input to the HELP records.
screen, report or display,
___________________________
- be able to find your help records - add $SUBJECT control words to the
in the SPIRES subfile PRISM HELP HELP records.
based on keywords of your
choosing,
___________________________
- do nothing at all, - at least remove the ?TOPICS help
record, which is no longer used.
Specific instructions for dealing with each of these tasks are presented below.
When users see the HELP TOPICS screen, they have several different categories of help topics to choose from. The screen will look something like this:
United States Report: REGIONS 08/08/88 08:08
HELP TOPICS
_______________________________________________________________________________
To choose a topic, type its number below and then press RETURN.
Information about your current situation
1. Where you are and what you can do next
2. Help for the report you have selected
Information about the Screen Definer file
3. Searching in this file
4. Displaying data in this file
5. Entering data in this file
6. Reporting in this file
7. Other information about this file
More general information
8. Printing, downloading, or mailing data
-Press RETURN for your earlier display.
YOUR RESPONSE: _
f1=Help f9=Print
This paper discusses the new Prism help system being introduced into production Prism on Saturday, August 13, 1988. Specifically, it discusses how the changes to the way Prism's HELP command works will affect Prism users, and covers what help writers for Prism applications can do to make HELP more useful.
The first change in Prism's new help system that most users will notice is the disappearance of the Options function key (F0). F0 (F10) is now equivalent to DISPLAY in situations where the DISPLAY command is available. The OPTIONS command is still available, though most users will probably find the command they're looking for listed in the function key line or the new "Also:" line of commands beneath it; otherwise, they may find complete option information through HELP.
On color terminals, the second status line changes from cyan to green (this may subtly suggest a window overlaying the current display, since the top line doesn't change). On non-color terminals, the second status line changes to bright.
When you issue a "HELP term" command, Prism will look for the "term" record using stem matching, on a word-by-word basis, just as Prism does for file selection. For instance, HELP A I might find help records for ABBREV INDEX and AVAILABLE INDEXES IN THIS FILE.
Prism will automatically supply some new pre-defined help records for each application, listed below. These will generate lists of all the indexes, displays, etc., available to the user, as defined in the selected application. The new help records are:
INDEXES IN THIS FILE FORMS IN THIS FILE DISPLAYS IN THIS FILE REPORTING FIELDS IN THIS FILE REPORTS IN THIS FILE SORTING FIELDS IN THIS FILE
When a HELP command is issued, Prism will look for "local" help first -- help defined by the application's help writer for a particular context. If no local help exists, or if the user issues the HELP command from there, then Prism will display "global" help of a somewhat general nature for the current context. If the user types HELP again from the global help, the new HELP TOPICS screen will appear (see below).
These levels work for both a "HELP term" command (qualified help) and the HELP command alone (unqualified help).
In general, applications have more opportunities to provide customized help that users will see when they issue the HELP command. Previously, this capability was really available only in the context of entry forms and parm screens; now, it is available for some contexts of reports, displays and indexes as well.
Thus, as help writers begin to take advantage of these new features, users will find that the HELP command becomes a more powerful and useful assistant, providing needed help directly from the HELP command, or appropriate and limited menu choices when a "HELP stem" would otherwise match to many different global help records.
As help writer for a Prism application, you will find several procedures you can follow to make the new help system work better for your application. Remember that the changes won't adversely affect an application in any way; if you do nothing to change your help records from the way they are now, HELP will continue to work the same for your application.
But if you do want the new features to work to your advantage, the various procedures to follow are outlined below:
If you want to... then do the following:
- have a particular help record for - add new "?INDEX/index-name",
an index, a display or a report "?DISPLAY/display-name" and
come up when HELP is issued from "?REPORT/report-name" records
that context, (or add those names as aliases
to existing records).
___________________________
- have new or existing help records - add $CATEGORY control words to
show up in the help menus for the HELP records.
various categories of the HELP
TOPICS menu,
___________________________
- tie particular help records for a - add $BIND or $XBIND control words
given topic to a specific input to the HELP records.
screen, report or display,
___________________________
- be able to find your help records - add $SUBJECT control words to the
in the SPIRES subfile PRISM HELP HELP records.
based on keywords of your
choosing,
___________________________
- do nothing at all, - at least remove the ?TOPICS help
record, which is no longer used.
Specific instructions for dealing with each of these tasks are presented below.
Currently in Prism, help writers can create local context help records for the input screens of an entry form, e.g. to explain some of the terms on the screen, what options are available from that screen, who to call for help, etc. Thus, a user who's perplexed by one of the input screens can issue the HELP command and get the local context record for help.
The new Prism help system extends that technique to displays, reports, and in a special way, indexes. You simply create local context help records (or give aliases to existing help records if appropriate) using the names ?DISPLAY/display-name and ?REPORT/report-name. (As described below, you won't need to do this for indexes if you already have an "index-name INDEX" help record for each one.)
If appropriate, you may instead add these names as aliases to existing help records, rather than create new records or duplicate old ones.
In the current version of Prism, if a user is on the screen that prompts for an index search value, help does not behave consistently. If the user types a "?" or HELP at the prompt for a value (up in the data area), Prism displays the "local context help" which is the "index-name INDEX" help record. But if the user types the HELP command or presses F1, Prism displays its global help, a general description of the screen.
For consistency with the other new context help records, Prism will respond to all these forms of user "input" by looking for the local help record "?INDEX/index-name" first. If it doesn't exist, then Prism will display its own global help.
Tonight, August 9, the DRG will add to all existing "index-name INDEX" records a new alias of "?INDEX/index-name".
Hence, existing records will continue to do double-duty as both the general help for an index and the local context help as well. For context help, Prism will look for the "?INDEX/index-name" record; for "HELP index-name INDEX", it will look for the "index-name INDEX" term record, which will be the same record. By making this conversion now, Prism can someday allow help writers to create separate context and term records without adversely affecting applications that in the past created "index-name INDEX" records that serve as context records too.
Note that after the conversion, no records with a "?INDEX/index-name" key will even be allowed in the file, at least for the time being. After the conversion, any help record added to the file with the key "index-name INDEX" will have the alias added automatically as well.
Incidentally, the "?INDEX/index-name" record will also be available from the HELP TOPICS menu when you have come from the search-value prompting screen. It appears as "Help for the searchtype you were using."
When users see the HELP TOPICS screen, they have several different categories of help topics to choose from. The screen will look something like this:
United States Report: REGIONS 08/08/88 08:08
HELP TOPICS
_______________________________________________________________________________
To choose a topic, type its number below and then press RETURN.
Information about your current situation
1. Where you are and what you can do next
2. Help for the report you have selected
Information about the Screen Definer file
3. Searching in this file
4. Displaying data in this file
5. Entering data in this file
6. Reporting in this file
7. Other information about this file
More general information
8. Printing, downloading, or mailing data
9. General instructions for using Prism
-Press RETURN for your earlier display.
YOUR RESPONSE: _
f1=Help f9=Print
Each of the categories numbered 3 through 7 leads to a menu that currently lists general help records provided by Prism. The menu can additionally list help records for your application if you add the $CATEGORY control word to the records.
The available categories are:
Searching Display Entry Reporting Other Printing
For example, to have a help record about the SSN field appear in both the Reporting and Display menus, add this control word to the help record:
$Category Reporting,Display
Separate multiple categories by commas.
Note: You cannot add the $CATEGORY control word to a help record whose key begins with a question mark, which marks it as a context help record. If you need to do this, it's because the record has a $ALIAS control statement for a term you want to be available in Prism help. So, to circumvent the limitation, make that term the key of the record, and make the context key serve as the alias.
Two other control words for help records, $BIND and $XBIND, make help records for particular terms into local records that Prism looks for first when a "HELP term" command is issued in a given context. For example, you could add $BIND to a help record for a field called "ST" on an input screen. A user on that screen who typed HELP ST would see that help, or a menu listing any other ST-prefixed help that was "$BINDed" to that screen. Without $BIND, Prism would create a menu of all global help that began with ST (including the ST help record), which, in this case, might be overwhelming to a user.
$XBIND works similarly, except that it marks the help record as exclusively bound to contexts; a "HELP term" command that found it in that situation would never find it in general help menus in any other context. You can "$Xbind" the same help record to multiple contexts by specifying the control statement multiple times. The same is true for $BIND. However, they cannot both appear in the same record.
To specify $BIND or $XBIND, you add a control statement that looks like this:
$BIND <context> <object-name> $XBIND <context> <object-name>
where "<context>" is either DISPLAY, FORM or REPORT, and "<object-name>" is the name of the display, form or report to which you want the help record bound.
To make help records easier to find in the PRISM HELP subfile, you can now add $SUBJECT control statements to specify your own subjects. These terms are indexed in the SUBJECT index; you can use normal SPIRES index-searching commands to retrieve your records using your subjects.
Simply add a control statement like this to a help record:
$SUBJECT keywords
where "keywords" is any word or words to be used by you for searching purposes in the PRISM HELP subfile.
For example,
$SUBJECT bound to the FULL display
The "?TOPICS" record is no longer used by Prism; you can remove it from the PRISM HELP subfile. You will probably want to add the $CATEGORY control statement as appropriate to the records named in the "?TOPICS" record, so that those help records will show up in appropriate menus built from the HELP TOPICS menu.
With stem matching of "HELP term" commands, you no longer need many forms of term aliases you may have included previously. For instance, you might have included "ST INDEX" as an alias for "STATE INDEX", with the result that both appeared on help menus. With stem matching, HELP ST INDEX would find a STATE INDEX record, so the alias is no longer needed.
To clean up help menus, you might want to examine the aliases you have created for help records to determine whether the stem matching eliminates the need for them.
As suggested earlier, more changes are possible, and several more are planned. The planned development is in the area of tools for Prism help writers, including a new Help Manager application in Prism, which will help keep track of what help records have been created, which ones should be, what records are bound to what entry forms, etc.
The Prism design team is always interested in suggestions about further development. Please feel welcome to contact us through the SUGGEST command in Prism.
From the end-user's point of view, the required helps are the minimum number of help records your file needs to be understandable. From Prism's own more technical point of view, the required helps are the records Prism expects to find in order to provide information -- usually automatically -- during a Prism end-user;s session.
The form you give to the key (or alias) of these help records must be precise. Here are the keys of the help records required for a basic application in Prism (i.e., one that does not include reporting and data entry):
?WELCOME Welcome screen for your file
<file-name> FILE Record explaining your file to
anyone anywhere in Prism
<indexterm> INDEX Help record for each search type
<display-name> DISPLAY Record describing a display
?DISPLAY/<display-name> Context help for a display
The IDs of many helps consist of just the help terms themselves. These help records are available to users whenever they type HELP followed by the help term. Context helps (those presented when the user simply types HELP) are identified by a "?" prefix in the record key. [See 6.1 for more about context helps.] Welcome (or introduction) screens are considered a type of context help and therefore have keys beginning with "?" (e.g. ?WELCOME for the welcome screen for your file).
This is the screen end-users automatically see when they select your file. It should be no longer than 15 lines (not counting lines with control words like $ALIAS). The reason for this length limit is that welcome screens, unlike your other help records, must fit on the same screen with the command options that your end-users will see in Guided Mode.
Your ?WELCOME help record should be formatted like the example below. (In Prism no one will see the first line as shown.) Note the question-mark prefix and the asterisk, which must be in column one:
1. * ?WELCOME <---(Note question-mark prefix) 2. 3. [Introductory text starting in line 3 and going on : : : : 15. for 15 lines max, in order to fit onto Guided screen.]
The text of the welcome screen should explain briefly what kind of information the file contains, whether the file can be used for reporting or data entry as well as searching, and who should be contacted to answer questions about the file. If you have coded additional displays besides BRIEF and FULL, and these displays are available for your general community of users, the welcome screen is a good place to announce them.
Note that if your application must collect parameter-input from your users, as they select your file, you can code a screen processing step to appear in place of, or in addition to, the file welcome screen. [See 9 for information on processing steps, 3.6 for suggestions of possible uses for screen steps in place of ?WELCOME.]
<File-name> FILE is the help record end-users see when they explicitly ask for help, naming your file. The record's key consists of your file's name as it appears on the Prism menu, followed by the word FILE. You can use the $ALIAS control word to create alternate names by which the help record might be accessed. (But don't forget that Prism matches stems when calling up help records, so two aliases with the same stem would be redundant.)
It is important that this help record be accessible to anyone in Prism, whether they have your file selected or not. For example, a user might see your file listed in a SELECT menu and want to use the HELP command to find out more about it. The $PRISM control word makes your <file-name> FILE help record accessible throughout Prism.
* PUBLIC EVENTS FILE
$ALIAS CALENDAR OF EVENTS
$CATEGORY OTHER
$PRISM <----|$PRISM makes your help
|screen available outside
text |the file it explains.
:
It's recommended that you include a $CATEGORY OTHER control word in this help record, so that it is listed on the HELP TOPICS menu, in the section "Other information about this file". [See 6.3.5 for an explanation of the $CATEGORY control word.]
Prism automatically appends to this help record a list of your file's search types, displays, entry forms, reports, and fields whenever end-users access it online. (It is actually the presence of the $PRISM control word in this help record that creates the lists at the end of your text.)
For each search type in your file, you should create a help record with a key in the form "<indexterm> INDEX". Users can request this help record by name (e.g. by typing HELP DEPT INDEX for information about the DEPT search type). In addition, this help record is displayed if a user types HELP (or "?") while being prompted for a search value for that index. Thus, this help record serves double duty as a general help and a context help.
This help record is also important in another situation. On the HELP TOPICS menu, if the user is in the process of performing a search and has chosen an index, one entry on the menu would be "Help for the search type you were using". If the user chooses that item from HELP TOPICS, the <indexterm> INDEX help record is displayed.
It's recommended that you include a $CATEGORY SEARCHING control word in this help record, so that it is listed on the HELP TOPICS menu, in the section "Searching in this file". [See 6.3.5 for an explanation of the $CATEGORY control word.]
"Indexterm" in the key of the help record must match the index name as it appears on the FIND menu. You can use the $ALIAS control word to create additional access points for the help record. And if you are installing several Prism files that use the same search type, you can add the $XFILE control word to the help record in order to make the record accessible in more than one file:
* DEPT INDEX
$ALIAS DEPARTMENT INDEX
$CATEGORY SEARCHING
$XFILE FISCALX <------|$XFILE makes this single
$XFILE FISCALZ <----|help accessible in two
text |additional files, with file-id
: |FISCALX and FISCALZ,
|respectively.
Note: Prism automatically adds an alias in <indexterm> INDEX help records. The alias is in the form $ALIAS ?INDEX/<indexterm>. This alias is used internally by Prism to ensure that this help record is always accessed as the context help when a user is being prompted for a value for this index (whether HELP is typed at the search value prompt itself or at the command line). In the future, Prism's help facilities may expand so that you may create two separate help records -- the <indexterm> INDEX help to provide a general description of the search type, and the ?INDEX/<indexterm> help to serve as a context help. For the time being, however, ?INDEX/<indexterm> is only allowed as an alias and not as the key of a help record.
For each additional display besides BRIEF and FULL in your file, you should create a help record with a key in the form "<display-name> DISPLAY". This help record should provide a general description of the display and how it might be useful. You might also provide any explanations needed to interpret what's shown in the display.
On the HELP TOPICS menu, if the user is viewing records with a particular display, one entry on the menu would be "Help for the display you were just viewing". If the user chooses that item from HELP TOPICS, the <display-name> DISPLAY record is shown.
It's recommended that you include a $CATEGORY DISPLAY control word in this help record, so that it is listed on the HELP TOPICS menu, in the section "Displaying data in this file". [See 6.3.5 for an explanation of the $CATEGORY control word.]
* SUMMARY DISPLAY
$CATEGORY DISPLAY
$ALIAS ?DISPLAY/SUMMARY <-- allows this help to
serve as context help
[text describing SUMMARY display] (see below)
:
There is another situation where Prism looks for a help record describing a particular display. If a user is looking at records using this display and simply types HELP (or "?"), Prism looks first for a context help for the display. This help has a key in the form ?DISPLAY/<display-name>. You have two choices: you may create a separate help record with this key, or you may add this term as an alias in the <display-name> DISPLAY help record (as shown in the example above).
One reason for creating two separate help records is that you can modify the wording to better fit the user's situation. That is, for the context help, you know that the user was looking at records in the given display. For the general help, you don't know whether the user was actually using the display, or just requesting information about it prior to using it. For example, the context help might say something like "You were looking at records in the XYZ display..." while the general help might be worded more generally, perhaps including a reference to using the DISPLAY <display-name> command to see records in a particular display.
If you wish, you may also create help records describing the BRIEF and FULL displays in your file. Since every Prism file is required to have displays called BRIEF and FULL, there are general Prism help records describing these displays. Naturally, these general help records do not provide specific details about the displays in any one file. That's why you may want to create your own help records for these displays.
If you create a help record with the key FULL DISPLAY (or BRIEF DISPLAY) then your help record will be shown in preference to the general Prism help when a user of your file types HELP FULL DISPLAY or HELP BRIEF DISPLAY. You may also create your own context helps for BRIEF and FULL (by using the key or alias of ?DISPLAY/FULL and ?DISPLAY/BRIEF).
An additional tool that is useful when maintaining help records for an application is the XHELP command. XHELP followed by a help-term takes you directly to the display form of the help record, without taking into account other general Prism helps that might otherwise cause a HELP menu.
XHELP also bypasses the normal Prism rules about binding ($BIND and $XBIND control words) and provides a way to display a context help record without having to actually be in that context (e.g. you can type XHELP ?WELCOME to display your welcome screen).
Thus, XHELP is useful when you are modifying a help record (with XSETUP HELP) and then want to see what it looks like on the Prism screen.
In response to suggestions and requests from users and application developers, several changes were made in the summer of 1988 to the way the Prism HELP system works. This chapter has been revised to reflect these changes, but for the benefit of application developers with existing help records, the changes are summarized briefly below.
Applications that support reporting and/or data entry will need the help records described so far in this chapter, as well as the following additional help records, which will be described more fully in later chapters:
?INTRO/REPORT/<report-name> An intro screen for each report
<report-name> REPORT Record describing the report
?REPORT/<report-name> Context help for the report
?INTRO/FORM/<form-name> An intro screen for each entry form
<form-name> FORM Record describing the entry form
?INPUT... One help for each input screen,
describing entry fields on that screen
(optional but strongly recommended)
?ERROR Single record explaining input errors
[See 10.7 to read about help records for reports, 9.1.1 for helps for input screens, 11.6 for other helps for entry forms.]
The command PERFORM PRISM HELP <help-term> may be used in a Prism protocol to simulate the user's typing HELP <help-term> at the command line.
The first few times you try out your application, things may not work as expected. Or you may receive system error messages from Prism, indicating some problem with your code (or how it interacts with Prism's code). To diagnose the problem, you will probably need to use the debugging and tracing commands described in this chapter. Often these debugging commands let you temporarily pause in the middle of a Prism session in order to obtain diagnostic or informational messages directly from SPIRES.
Here are some of the most widely-used debugging tools:
Prism prepares nightly reports of system errors or other errors encountered in your application that day. This report is sent by electronic mail to the contact address specified in your profile. In addition, you may request immediate online notification of system errors, so that problems in your application may be identified and corrected quickly. Use the XSETUP PROFILE command to request this notification, if you did not do so when you first created your profile.
When a system error happens in your application, Prism generates a dump of information about the Prism environment at the time of the error. This dump is assigned a number and saved. Your email error notification will refer to this identifying number.
To see the dump, in WYLBUR, type UTIL GETDUMP and enter the identifying number when prompted. The dumps are stored as "held" print jobs, so will be available about 48 hours.
Note that system errors that happen on the application's owner/maintainer accounts will not trigger a dump (or an email error notice). In addition, Prism will only perform the dump once per SELECT for each user (in an attempt to avoid massive dumping if a user encounters the same error repeatedly).
Prism uses the SPIRES facility PERFORM SYSDUMP to create the dump of the environment information at the time of an error. You can exit to SPIRES and use PERFORM SYSDUMP yourself to generate the dump "on demand". [See 7.5.]
If necessary, you may temporarily disable selection of your Prism application while you are fixing bugs or doing other maintenance. The XSETUP SELECT command (in Prism) and the PERFORM PRISM DISABLE SELECT command (in SPIRES) provide a quick and convenient way to do this. It is also possible to disable just a specific entry form or report, with the XSETUP FORMS or XSETUP REPORTS commands. The same commands provide a facility for re-enabling the file, entry form, or report after your maintenance is finished. [See 8.5, 8.5.1.]
The SET DEBUG command turns on SPIRES warning and serious error messages to level 3, so that the messages display online within Prism while you are testing your application. (Ordinarily error messages are set to level 0 and are hidden from the online display.) Most often these error messages signal a problem in your code -- perhaps in the way your code is interacting with Prism's own code. Once you have SET DEBUG, you can access SPIRES information through the EXPLAIN and SHOW EVAL commands, as described further below.
In addition to SPIRES error messages, SET DEBUG generates other diagnostic messages to help pinpoint problems. Also, whenever DEBUG is set, Prism pauses after each of your input screens (e.g., in data entry) so that you can monitor the screen's status. [See 11.3.2.] At DEBUG pauses, you may press the BREAK or ATTN key to interrupt execution of your code and return to SPIRES. The command CONTINUE XEQ will cause the Prism protocol to resume.
You can only use the DEBUG facility for files that you are authorized to maintain, though you can SET DEBUG (and other debugging commands) at any time that you are within Prism. If you select multiple files in the session, the debugging and tracing will be temporarily turned off whenever you select someone else's file.
As a shortcut you can SET DEBUG and request other debugging facilities at the same time:
SET DEBUG [TRACE] [STRACE] [FTRACE] [XTRACE] [ECHO] [STOP]
(The other debugging tools are described further below.) In addition, if you set one of the other debugging tools, DEBUG will automatically be set at the same time. For instance, SET ECHO turns on DEBUG as well as ECHO.
Note that if you include FTRACE or XTRACE in your SET DEBUG command, you are not allowed to use any of the additional options otherwise available for those tracing commands. You must use SET FTRACE or SET XTRACE to specify the special features of FTRACE or XTRACE. [See 7.4.3, 7.4.4.]
The Prism flag variable $DEBUG is true whenever DEBUG is set, so your code can query this value if you want your application to behave slightly differently when it's in "debugging" mode. (See the appendix on Prism variables for more information.)
Use the SHOW DEBUG command in Prism if you need a reminder of the debugging and tracing options you have enabled.
There is a $DEBUG control word available for help records, which specifies that the help should only be available when DEBUG is set. You are free to use the control word for your own application help records. It is also used in some of the general Prism help records about debugging commands. (Using $DEBUG in these help records "masks" them from end-users, who normally don't need to see them and might be confused by reading about programming tools and techniques not applicable to their work.)
Once you have SET DEBUG, you may type HELP DEBUGGING COMMANDS, which gives a summary of all the available debugging commands. In SPIRES, a similar summary can be seen with EXPLAIN DEBUGGING COMMANDS.
The CLEAR DEBUG command counteracts the SET DEBUG command and resets internal messages to zero. CLEAR DEBUG turns off all debugging and tracing mechanisms at once. So if, for instance, you've turned on XTRACE and FTRACE, the single command CLEAR DEBUG will turn off both. (There are also CLEAR commands to turn off the individual debugging/tracing tools, as described in later sections.)
Note: CLEAR DEBUG does not turn off the TLOG mechanism. Use the CLEAR TLOG command to clear out your tracing log. [See 7.4.5.]
Once you SET DEBUG, Prism pauses whenever it detects an error during execution of your code, giving you an opportunity among other things to check the SPIRES error messages. (Pressing RETURN will cause Prism to continue the session.) While DEBUG is set, you can issue the SPIRES command EXPLAIN at any command prompt (e.g., EXPLAIN S256) for information about the errors. Or you can issue the SHOW EVAL command to see current values for any of your variables and/or expressions.
Note that when SET DEBUG is turned on, EXPLAIN behaves in Prism exactly as it behaves in SPIRES. When SET DEBUG is not functioning, the EXPLAIN command is interpreted by Prism as a synonym for HELP.
The SET STOP command causes your Prism protocol code to interrupt its execution whenever a command in the protocol fails. [See 9 for information on protocol steps in Prism.] When you have SET STOP and a command has failed, you will see the prompt "-Continue XEQ?" appear below the Prism screen. If you type "BREAK" in response to this prompt, the protocol will interrupt at just that point, leaving you free to test or change the condition that caused the error:
-Continue XEQ? BREAK <--Or you could cause execution
to resume by typing YES here
When finished testing within the execution break, type the command CONTINUE XEQ to cause the Prism protocol to continue executing where it left off.
SET STOP is probably most effective when it's used together with SET ECHO [See 7.3.] Note that the SET STOP command in Prism should make it unnecessary for you to use the SET STOP command in your SPIRES code -- that is, you can now avoid coding the SPIRES command SET STOP within your protocol itself, since the Prism version of the command is much better suited to debugging in Prism.
The command SET NOSTOP, or CLEAR STOP, turns off the protocol "stopping" mechanism.
Another debugging command, SET ECHO, turns on SPIRES command echoing within Prism, during the execution of any protocol step you've added to your Prism application. If one of your protocol steps causes an error, SET ECHO can help pinpoint the exact protocol statement causing the problem. SET ECHO and SET STOP make an especially useful pair of debugging commands -- one causes commands (including failing commands) to echo, the other interrupts the protocol so you can investigate further. [See 7.2.]
Either CLEAR ECHO or SET NOECHO turns off echoing of protocol execution.
Although you don't have to have your own application selected to issue the SET ECHO command, the echoing will only be activated in applications that you are authorized to maintain.
Note that compiled protocols do not echo during execution, even if you have SET ECHO, so you may want to leave your Prism protocols uncompiled during testing, and compile them when you move the application to production. [See 9.2.3 for information on compiling protocols.]
If your protocols are compiled, you can issue the SET NOCOMPXEQ command to instruct Prism to switch to the uncompiled versions, so that you can trace their execution with SET ECHO. Any protocols currently in the XEQ stack when the command is issued will be reloaded in uncompiled form as the compiled protocol is exited. For example, if you are in the middle of an entry transaction in a form with compiled protocols and you type SET NOCOMPXEQ, the uncompiled version will be loaded only after you SEND or CANCEL the transaction and the entry form protocol is exited.
Note that if your code invokes protocols with XEQ FROM or a "..protocol-name" command, Prism cannot switch to the uncompiled form.
To switch back to compiled protocols, type either SET COMPXEQ or CLEAR NOCOMPXEQ. Note that the SET NOCOMPXEQ setting is session-wide, so simply changing files or entry forms is not sufficient to switch from uncompiled to compiled protocols. (CLEAR DEBUG turns off the NOCOMPXEQ switch, however, along with all the other debug settings.)
If SET TLOG is in effect, uncompiled protocol statements will be echoed to the TLOG (along with the other tracing information you have requested). [See 7.4.5.]
Several commands are available to trace different parts of your code (and Prism's) as it executes. Most provide the same function as in SPIRES, but there are two Prism-specific tracing commands (SET TRACE and SET STRACE):
SET TRACE general Prism tracing SET STRACE how Prism searches are processed SET FTRACE formats tracing SET XTRACE protocols tracing SET PTRACE processing rules tracing SET TLOG sending tracing information to a "trace log"
Each command is described in detail in the following sections.
The SET TRACE command provides a general tracing facility for major "events" in a session, both within and outside of your own protocols and formats code. Specifically, it traces:
- Selecting the SPIRES file supporting your application
- Setting the display, form, or report format
- All preloads that occur
- The start of protocol step execution
- Any PERFORM PRISM commands that are executed
- The end of protocol step execution
At each of these events, you get a standard DEBUG pause, where you have the opportunity to break out to SPIRES for whatever diagnostic task you need to do.
If you have issued the SET TLOG command, the tracing information generated by SET TRACE will be placed in your "trace log". [See 7.4.5 for information about trace logs.]
To turn off the tracing, issue the command CLEAR TRACE. (The CLEAR DEBUG command will also turn off SET TRACE, plus any other debugging and tracing tools that were enabled.)
The SET STRACE command traces how a Prism search request is parsed and passed to SPIRES for processing. It also expands Personal Searches into their component parts. Here is a fairly simple example:
YOUR RESPONSE: find local.thai
:
:
-Search: FIND local.thai
- Personal search LOCAL.THAI
- + Search: Find CUISINE THAI
- SPIRES: Find CUISINE THAI
- Result: 5
- + Search: and (CITY redwood city or palo alto or menlo park)
- SPIRES: and (CITY redwood city or = palo alto or = menlo park)
- Result: 2
- Stored result @1
-SPIRES: FIND @1
-Result: 2
-Debug pause; press RETURN to continue
- (ATTN=Break Xeq)
If you have issued the SET TLOG command, the tracing information generated by SET STRACE will be placed in your "trace log". [See 7.4.5 for information about trace logs.]
To turn off the tracing, issue the command CLEAR STRACE. (The CLEAR DEBUG command will also turn off SET STRACE, plus any other debugging and tracing tools that were enabled.)
The SET FTRACE command activates format execution tracing, which acts in Prism much as it does in SPIRES, displaying successive steps of your formats code as they execute, and helping you spot the exact point at which something goes wrong in the code.
In Prism, you can use the same FTRACE options as in SPIRES, to control precisely what type of tracing information you see:
Several of your formats may be in use in your Prism application, depending on whether you are in search, report, or entry activity. In report and entry activity, at least two formats are typically in use, on different paths -- your display format and your report or entry format.
SET FTRACE will turn on tracing for all of your formats, as they are used. If you are in report or entry activity, you may issue the command CLEAR FTRACE DISPLAY to turn off tracing of your display format while leaving it on for your report or entry formats. The command SET FTRACE DISPLAY (or with options such as JUMP, SNAPSHOT, etc.) will turn it back on.
The SPIRES command SHOW FTRACE tells you which of the FTRACE options are currently in effect. (Type SPIRES first, then SHOW FTRACE.)
Your SET FTRACE FRAMES and SET FTRACE VARIABLES commands may include lists of frames or variables:
SET FTRACE FRAMES frame-name1, frame-name2 ...
You may add or delete frames/variables with a plus or minus sign:
SET FTRACE FRAMES + frame-name3, frame-name4 ... SET FTRACE FRAMES - frame-name1 ...
You may also specify an "exclusion list" with a series of commands like this:
SET FTRACE VARIABLES SET FTRACE VARIABLES - variable1, variable2 ...
The effect here is that all variables except "variable1" and "variable2" will be shown in the tracing.
If you have issued the SET TLOG command, the tracing information generated by SET FTRACE will be placed in your "trace log". [See 7.4.5 for information about trace logs.]
The CLEAR FTRACE command turns FTRACE off completely, as does the CLEAR DEBUG command. You may instead turn off specific FTRACE options with one or more of these commands:
CLEAR FTRACE JUMP CLEAR FTRACE VARIABLES CLEAR FTRACE SNAPSHOT CLEAR FTRACE FRAMES CLEAR FTRACE BRIEF
For further details about FTRACE, see B.7.2 in "SPIRES Formats".
The SET XTRACE command activates tracing of your protocols, as in SPIRES. The tracing will show each entry and return in your protocols and procs.
In Prism, you can use the same XTRACE options as in SPIRES, to control precisely what type of tracing information you see:
The SPIRES command SHOW XTRACE tells you which of the XTRACE options are currently in effect. (Type SPIRES, then SHOW XTRACE.)
Your SET XTRACE PROTOCOLS and SET XTRACE VARIABLES commands may include lists of protocol-names or variables:
SET XTRACE VARIABLES variable1, variable2 ...
You may add or delete protocols/variables with a plus or minus sign:
SET XTRACE VARIABLES + variable3, variable4 ... SET XTRACE VARIABLES - variable1 ...
You may also specify an "exclusion list" with a series of commands like this:
SET XTRACE PROTOCOLS SET XTRACE PROTOCOLS - protocol-name1, protocol-name2 ...
The effect here is that all protocols except "protocol-name1" and "protocol-name2" will be shown in the tracing.
If you have issued the SET TLOG command, the tracing information generated by SET XTRACE will be placed in your "trace log". [See 7.4.5 for information about trace logs.]
The CLEAR XTRACE command turns XTRACE off completely, as does the CLEAR DEBUG command. You may instead turn off specific XTRACE options with one or more of these commands:
CLEAR XTRACE JUMP CLEAR XTRACE VARIABLES CLEAR XTRACE PROTOCOLS
For further details about XTRACE, in SPIRES type EXPLAIN SET XTRACE.
As in SPIRES, you may issue the SET TLOG command in Prism to specify that your tracing and debugging information should go into a "trace log" rather than being displayed at your terminal. Then you can examine the trace log, perhaps placing it in your active file or printing it for closer study.
SHOW TLOG DATA displays the contents of the trace log. Add the IN ACTIVE (or DUMP) prefix to place the trace log in your active file.
CLEAR TLOG DATA clears the trace log but leaves the trace log facility on. CLEAR TLOG clears the log and turns off the log facility altogether.
The SET PTRACE command activates tracing of processing rules being executed as element values are processed by them, as in SPIRES. The command will succeed only if you have SEE access to the SPIRES file to which the subfile belongs.
There are eight forms of the SET PTRACE command, depending on which options you want to use. You may issue multiple SET PTRACE commands to achieve particular combinations.
SET PTRACE - basic information
SET PTRACE SNAPSHOT - detail information
SET PTRACE USERPROCS [names] - information about Userprocs
SET PTRACE VARIABLES [names] - information about variables
used in Userprocs
SET PTRACE JUMP - information about execution
flow commands in Userprocs
SET PTRACE ELEMENTS [names] - limits other SET PTRACE commands
to named elements
SET PTRACE TYPES [types] - limits Ptrace information to
specific types of processing
(e.g., Inprocs, Searchprocs)
SET PTRACE ALL - same as issuing all of the above
except SET PTRACE TYPES
Each has a parallel CLEAR PTRACE command to clear its particular effect. Also, "+ names" and "- names" lists can be used on the USERPROCS, VARIABLES, ELEMENTS or TYPES flavors to alter the effect of a previous command.
The SPIRES command SHOW PTRACE tells you which of the FTRACE options are currently in effect. (Type SPIRES first, then SHOW PTRACE.)
If you have issued the SET TLOG command, the tracing information generated by SET PTRACE will be placed in your "trace log". [See 7.4.5 for information about trace logs.]
The CLEAR PTRACE command turns PTRACE off completely, as does the CLEAR DEBUG command. You may instead turn off specific PTRACE options, e.g. CLEAR PTRACE SNAPSHOT.
For further details about PTRACE, see B.4.16 in "SPIRES File Definition" or EXPLAIN SET PTRACE (in SPIRES).
The GRANT PRIVILEGES command lets you temporarily extend debugging and tracing privileges to a person who is not an owner/maintainer for the application. After you have granted the debugging privileges, the other person may issue debugging and tracing commands to help track down a problem.
The debugging privileges remain in effect as long as the user is in the application. After helping the application user with the debugging process, it's a good idea to instruct him to select a new file or end the Prism session, in order to terminate the debugging privileges. You can check the currency of the granted privileges with the STATUS GRANT command.
The syntax is:
GRANT [APPLICATION] PRIVILEGES [FOR file-id] TO userID
In regard to the APPLICATION option, Prism system programmers may on occasion issue a GRANT SYSTEM PRIVILEGES command in order to give you, as an application developer, tracing privileges for the Prism code itself. This tool is useful when you need to trace interactions between your own code and Prism's. By default, the debugging privileges will apply to the file-id of the application you have selected when you issue the GRANT command. Use the FOR file-id option if you need to grant privileges for another file-id.
The "userID" may be either a WYLBUR account or a userID.
When you issue the GRANT PRIVILEGES command, your terminal locks (with the "Wait" indicator on) until the "grantee" selects your application and issues a debugging command. You can press the BREAK key to interrupt the GRANT; there's also a 5 minute timeout.
If the account to which you grant privileges happens to be logged on with multiple sessions, the first session in which the debugging commands are initiated will be the one (the only one) with debugging privileges.
Note that the grantor and grantee must be on two different Forsythe sessions, in this implementation. You can't, for example, logon with an application owner account, grant the privileges, then logoff so the user can logon and show you what was happening.
The SPIRES command (which can be abbreviated to "SPI") interrupts your Prism session and places you in SPIRES. It is available only in files you are authorized to maintain. While in SPIRES, you might test or change one of your variables or issue SPIRES commands that might help you determine how your code is executing.
Note that you should not alter the environment of your Prism session radically (like selecting a different file!) or the session will not work properly when you issue the CONTINUE XEQ command to return to Prism from SPIRES. Also, when you exit to SPIRES, your current WYLBUR active file may be a temporary working file established by Prism, rather than the active file that was current when you first went into Prism.
If you are authorized to maintain an application, you have access in Prism to other SPIRES commands that may be useful for debugging:
SHOW ELEMENTS SHOW INDEXES SHOW SUBFILE INFORMATION SHOW SUBFILE SIZE SHOW SUBFILE TRANSACTIONS SHOW SUBFILE STATUS
The IN ACTIVE prefix may be used on any of these commands to append the display to your active file, in case you want to print it. For example:
[IN ACTIVE [CLEAR | CONTINUE]] SHOW SUBFILE TRANSACTIONS
In addition, two SPIRES commands are available to help in monitoring your application's use of computer memory:
[IN ACTIVE [CLEAR | CONTINUE]] SHOW FREECORE [IN ACTIVE [CLEAR | CONTINUE]] SHOW SUBFILE MAP
These commands are useful for developers of large or complex applications that risk either fragmenting computer memory or running out of enough memory to do their work. The commands show how much memory the different SPIRES components of your application (such as formats and vgroups) are taking up, and whether any individual component is taking an undue share of memory.
The two commands work the same way in Prism as they do in SPIRES. For details, see the "SPIRES Protocols" manual or use EXPLAIN online.
The PRISMCPU utility creates a report showing CPU/IO breakdown of an application from a day's Prism log. To create the report, issue the command UTIL PRISMCPU in WYLBUR. Note that the utility uses scratch files, so don't run more than one at a time on a given account or the files will intermingle. And run the report only in non-PEAK hours, since it takes significant computer resources to generate the report. This utility was developed for use in capacity-reduction efforts in 1994 and is subject to change. If you comments or suggestions, contact a consultant in Data and Technology Resources.
The SHOW VARIABLES command will show you all of your static and dynamic variables. It acts somewhat like the SHOW STATIC VARIABLES command in SPIRES, but shows you only your own variables, not Prism's variables.
SHOW VARIABLES offers three options:
[IN ACTIVE [CLEAR | CONTINUE]] SHOW VARIABLES [BRIEF] [LIKE vname]
The BRIEF option acts similarly to the BRIEF option on the SHOW STATIC VARIABLES command in SPIRES, condensing the more repetitive parts of the variable display. The LIKE option lets you narrow the display to similarly-named variables: you can use it to see all the members of a single array in one command. Replace "vname" with the name of one of your variables. Note that currently you cannot limit the display to a particular "vgroup" -- this may come as a future enhancement someday.
The IN ACTIVE prefix puts the SHOW VARIABLES display at the end of your active file.
The $PRISMINFO function returns information about the current Prism environment. For the complete syntax, EXPLAIN $PRISMINFO. Here is an example that retrieves the user's first search command:
> show eval $prisminfo(search,command,,1) Find NAME california
If at any time you forget which version of Prism you are currently using, e.g., PRISM(TEST) or PRISM(PREPRODUCTION), you can issue the SHOW VERSION command to see the version number and the date when it was installed. (The different versions of Prism such as PRISM(TEST) are described in an appendix to this manual called "Change Control Procedures".)
Use the UTIL PRISMVER command (in WYLBUR) to set the default version of Prism that you would like to enter when you issue the Prism command.
The SHOW LOG command provides an online display of the most recent log entries written for your current session into Prism's internal LOG buffer. These log entries consist of your commands along with system responses. SHOW LOG offers a way to get quick debugging information after an error has occurred, e.g., when a SELECT command fails.
If you need to obtain longer excerpts from the general Prism log, for debugging purposes, contact Data and Technology Resources staff.
An alternate way to see your most recent issued commands is the SHOW HISTORY command. SHOW HISTORY displays commands only, not errors or system responses. For more information, type HELP SHOW HISTORY within Prism.
The SET LOG and CLEAR LOG commands were eliminated from Prism with the May 1990 version of Prism.
Ordinarily, Prism enters your protocol code with the message level set to zero, but when you SET DEBUG, Prism will enter the code with everything but informational messages set to level 3. Within the protocol you can change the message level all you want while you are testing your application -- when it regains control, Prism will reset the message level to whatever it was before the protocol was invoked. Of course, before you move the processing step into production, you will need to set the message level back to zero at all times. [See 9.2.5.]
The DUMP SCREEN command appends a copy of the current screen to the end of your active file. DUMP SCREEN is useful for getting screen pictures for documentation, for debugging, or for checking layouts. Remember, by the way, that you can use the PAUSE command in Prism to look at your "dumped" screen (or anything else), then return to the identical place in Prism with the GO command.
The full syntax of the command is as follows:
DUMP SCREEN [BOX|CLEAR|KEEP] [/ text]
The BOX option surrounds the screen with a box. The CLEAR option clears the current active file for dumping the screen.
The KEEP option opens a new active file for the screen dump.
If you add a slash and text after the DUMP SCREEN command, the text after the slash will be placed in the command line in the dumped screen image. For example, DUMP SCREEN / FIND DATE 3/89 will put "FIND DATE 3/89" in the command line of the screen image.
Occasionally your application users may encounter problems with Personal Searches or Personal Reports or tasks defined in your application. Besides the debugging and tracing tools already described in this chapter, there is one other tool that may help you assist your users.
Personal Search, Personal Report, and task definitions are stored in a SPIRES subfile called PRISM DEFINITIONS. In this subfile you may display (and update) records for your applications. Its main purpose is for Prism to store and maintain search and report definitions, but it is open to you in case the information there will help you analyze problems.
The keys of the records in the subfile are in the form:
REPORT/file-ID/account/report name SEARCH/file-ID/account/search name TASK/file-ID/account/task name
If you know the name of the search or report or task, plus the account under which it was defined, plus the application file-ID, it is simplest to use the DISPLAY <key> command to look at the record.
There are a few indexes to help you retrieve definitions:
PRISMID the file-id to which the definition belongs OWNER account that defined the object NAME name of the report, search, or task TYPE either REPORT, SEARCH, or TASK
Or you can use Global FOR techniques to review the report or search definitions for a particular user:
-> for subfile +> set scan prefix report/suffunds/as.ahh +> display
Another subfile, PRISM DEFINITIONS MAINT, lets you update definition records for your applications, on those rare occasions where you might need to do this.
Why might you need to update definition records? For the most part, you should not change the definitions themselves, but if you need to migrate definitions from one application to another, you could do so here by changing the file-id of the definition record (i.e. adding a new record and possibly removing the old one). If an application user switches from one account to another, you could migrate his or her definitions to the new account. Or if you remove a Prism application altogether, you could use this subfile to remove all the definition records associated with the application.
If you have questions or want help interpreting the records in PRISM DEFINITIONS, contact DTR staff.
Here is a summary of the debugging commands available within Prism. For online explanations of them in SPIRES, use EXPLAIN followed by the term:
SET DEBUG Turns on debugging mechanism in your file
(CLEAR DEBUG turns it off)
XSETUP SELECT Lets you temporarily disable a Prism file
SET ECHO Causes commands to echo in uncompiled protocol
(CLEAR ECHO or SET NOECHO turns it off)
SET NOCOMPXEQ Switches to uncompiled protocols
(CLEAR NOCOMPXEQ or SET COMPXEQ turns it off)
SET STOP Interrupts protocol if a command fails
(CLEAR STOP or SET NOSTOP turns it off)
SET TRACE Turns on general tracing of major session "events"
(CLEAR TRACE turns it off)
SET STRACE Shows how Prism searches are passed to SPIRES
(CLEAR STRACE turns it off)
SET FTRACE Turns on general tracing of your SPIRES format
(CLEAR FTRACE turns it off)
Specialized formats tracing commands:
SET FTRACE JUMP
SET FTRACE VARIABLES variable-names
SET FTRACE SNAPSHOT
SET FTRACE FRAMES frame-names
SET FTRACE BRIEF
SET FTRACE HELP ftrace-options
SET XTRACE Turns on tracing of protocol execution
(CLEAR XTRACE turns it off)
Specialized protocol tracing commands:
SET XTRACE JUMP
SET XTRACE VARIABLES variable-names
SET XTRACE PROTOCOLS protocol-names
SET PTRACE Turns on tracing of processing rules
(CLEAR PTRACE turns it off)
Specialized commands:
SET PTRACE SNAPSHOT
SET PTRACE JUMP
SET PTRACE USERPROCS names
SET PTRACE VARIABLES names
SET PTRACE ELEMENTS names
SET PTRACE TYPES types
SET TLOG Sends tracing information to a trace log
UTIL GETDUMP Get the dump of environment info generated when a
Prism system error happens.
SHOW DEBUG Shows which debugging and tracing options are in effect
SPIRES Exit temporarily to SPIRES
GRANT PRIVILEGES Temporarily gives debugging privileges to a
non-owner/maintainer account
GRANT PRIVILEGES [FOR file-id] TO userID
STATUS GRANT to see status of granted privileges
SHOW FREECORE Shows application use of memory (core)
SHOW SUBFILE MAP Shows application components loaded into memory
SHOW VARIABLES Displays your own variables
SHOW EVAL Evaluates variables and expressions
EXPLAIN Displays SPIRES explanations
SHOW LOG Displays brief log of current session
SHOW HISTORY Displays recent command history
SHOW VERSION Tells which version you are in
UTIL PRISMVER Establish default version of Prism to enter.
DUMP SCREEN Puts screen in your active file
Some other SPIRES commands, such as SHOW SUBFILE INFORMATION, SHOW SUBFILE TRANSACTIONS, SHOW SUBFILE STATUS, SHOW ELEMENTS, and SHOW INDEXES, are also available in Prism.
Once your application is installed (with the ADD PROFILE entry form in Prism Profile), further modifications are made with the XSETUP command or with other entry forms in Prism Profile. (Changes to the SPIRES components of your application -- your file definition and formats -- must be made in SPIRES.)
For example, general information about your application (such as its name and description on the SELECT menu) may be changed using either the XSETUP PROFILE command or the MOD PROFILE entry form in Prism Profile.
Why are there two ways to do these maintenance tasks? The XSETUP command was added to Prism in December 1989. Prior to that time, all changes to your application profile had to be done in Prism Profile. XSETUP offers a number of benefits over working in Prism Profile. The command XSETUP for modifying application components is an analog to the SETUP command available for all Prism users. SETUP lets you customize various aspects of your Prism session, such as defining Personal Reports, setting up default sorting, and so forth.
- The XSETUP command allows you to add or modify application components, from within the application itself. This is a convenience and time-saver, because you do not have to leave the application and move to Prism Profile or to native SPIRES to make the changes.
- Another advantage of modifying your application with XSETUP rather than in Prism Profile is that you can quickly see the effects of the changes you make. You do not have to re-select your application; your changes will be reflected immediately after you finish XSETUP.
- The XSETUP command lets you be very specific about which part of your application you want to modify. For example, the command XSETUP FORM ADDUPD tells Prism that you want to modify some aspect of the entry form called ADDUPD in your application. With the alternative tool -- the MOD FORMS entry form in Prism Profile -- you must see an additional screen where all of your entry forms are listed and you specify which one you want to work on.
- And the XSETUP command lets you modify some components of your application that are not accessible via entry forms in Prism Profile:
- Your help records (XSETUP HELPS). [See 6.2.]
- Your protocol records (XSETUP PROTOCOLS).
Before XSETUP was available, all maintenance of help records and protocols had to be done outside of Prism, in native SPIRES.
XSETUP SELECT provides another facility not available in Prism Profile -- temporarily disabling selection of your Prism file (and later re-enabling it). [See 8.5.]
There are some application maintenance tasks that are not available in XSETUP and must be done in Prism Profile:
Another way to summarize the differences is to compare the XSETUP menu and the menu of entry forms in Prism Profile. If you type XSETUP in an application you are authorized to maintain, you will see the menu of choices shown below.
_________________________________________________________________________ United States Search 06/30/92 09:36 XSetup selection ------------------------------------------------------------------------- Choose which developer setup you want by typing its name or number below. 1. PROFILE Setup basic file-level application profile information 2. SELECT Setup file availability (disable/enable) 3. DISPLAYS Setup BRIEF, FULL and additional displays 4. FIELDS Setup definitions for sorting and reporting fields 5. FORMS Setup information about entry forms 6. HELPS Setup application help records 7. INDEXES Setup indexes (search types) 8. PROTOCOLS Setup application protocol exits 9. REPORTS Setup information about reports _________________________________________________________________________
If you type ENTRY in Prism Profile you will see this menu of entry forms:
_________________________________________________________________________
Prism Profile 03/22/90 17:12
Entry form selection 11 entry forms available
-------------------------------------------------------------------------
Choose an entry form by typing its name or number below:
NAME PURPOSE
1. ADD PROFILE Install basic components for primary file
2. MOD PROFILE Revise basic components of Prism application
3. MOD DISPLAYS Add or revise DISPLAY definitions
4. MOD INDEXES Add or revise INDEX definitions
5. MOD FIELDS Add or revise FIELD definitions
6. MOD REPORTS Add or revise REPORT definitions
7. MOD FORMS Add or revise ENTRY FORM definitions
8. MOD ACCESS Modify Prism select access
9. MOD OPTIONS Add or revise customized option messages
10. ADD LINK Install basic components for link file
11. REM PROFILE Remove Prism profile record
_________________________________________________________________________
You are free to use either XSETUP commands or the corresponding entry forms in Prism Profile to maintain your application; both tools provide the same function. In fact, the screens you see when you use XSETUP are almost identical to the ones in the Prism Profile entry forms.
Note that you issue the XSETUP command from within your own application. You may only use XSETUP in an application that you are authorized to maintain.
The rest of this chapter covers the following topics:
To change the information you entered in ADD PROFILE, issue the XSETUP PROFILE command from within the application you want to modify. You'll see a series of screens similar to those in ADD PROFILE, where you can change the values you entered earlier.
There are a few differences between ADD PROFILE and XSETUP PROFILE:
Specify here fields to be used for automatic sorting: .............. .............. .............. ..............
Note that the file-id is a protected field; you cannot change it in XSETUP PROFILE. If you want to change your file-id, you will have to reinstall your application with ADD PROFILE (that is, create a new profile) and remove the existing profile. To remove a profile, use the REM PROFILE entry form in Prism Profile. [See 8.6.]
As an alternative to XSETUP PROFILE, you can use the MOD PROFILE entry form in Prism Profile, using a series of commands such as these:
YOUR RESPONSE: select prism profile YOUR RESPONSE: entry mod profile YOUR RESPONSE: find fileid <...> <---(Name your file-id) YOUR RESPONSE: get
MOD PROFILE and XSETUP PROFILE use exactly the same entry screens. The only difference in the two maintenance techniques is that MOD PROFILE is used in Prism Profile and the XSETUP PROFILE command is issued from within the application you are maintaining. [See 8 for the benefits of XSETUP.]
While XSETUP PROFILE lets you modify general profile information, other options on the XSETUP command let you install or modify specific components of your application. For example, XSETUP INDEXES lets you add indexes or change the ones you installed earlier with ADD PROFILE. You would use XSETUP DISPLAYS to install additional displays, XSETUP FORMS to install entry forms, and so forth.
Rather than simply typing XSETUP and seeing a menu of choices, you may specify in your command exactly what you want to modify:
XSETUP PROFILE
XSETUP DISPLAYS or XSETUP DISPLAY display-name
XSETUP FIELDS or XSETUP FIELD field-name
XSETUP FORMS or XSETUP FORM form-name
or XSETUP FORM *
XSETUP HELPS or XSETUP HELP help-term
XSETUP INDEXES or XSETUP INDEX index-name
XSETUP PROTOCOLS or XSETUP PROTOCOL protocol-name
XSETUP REPORTS or XSETUP REPORT report-name
or XSETUP REPORT *
The * in XSETUP FORM * and XSETUP REPORT * refers to the currently selected entry form or report.
If you use the command form shown in the left column, you will be presented with a list of available components to work on (e.g. a list of your reports or entry forms, or help records for the application). You'll be asked to choose a specific item, and to choose a task.
As an example of how XSETUP works, here's what the authorized maintainer of the United States file sees in response to the XSETUP INDEXES command:
___________________________________________________________________________
United States XSetup Index 07/20/90 13:24
Select Function
---------------------------------------------------------------------------
_ <-- Type the number of the function you want to perform (1-3).
1. DEFINE a new index.
2. MODIFY or REMOVE an existing index.
3. CHANGE the order of indexes on the Prism FIND menu.
__ <-- For MODIFY or REMOVE, type a number from the list below.
1. ABBREV Postal abbreviation for a state
2. NAME Name of the state
3. CAPITAL State capital
4. MOTTO Words from a state motto
<etc.>
___________________________________________________________________________
From this screen, you have a choice of defining a new index for your application, modifying or removing an index, or simply changing the order in which indexes are listed in your application.
Once you make your choices here, you'll then be taken to additional screens to make your changes.
Here is an example of the screen shown if you ask to "MODIFY or REMOVE" an existing index. You may type over the existing values or blank them out. If you want to remove the index, fill in the first entry field on the screen. As you can see, this screen is almost identical to the one you saw in ADD PROFILE if you installed indexes when you first created your profile. [See 4.1.5 for instructions on how to fill in this screen.]
____________________________________________________________________________
United States XSetup Index 07/20/92 13:25
STATES: Index MOTTO
----------------------------------------------------------------------------
To remove, enter 'R': _
NAME DESCRIPTION for this index Sample Search Value
MOTTO___ Words from a state motto____________ Liberty_________________
Enter 'Yes' if this index supplies its own search value: No_
If not, enter the prompt used for this index: Motto Words_________
Enter up to 3 lines of explanation to be displayed at the prompt:
Enter words from a state motto._____________________________________________
____________________________________________________________________________
____________________________________________________________________________
Enter 'Yes' to declare or modify special features for this index: No_
Indicate all accounts, groups, or access lists that may use this index:
PUBLIC______________________________________________________________________
____________________________________________________________________________
____________________________________________________________________________
____________________________________________________________________________
Note that instead of XSETUP INDEX, you could have typed XSETUP INDEX MOTTO to get directly to the screen shown above.
Note that if you plan to remove an index or change its name, you should produce a CHECK INDEX report first. This report, available in Prism Profile, tells you whether any indexes have been used in Personal Search definitions in your application. Your user's Personal Search will stop working if you remove an index that has been included in the Personal Search definition.
A set of SHOW commands is available to display information about components of your application, from within the application:
SHOW PROFILE SHOW DISPLAYS or SHOW DISPLAY display-name SHOW FIELDS or SHOW FIELD field-name SHOW FORMS or SHOW FORM form-name SHOW INDEXES or SHOW INDEX index-name SHOW REPORTS or SHOW REPORT report-name
These commands show the same information as the displays available in Prism Profile. For example, SHOW PROFILE is equivalent to looking at the FULL display for your application profile in Prism Profile, SHOW INDEXES is equivalent to DISPLAY INDEXES in Prism Profile, and so forth.
Of course, the advantage of these commands is that they can be used while you have your application selected, in order to see details about how parts of your application are coded. The SHOW commands are also more flexible, in that you can ask for details about one particular component (a specific entry form, index, etc.).
Like XSETUP, these SHOW commands are only available to authorized maintainers of an application.
For information about your help records, refer to the HELP LIST report in Prism Profile. This report provides a summary of the minimum recommended helps for your application, based on the components you have installed (reports, entry forms, etc.). The report shows not only which helps are recommended, but also which ones already exist for your application. [See 6.1.]
The CHECK FIELDS report in Prism Profile tells you which of your reporting and sorting fields are currently in use, either in Personal Report definitions or as default sorting fields. The primary purpose of this report is to tell you which users need to be contacted if you plan to remove a field definition (or change a field name). [See 5.5.]
The CHECK INDEX report in Prism Profile tells you which indexes have been used in Personal Search definitions by your application users. If you plan to change an index name or remove an index altogether from your application, it's recommended that you produce a CHECK INDEX report first so that you will know which users should be notified of changes.
The MOD ACCESS entry form in Prism Profile is dedicated to the single task of adding to the list of accounts allowed to select your file in Prism (and to remove accounts).
As you saw earlier, both ADD PROFILE and XSETUP PROFILE (and MOD PROFILE) already let you add to your account list, but the main advantage of MOD ACCESS is that it lets you add a much larger number of accounts or groups -- 176 maximum, in fact.
Type ENTRY MOD ACCESS in Prism Profile to choose the entry form. Then use the FIND command to retrieve your own application profile, and type GET to begin adding or removing accounts.
MOD ACCESS prompts you for all the Data Center accounts, groups of accounts, or access lists to be given access to your file.
____________________________________________________________________________ Prism Profile Entry Form: MOD ACCESS 10/15/87 14:45 RESTRNTS: Subfile Accounts -Record 1 of 1 ---------------------------------------------------------------------------- Indicate all accounts, groups or access lists that may use this file: gq.jpr, gq.jpr.testers...................................................... ............................................................................ ............................................................................ ............................................................................ ............................................................................ ............................................................................ ............................................................................ ............................................................................ ............................................................................ ............................................................................ ............................................................................ ............................................................................ ............................................................................ ............................................................................ ............................................................................ ............................................................................ ____________________________________________________________________________
List here the Data Center accounts, groups of accounts or access lists to be given access to your file (up to a maximum of 176). Remember that an account takes the form gg.uuu (for example, GG.DAR or AS.PBT). Install a group such as G..... to give access to everyone whose Data Center account begins with G. [See 4 for access lists.]
Don't forget that an end-user needs access to your file via SPIRES as well as Prism -- that is, you must give access through the ACCOUNTS statement in your SPIRES file definition as well as through Prism Profile. [See 2.1 for more information on how to modify your file definition to extend access to it.]
There are two techniques for disabling a Prism application: the XSETUP SELECT command (done within Prism) and the PERFORM PRISM DISABLE SELECT command (which can be done outside Prism, in a protocol or command stream). Both of these techniques allow you to temporarily block selection of a Prism file (and later re-enable it) in order to do file maintenance or fix a tricky bug. You may also write a message to be displayed to anyone who tries to select the file while it is disabled.
(To disable only a specific entry form or report, use XSETUP FORMS or XSETUP REPORTS and choose the "disable" function.) [See 8.5.1.]
Only authorized owners/maintainers of the application may disable a file. And even though the file is disabled for the general public, owner/maintainer accounts may still select the file.
To disable a file:
__________________________________________________________________________
United States XSetup Select 06/30/92 14:33
File enable/disable
SELECT UNITED STATES currently allowed? Yes
To disable SELECT, enter 'Yes' ___
Provide a message for people attempting to select the disabled file:
UNITED STATES is temporarily unavailable because of file maintenance.
We expect to make the file available again by Thursday morning. Call
3-3798 if you have questions._________________________________________
______________________________________________________________________
______________________________________________________________________
______________________________________________________________________
______________________________________________________________________
______________________________________________________________________
______________________________________________________________________
(File availabilty last updated by GQ.PCJ at 01:45:08 on 06/27/92)
__________________________________________________________________________
To re-enable a file so that people can SELECT it:
If you need to disable a Prism file from outside Prism, you may use the PERFORM PRISM DISABLE SELECT command (in SPIRES). The syntax is:
PERFORM PRISM DISABLE SELECT PRISMID = <file-id>
[TEXT = 'text']
The complementary command to re-enable the Prism file is:
PERFORM PRISM ENABLE SELECT PRISMID = <file-id>
If all you need to control is the Prism access, XSETUP SELECT (or PERFORM PRISM DISABLE / ENABLE SELECT) is sufficient. You do not need to issue SPIRES commands such as SET SUBFILE DISABLE.
On the other hand, XSETUP SELECT (and the PERFORMs) only affects access to the file in Prism (not SPIRES access). If you have SPIRES views of the database that need to be blocked from selection, then you do need to use SPIRES commands to control that access.
If several Prism applications use the same SPIRES subfile, you'll need to disable each Prism application individually.
If you need to temporarily disable an entry form or report in order to make a change or fix a bug, use the XSETUP FORMS or XSETUP REPORTS command and choose the "disable" function:
__________________________________________________________________________
United States XSetup Report 03/04/93 13:06
Select Function
_ <-- Type the number of the function you want to perform (1-4).
1. DEFINE a new report.
2. MODIFY or REMOVE an existing report.
3. CHANGE the order of reports on the Prism REPORT menu.
4. DISABLE access to a report temporarily / RE-ENABLE access.
:
:
The resulting screen looks very similar to the one shown earlier for XSETUP SELECT. [See 8.5.] You simply type "yes" to disable the entry form or report. You may also write a message to be displayed to anyone who tries to select the form or report while it is disabled.
Even though the form/report is disabled for the normal community of users, owner/maintainer accounts may still select the form/report.
As you can see from the screen excerpt above, to re-enable a disabled entry form or report, you type XSETUP FORMS or XSETUP REPORTS and again choose function #4. This time, typing "yes" on the resulting screen re-enables the form/report. (You may leave your message in place, in case you need to disable the form or report at a later date.)
When you wish to remove a Prism application, here is the procedure to follow:
(After calling SPIRES, selecting PRISM HELP and naming the file-id of the records you wish to remove:) -> CLEAR FORMAT -> SET RECSEP 'ADD;' -> FOR SUBFILE +> IN ACTIVE DISPLAY ALL (Then save the records in a data set, then:) +> REMOVE ALL (Later if you need to add the records back into the file you could use the INPUT BATCH facility)
Make sure that none of your help records are being shared with other applications through the $XFILE control word before removing them.
____________________________________________________________________________
Prism Profile Entry Form: REM PROFILE 10/15/87 10:09
<file-id>: Remove Profile Record -Record 1 of 4
----------------------------------------------------------------------------
Prism ID: <...> to be removed.
This Prism record contains the following components:
5 INDEXES
2 REPORTS
2 FORMS
0 PROTOCOL records.
0 HELP records.
__________________________________________________________________________
Type YES to remove this profile record: ___
____________________________________________________________________________
To remove the profile record, simply type YES in the blank provided, then issue the SEND command to finish the transaction. If you change your mind and decide not to remove the record, you can issue the CANCEL command at this screen to discard the transaction and retain the profile record. (You would have to enter SPIRES to reinstate your protocol and help records, however.)
REM PROFILE won't let you remove a profile record until all the associated helps and protocols have been removed from their SPIRES files, so you will need to carry out steps 1 and 2 listed earlier, before using the form.
Prism offers you a powerful method of customizing your basic application to meet the specific needs of your end-users. At a number of points within a Prism session, your application can take temporary control of that session, in order to gather specific information from the end-user (such as an authorizing i.d.) or in order to tailor the session in some special way behind the scenes. To take advantage of this facility, you need to write (and later declare to Prism) some extra pieces of SPIRES protocols and/or formats code known in Prism as "processing steps".
These processing steps are optional (except for entry forms, which must have at least one processing step to invoke a screen for entry). If you prefer, you can usually avoid coding steps of your own and let Prism control the flow of your application from beginning to end.
Processing steps come in two basic flavors: screen processing steps and protocol processing steps.
Screen Processing Steps Protocol Processing Steps
- are coded in a format, - are coded in a protocol
usually as a pair of frames as a Proc (or subroutine)
per screen beginning with label and
ending with RETURN
- create screens to gather - act on user requests
information from the user or tailor the environment
(who sees them as input behind the scenes (user
screens) never sees them)
- are declared to Prism as - are declared to Prism as
steps with STEP ID matching steps whose STEP ID is the
the frame-name closely label beginning the Proc
- are always XEQ-frames - are allowed in many more
(except in entry) places than screen steps
Prism allows you to have either a screen processing step or a protocol processing step (or both) at these places in a session:
- When a file is first selected. A screen step at this point, might appear instead of, or in addition to, the conventional welcome screen, or a protocol step might perform a hidden search. [See 6.4.1 for the conventional welcome screen., 13 for hidden searches.]
- When a report is first selected. A screen step might override or supplement the report's introductory screen. A protocol step might perform a hidden search. [See 10.7, 13.]
- When a report is generated, either by the DISPLAY REPORT command or the PRINT command.
- When an entry form is selected. Again, a screen step might override or supplement the entry form's introductory screen, or a protocol step might perform a hidden search. [See 11.6, 13.]
- Throughout a data entry transaction initiated by the CREATE or GET command. [See 11.]
A protocol processing step (but not a screen processing step) is allowed at these points in the Prism session:
- As part of custom processing of an individual search type. [See 13.]
- Before a search, or at the end of a search (i.e., after the search has been performed but before the search result is actually displayed to end-users.)
- Just after an end-user issues the SEND command, in data entry, to enter a new record into the data base. [See 11.4.]
- When an end-user exits your file.
- When an end-user leaves one of your reports.
- When an end-user leaves one of your entry forms.
Here is a chart giving the same information organized in a slightly different way:
SCREEN PROTOCOL
STEPS ALLOWED STEPS ALLOWED
------------- -------------
At file-selection yes yes
At clearing of select no yes
As part of processing no yes
a search type
Before/after a search no yes
At report-selection yes yes
At clearing of report no yes
At report generation yes yes
(DIS REPORT or PRINT)
At form-selection yes yes
At clearing of form no yes
During data entry yes yes
(e.g., between
CREATE and SEND)
After SEND command no yes
Thus processing steps alter Prism's automatic control of an application's movement only at very specific points. Steps can come into effect 1) at the "beginning" or selection of an entity (a file, form or report), 2) at the "ending" of that same entity, when end-users leave it, and 3) at a specific point in the middle of the entity, during a transaction that can be repeated several times, such as searching a file or entering a record:
(Steps at File selected Report selected Form selected
beginning) : : :
: : :
: : :
: : :
(Steps in Processing Processing Processing
middle -- a search PRINT or data entry
can be DIS REPORT
repeated) : : :
: : :
: : :
(Steps at File exited Report cleared Form cleared
end)
Although screen processing steps and protocol processing steps are coded and stored in two different places (in a SPIRES format and a SPIRES protocol, respectively), all steps for a given task are declared to Prism together in Prism Profile. The way you declare a step is to fill in a table in Prism Profile with the step's unique "step id". The "step id" is an identification code of your choosing (16 characters maximum) that uniquely identifies that particular step. Once you have chosen a step id for a step, your frame-name (for a screen processing step) or Proc label (for a protocol processing step) must closely match the step id, in a manner described later in this chapter.
Important: note that, when you are declaring more than one step for a single task, the order in which you declare the steps will determine the order in which they are performed in Prism. The order of steps in Prism Profile will override the order of Procs in a protocol, and it will override the order of frames in a format.
For example, suppose you have installed a file of fiscal data into Prism, and you want to code processing steps for when the file is selected. The first (screen) step might ask end-users whether they prefer "historical" or "current-only" fiscal data, and the second (protocol) step would then set whichever view they request. Suppose you then gave the first step a step id of ASKVIEW and the second step a step id of SETVIEW.
- The first of these steps would be coded in your display ASKVIEW.OUT.
- The second of these steps would be coded as a Proc in the protocol whose key is simply FILE. The Proc's label would be ++SETVIEW.
- But both steps, the protocol step and the screen step would be installed together in a single table in Prism Profile, using either MOD PROFILE or ADD PROFILE, where the table would look like this:
STEP# STEP ID TYPE TITLE/COMMENT 1 ASKVIEW_________ s Welcome to Budgets File_____ 2 SETVIEW......... p (Set a view of the file)....
(TYPE and TITLE/COMMENT are explained later in this chapter.)
Because of the order in which the steps were installed, the ASKVIEW step would be executed before the SETVIEW step. In other cases you might install a protocol step to precede a screen step and be executed first. For instance, you might perform a hidden search first through a protocol step, then have a screen step inform end-users that a search was automatically performed for them. [See 13.] In any case, the order of step installation in Prism Profile determines the order of step execution in Prism.
Screen processing steps provide an opportunity for your application to request specific information from end-users -- information that affects the processing of subsequent commands. For instance, a screen might ask end-users for an authorization code before letting them access a particular entry form. Or, in the case of reporting, it might allow a user to specify customizing options (e.g., "detailed" vs. "summary" data) for a particular report. During data entry, screen steps can help determine the content and even the sequence of subsequent entry screens. [See 11.]
However, you should note that screen steps will add to the cost (and sometimes the complexity) of using your application. Be sure any screen step you add can clearly "pay its way" in making the file more effective.
Screen steps are not designed to access your data base and enter or change data there (except for screen steps for data entry). [See 11, 12.] Rather, screen steps are for tasks such as passing end-user information into your own parameters or variables.
To code a screen, you usually write a matched pair of format frames, one for input and one for output. (Exception: for "display-only" screens in an entry form, only an output frame is needed.) The frames go within the same format as the feature that the screen supports -- that is, a screen to support a report would be coded within the same format as the report itself, and a screen to support an entry form would be coded within the same format as the entry form it supports. A screen for a file-related task (selection and exiting of your file or processing a search), would be coded within your display format.
Frames for a screen step at...
File-selection go in your display format
Form-selection go in the format supporting
that entry form
Report-selection go in the format supporting
that report
Report-generation will go in the format for
that report (but this stage
is not fully designed)
The FRAME-TYPE must be XEQ for both frames of any screen step that is not part of an entry form. If you use Screen Definer to generate a screen that is not for an entry form (for instance, a screen prompting end-users when they select a report), make sure the SPIRES format generated contains only XEQ-type frames to support that screen. A skeleton outline of those frames would look as below:
FRAME-ID = <step-id>.OUT; FRAME-ID = <step-id>.IN;
DIRECTION = OUTPUT; DIRECTION = INOUT;
USAGE = NAMED; USAGE = NAMED;
: :
FRAME-NAME = <step-id>.OUT; FRAME-NAME = <step-id>.IN;
FRAME-TYPE = XEQ; FRAME-TYPE = XEQ;
[See 11.3 for information on screens for an entry form.]
Because of limits in Guided Mode, 17 lines is the usual maximum length for a screen step on a standard 24-line terminal. A confirmation screen (an optional screen appearing after successful data entry) can only be 15 lines maximum. [See 12 for more on confirmation screens.]
All processing steps in Prism must be identified by a "step id". In the format supporting a screen processing step, your frame names must take the form <step-id>.OUT and <step-id>.IN. E.g., for a screen processing step with step id INPUT1, you would code frames with the names INPUT1.OUT and INPUT1.IN. If you use Screen Definer, your format frames are automatically named using these conventions (where "Screen ID" in Screen Definer corresponds to "step id" in Prism Profile).
Each step id for a screen processing step must be unique in the format where it appears (because the frame-names corresponding to the step id must be unique in the format). Step ids for screen processing steps may be up to 12 characters long.
Screen step (12 char. max.) Frame-names (16 char. max.)
as installed in Prism in your SPIRES format
--------------------------- ------------------------------
<STEP-ID> or <SCREEN-ID> <STEP-ID>.OUT or <SCREEN-ID>.OUT
<STEP-ID>.IN or <SCREEN-ID>.IN
In addition to step id, every screen processing step must also have a title, to appear automatically above the screen when it is displayed online. Prism Profile will prompt you for this title when you install the step.
In general, screen processing steps in Prism need to be supported by the following help records:
?ERROR Help record describing error codes on an
input screen. (One ?ERROR record per file.)
?INPUT... "Context" help to explain input fields
of the current input screen. (One ?INPUT
record per screen for most files.)
Each kind of help will be described in more detail below.
The ?ERROR help record provides explanations of any error codes you have installed in your input screens, so that end-users can get these explanations instantly online. (Note that this error help is accessible only after your code has SET STATUS = REPROMPT or = WARN. [See 11.3.2 for more information on SET STATUS, 11.3.2a for details about error codes.]
One single record serves to explain the error codes on all of your input screens in Prism -- including all the screens of your entry forms. [See 11, 12.] Thus you can use the same error codes for all of your input screens, no matter where they occur in your application. If you have several related Prism applications using the same error codes, you may use the $XFILE control word to share a single ?ERROR record between several applications.
The ?ERROR record must follow a specific format. Each line (after the first one) starts with a hyphen, followed by the error code, followed by a colon, and ending with a one-line explanation to appear in the message line when an end-user requests help for that code during reprompting.
Below are some standard error codes and explanations used in Screen Definer, Prism Profile, and other applications. Use these codes for your own file if possible:
* ?ERROR
-AN: Only alpha-numeric values are allowed in this field.
-ID: A record with this value already exists; value must be unique.
-ME: Marked fields contain mutually exclusive values.
-RQ: Required field.
-XC: An invalid character has been input within this field.
-XV: Invalid value.
<etc.>
Error codes may vary in length, and can even be more than one word, but the error code and message together must fit within 79 columns, since they appear on the message line exactly as entered on the help record.
If one line is insufficient to explain the error, you might direct the user to fuller help:
-XV: Invalid value for CLASS. Type HELP CLASS for details.
Users of Prism entering data into a screen will also need "context help" describing the specific fields on that screen. ("Context help" is the help that appears on the screen when an end-user just types HELP or a "?", rather than asking for help on a particular term.) For instance, a screen with input fields for "Account" and "Code" would need a help record indicating what kind of Account or Code is to be input.
You provide this information in a help record whose key begins "?INPUT". The key is completed by words identifying the context of the screen, as follows:
?INPUT/FILE/<step-id> <--for a screen
at file selection
?INPUT/REPORT/<report-name>/<step-id> <--for a screen
in reporting
?INPUT/FORM/<form-name>/<step-id> <--for a screen
at form selection
or during data entry
Note: for a screen invoked by custom processing, enter "screen-id"
(from your PERFORM PRISM SCREEN commands) rather than "step-id".
E.g., a screen for the ORDER EQUIP entry form with a step id (or screen-id) of SCREEN1 would have a context help record with key ?INPUT/FORM/ORDER EQUIP/SCREEN1.
The ?INPUT help should contain information about each of the input fields and might look something like this:
* ?INPUT/FORM/ORDER EQUIP/SCREEN1
Accounts -- Enter in this field an authorized University
Account. The Account should be 7 characters.
Code -- Enter in this field your personal Budget Code.
(etc.)
You might also consider creating help records describing each of the individual fields on entry screens. For example, the ?INPUT record above could be supplemented by help records for ACCOUNTS, CODE, etc., so that end-users typing HELP CODE or HELP ACCOUNTS receive quick help for those fields. If you do this, you could use the $BIND and $XBIND control words to specify that the help records should be associated with particular entry forms or reports. [See 6.3.6.]
Like screen steps, protocol processing steps are a handy way to customize your application to meet your users; special needs. In fact, protocol steps often work in direct partnership with screen steps, by acting behind the scenes on information end-users have input into the preceding screen.
Thus one benefit of protocol steps is that they can help streamline your application and customize Prism to meet the particular needs of your application.
In addition, since Prism protocol steps can contain non-Prism SPIRES commands (with some exceptions named later), Prism developers with SPIRES experience can use a Prism protocol step to bring SPIRES commands or procedures into their behind-the-scenes Prism processing. For instance, a protocol step for custom searching might contain SPIRES Global FOR commands, which are not directly available to Prism end-users. [See 13.]
However, you should also note these possible drawbacks to using Prism protocol steps: 1) complex protocol steps may have a noticeably adverse effect on the efficiency of your application; and 2) since there is no way Prism can fully check a complex protocol step for coding errors, you will need to test it thoroughly yourself (using SET DEBUG and SET ECHO) or the step may cause errors in the execution of your application. [See 7 for information on SET DEBUG and SET ECHO.]
Technically, a protocol step consists of a series of SPIRES procedural statements (SPIRES protocol code) which you add to the PRISM PROTO subfile in SPIRES. [See 9.2.1.] After adding the record to PRISM PROTO, you install the protocol step in Prism along with its related screen steps by declaring, within Prism Profile, the name of the step and the point in a session at which the step should be invoked and executed. [See 9.3.]
Note: To write protocol steps you'll need to be familiar with some of the procedural language described in the manual "SPIRES Protocols".
Since the protocol code invoked by a processing step temporarily exits the standard Prism interface and does its work behind the scenes, users should never be aware of them. (In some cases the code may tailor the Prism environment slightly, perhaps by using the $NEXTCMD variable to issue a command behind the scenes.) Your protocol code should never alter the look of the Prism interface or the shape and meaning of Prism commands. In the few cases where protocol code does affect the general Prism environment, it should do so only by means of the system communication variables listed in Appendix A.
Your protocol code should never interact directly with end-users by issuing command prompts. All command prompts are issued by Prism itself, in order to guarantee stability for the Prism interface within and across files. [See 17 to learn how you can use $NEXTCMD to ask Prism to issue commands for you.]
To get information from your end-users, use a screen step, not a protocol step. (E.g., never issue the ASK command.) Prism protocol code works only behind the scenes, interpreting and acting upon information gathered in some other way.
Protocol steps should never noticeably slow system response time. If a protocol needs to perform a time-consuming task, or one that can't be finished immediately online (e.g., batch printing), alert your users beforehand -- Prism has no way of sending a message while the job or task is in process. One possibility is to code a screen step preceding the protocol step, asking users whether they want the processing to be deferred.
All of your protocol processing steps for general file-related tasks (selecting, searching, and leaving the file) go into one protocol. All protocol processing steps associated with a single report go into a single protocol, and all protocol processing steps associated with a single form likewise go into a single protocol. So, for instance, if your application has three entry forms, and all three require protocol processing steps, you will need three separate protocols, named according to the conventions shown below.
Protocols used in Prism must have standardized names as shown in the box below. No blanks are allowed between text and slashes, although the "report-name" or "form-name" may contain blanks: thus "FORM/mod forms" would be valid, but "FORM / mod forms" would not be. Note that the part of the name that is capitalized must be entered exactly as shown; you substitute your own values for the bracketed part of the name:
PROTOCOL'S FUNCTION PROTOCOL'S NAME
File-selection, file-exit, * FILE
searching
Reporting: selection, exit * REPORT/<report-name>
or generation of report e.g., REPORT/labels
Form-selection, exit * FORM/<form-name>
and all data entry e.g., FORM/mod profile
(<report-name> and <form-name> are 12 characters max.)
All protocol code for Prism is stored in a central SPIRES protocols subfile called PRISM PROTO (alias PRISM PROTOS). You may work on your protocols in SPIRES or from within Prism with the XSETUP PROTOCOL command. [See 8, 8.2.]
When you select the PRISM PROTO subfile in SPIRES, you are asked for the file-id of the application that the protocol supports. For example, to begin adding a protocol record for an application with file-id PRISMTEST:
-> select prism proto -Enter your Prism file's file-id (press RETURN for help) :File-ID? prismtest ->
As a shortcut, to bypass the "File-ID" prompt, you can include the file-id in your SELECT command:
-> select prism proto, prismtest ->
The file-id that you enter when you select PRISM PROTO determines which protocols you may see, add, and update.
To add a protocol record, assemble the protocol's statements in your active file. The first line must have an asterisk in column one, followed by the protocol's name. For instance, a protocol record for a report called LABELS, with protocol step STEP1, would be formatted as follows:
* Report/Labels
-$SUBJECT Report Labels <--optional, but helps retrieve
: the protocol in a later search
++Step1
(protocol commands)
:
Return
Use standard SPIRES commands to work with the records: e.g., ADD to add a new record, TRANSFER and UPDATE to modify a protocol record, and so on.
Technical note: internally, PRISM PROTO prefixes the key of your protocols with your application's file-id. Thus the internal form of the key differs from the form you see when you search and display records in the subfile. You'll use this prefixed key if you compile your protocol (as described in the next section), or if one of your Prism protocols executes code from another.
You may include two file-ids in your SELECT command if you wish to maintain protocols for two applications (for example, a test and production version of an application) without having to reselect the file for the different file-ids:
-> select prism proto, tevents/pevents ->
Alternatively, you may select PRISM PROTO MAINT if you need to maintain protocols for a number of applications. You are not asked for a file-id at all when you select this subfile.
-> select prism proto maint ->
If you have specified two file-ids or selected PRISM PROTO MAINT, you must work with full and complete protocol keys, including the file-id. This applies to commands such as TRANSFER and DISPLAY:
-> tra pevents:file
or
-> dis tevents:report/labels
It also applies to the form of the protocol name that you type in the first line of your active file:
* pevents:file ... [your protocol code]
Note that when you are doing Global FOR operations, you only have access (in effect) to protocols for the first file-id of the pair you specified. For example:
-> select prism proto, tevents/pevents -> find fileid pevents or tevents -Result: 20 PROTOCOLS -> for result +> remove all <-- this would only remove TEVENTS (1st file-id) +> Removed: 10 record(s)
The PFORMAT command (a WYLBUR command) reformats protocols code in your active file, providing a standard indention style. (For details, in SPIRES, EXPLAIN PFORMAT.)
You can use standard SPIRES tools for printing and searching your protocols, such as the PERFORM PRINT command:
-> perform print 'FORM/MOD REPORTS' <--(use apostrophes
or if the key
-> for subfile contains blanks)
+> perform print all
Control words such as -$PAGE, -$TITLE, -$SUBJECT, -$AUTHOR, and -$FORMAT ON help clarify the structure of the printed listing, and make it easier to retrieve the protocol by searching. (In SPIRES, type EXPLAIN PERFORM PRINT COMMAND, WITH PROTOCOL FILES for more information on printing protocol records.)
When Prism loads an application, it will keep in memory the FILE protocol that contains any file-level protocol steps. Similarly, the protocols belonging to a form or report are also loaded once. But protocol steps often bring in other SPIRES resources as they execute. For instance, a $LOOKSUBF will bring a new file's characteristics into memory when first executed, and SPIRES keeps such file references in memory to optimize repeated use of such lookups.
In a complex environment like Prism, the timing of how pieces of an application are loaded can make a difference in how effectively memory is used. If "permanent" resources (such as a new format or a $LOOKSUBF) are brought into memory intermixed with temporary resources (such as a referenced record), then memory can become fragmented as holes are created when those temporary resources are released.
A technique called preloading can be used to bring resources into memory early, before they are explicitly referenced. This helps assure that parts of your code that are used more than once are brought into memory early and together, without fragmenting the available space. Generally preloading is only needed for large, complex applications using many resources and where code is likely to be called multiple times during a transaction.
In Prism protocols, the DECLARE PRELOAD statement may specify the pieces of code that you would like Prism to preload when the file, report, or form is first selected. This facility provides four benefits.
- It is more convenient to have Prism perform the preloading operation rather than code a variety of preloading techniques yourself as part of a file, form, or report protocol step.
- It is the only way to establish subgoal access to files that are PRISM privileged only (protected by PROGRAM=PRISM).
- Prism is aware of secondary resources used by your application and can cleanup memory automatically. This is more efficient than coding CLEAR steps for the same purpose, but it also makes it possible for Prism to clean up even after CANCELs or errors.
- Prism attempts to preload many resources automatically. It is usually aware of PERFORM PRISM LINK and PERFORM PRISM ROUTE. However, applications that "nest" protocols -- call a secondary protocol from the protocol step -- will need to preload these resources explicitly if they are only found in the nested protocol.
DECLARE PRELOAD is followed by statements naming the code to be preloaded:
DECLARE PRELOAD
VGROUP vgroup-name
DYNVAR dynamic-variable-name
LOOKSUBF subfile-name
LOOKSUBG record-type
LOOKSYS looksys-type
LINK fileid [, FORMAT format]
PROTOCOL protocol-name
ROUTING
ENDDECLARE
The end of the PRELOAD declaration section is signalled by an ENDDECLARE statement. [See 12a.2, 10.8 for other possible DECLARE statements.]
Prism allows a maximum of 160 declared "resources" per file select. This includes preloads and also events declared in the DECLARE SCREEN section of your protocol. 120 of those resources may be events. [See 12A.2.] (It also includes resources loaded on your behalf by Prism, such as those needed for a routing application to work.)
Here are explanations of the options:
VGROUP -- causes Prism automatically to set (allocate) the named vgroup at time of file-selection (or report-selection or form-selection) and to clear the vgroup upon leaving the file (or report or form). Thus you do not need to issue a SET VGROUP or ALLOCATE command within your protocol code to set a vgroup, nor do you need to include a protocol step solely to deallocate or clear vgroups, since DECLARE PRELOAD will do this automatically.
If you use the DECLARE VGROUP feature in your protocols, you do not need to use DECLARE PRELOAD VGROUP, since SPIRES will manage the loading and unloading of vgroups automatically.
DYNVAR -- tells Prism that the application will be creating dynamic variables (probably arrays). In the case of a CANCEL or a system error, Prism will check the dynamic variable references and clean up afterwards. Note that DECLARE PRELOAD DYNVAR only handles a single variable or a continuous array starting from 0 or 1.
LOOKSUBF/LOOKSUBG/LOOKSYS -- causes Prism automatically to establish an internal subgoal path to subfiles or record types that you will use in later lookups. The path is established early, and is established under Prism control, so that preloading a lookup to files with PROGRAM=PRISM statement is possible.
LINK -- tells Prism of a PERFORM PRISM LINK that will be issued in another protocol that this protocol step will be calling (and preloading). Note that normally the existence of a PERFORM PRISM LINK command in your protocol step automatically causes the link to be automatically preloaded. Therefore, the DECLARE PRELOAD method is only needed when your main protocol calls another protocol, which performs a LINK that Prism otherwise wouldn't have known about in advance. [See 16 for more on PERFORM PRISM LINK.]
PROTOCOL -- causes Prism to preload into computer memory any secondary protocol that a main protocol calls. This is useful, for instance, if you share protocol code by having a small main protocol invoke common code.
ROUTING -- tells Prism to preload its routing code components. This is needed when your PERFORM PRISM ROUTE command is not in the main protocol but instead in a "nested" protocol. (If it is in the main protocol, Prism automatically preloads the routing code.)
The example below shows the DECLARE PRELOAD statement near the beginning of a protocol, but it can appear wherever you wish.
* FORM/MOD SALARY - comments DECLARE PRELOAD LOOKSUBF PERSONNEL ENDDECLARE ++LABEL :
The DECLARE PRELOAD statement supersedes the -$PRELOAD control word. Either form of PRELOAD declaration is recognized in Prism protocols. Here is the syntax of the -$PRELOAD statement:
-$PRELOAD VGROUP vgroup-name -$PRELOAD DYNVAR dynamic-variable-name -$PRELOAD LOOKSUBF subfile-name -$PRELOAD LOOKSUBG record-type -$PRELOAD LOOKSYS looksys-type -$PRELOAD LINK fileid [, FORMAT format] -$PRELOAD PROTOCOL protocol-name -$PRELOAD ROUTING
The protocols associated with your Prism application can run either compiled or uncompiled. In virtually all cases, it is strongly recommended that production applications use compiled protocols. Compiled protocols execute more efficiently than uncompiled ones, and this is an important consideration for CPU usage and response time in Prism.
Complete details on compiling any SPIRES protocol can be found in the "SPIRES Protocols" manual.
In addition to actually compiling your protocols, you must tell Prism to use them in compiled form. To do this, answer "yes" to this question:
Enter 'Yes' if protocol steps are compiled: Yes
which appears in the places where you install protocols (XSETUP PROFILE, XSETUP FORM, XSETUP REPORT, or the corresponding entry forms in Prism Profile).
Compiling a Prism protocol is just like compiling any other SPIRES protocol, with the small exceptions noted below if you use the SYS PROTO technique.
Prism protocols, like other SPIRES protocols, may use the DECLARE VGROUP feature introduced in February 1994 as a more convenient and improved alternative to using SYS PROTO records. If you use DECLARE VGROUP, you may issue your COMPILE or RECOMPILE command directly from the Prism Protos subfile. Or, in the unlikely case where you have no variables to declare, you may simply compile from Prism Protos without DECLARE VGROUP. For example:
-> select prism protos
-Enter your Prism file's file-id
:File-ID? testfile
-> tra report/mail labels
:
<make changes to your protocol>
-> upd
-> recompile 'report/mail labels'
Note that if your protocol name contains blanks, you will need to enclose it in quotes in the COMPILE / RECOMPILE command.
If you use the SYS PROTO technique of compiling your Prism protocol, follow the pattern below for your SYS PROTO record:
ID = <gg.uuu>.<file-id>:<protocol.name>; FILE = $PPRISM; RECORD-NAME = REC03; PROTOCOL = <file-id>:<protocol name>;
The FILE value is always "$PPRISM" and the value for RECORD-NAME is always "REC03".
For PROTOCOL, supply the full key of the protocol, with your application's file-id prefixed to the name of the protocol, separated by a colon. For example, for the protocol "REPORT/MAIL LABELS" in an application with file-id "TESTFILE":
PROTOCOL = TESTFILE:REPORT/MAIL LABELS;
| |
file-id protocol's name
For ID, use the value for the PROTOCOL element, prefixed with the account of the file-owner of the SPIRES file supporting the application. (Replace any blanks in the protocol's name with periods.) For example:
ID = GQ.ELL.TESTFILE:REPORT/MAIL.LABELS; <---note the period
Thus the SYS PROTO record for the protocol "REPORT/MAIL LABELS" in an application with file-id "TESTFILE" might look like this:
ID = GQ.ELL.TESTFILE:REPORT/MAIL.LABELS; FILE = $PPRISM; RECORD-NAME = REC03; PROTOCOL = TESTFILE:REPORT/MAIL LABELS;
Prism protocols always consist of separate subroutines or 'Procs'. Each Proc is headed by a label statement that identifies the Proc and exactly matches its step id (see below), and each Proc ends with the RETURN command, in order to return control to Prism.
Protocols for Prism must be structured in these separate labeled blocks of code. (By contrast, SPIRES protocols outside Prism can consist of a sequential series of commands read "from the top down".) The Prism protocol can contain additional Procs whose label does not correspond to a step id and which are used as internal subroutines, or there may be additional labels for branching, but the structure of the protocol must be determined by its step-related Procs.
Thus a protocol step might look in outline something like this:
* FILE
++STEP1 (STEP1 here is the name of the first
: step and would be installed by that
: name in Prism Profile)
:
++SUB.STEP (SUB.STEP here is an optional Proc or
: subroutine within STEP1 - it would
: not be installed in the Profile)
:
RETURN
++ANOTHER.STEP (ANOTHER.STEP names here another
: protocol step installed by name in
: the Profile)
:
RETURN (Every installed step would end with a
RETURN statement to return control to
Prism)
Thus, even though each protocol step in Prism corresponds to a Proc (labelled with "++"), not everything labeled with the "++" in the protocol necessarily corresponds to a step id installed in Prism Profile.
The order of execution of each Proc in your protocol is determined not by its position in the protocol, but by the point at which the Proc is invoked by a processing step within Prism.
For instance, in the example below the Proc ++DO.FIRST
would presumably be executed before ++DO.SECOND:
______________________________________________________________
|
Installed in Prism Profile | Coded in the protocol
in this order: | in this order:
|
ORDER STEP ID TYPE | :
| ++DO.SECOND
1 DO.FIRST p | :
2 DO.SECOND p | :
| RETURN
| ++DO.FIRST
| :
| :
| RETURN
As stated earlier, every processing step in Prism must have a unique step id; every protocol processing step must have a step id whose name corresponds to the label statement of a Proc in the appropriate Prism protocol. (The label statement is the line of code beginning with the ++ characters.) As with any processing step in Prism, the step id for a protocol step can be no longer than 16 characters and cannot contain blanks.
Whenever Prism begins to execute one of your protocol steps, practically the first thing it does is to open a brand-new active file, in case the step needs to use an active file as part of its processing. This active file is invisible to your end-user, so you can use it for tasks such as mailing or printing data, without ever worrying about tampering with your end-user's own active file(s).
Thus commands like the following, issued within a Prism protocol step, never touch your end-user's own active file:
++PRINT.DATA /Wdse #PrintOptions In Active Cont Display All <---Displays data into a /Print to $Account temporary active file, not Return the user's active file
This temporary active file is closed and discarded as soon as your protocol step passes full execution control back to Prism (i.e., when your protocol step issues its RETURN command to return control to Prism). Within the step, however, the active file remains stable for your use. A protocol step can pass temporary execution control to Prism with a command such as PERFORM PRISM SCREEN, trusting that the initial active file will be intact when Prism passes control back to the protocol. [See 12.]
If you need to use a single active file over more than one protocol step, you will have to save it temporarily as a data set within the first step (e.g., SAVE dataset TEMP) and access it (eventually scratching it if necessary) within the second step.
Prism sets message numbers ($SNUM, $PSNUM, $ENUM, and $MNUM) to 0 before calling your protocol code. From this point on, your code should trap errors, branch to appropriate code, or set $STATUS and return control to Prism.
Set the $STATUS variable to 'STOP' and then RETURN when you want to return control to Prism so that an error message can be displayed. For example:
++CheckAccess : Set MsgLine = 'You have already taken action on this item; GET not allowed' Set Status = 'STOP' <--(Set Status the last thing Return before returning)
The RETURN here is important. Prism will not "see" the new $STATUS setting until you return control to Prism from your protocol.
In this situation, Prism presents the $MsgLine text in a box on the screen, along with a generic Prism message indicating that a command has failed. $MsgLine here may be up to 256 characters long.
Forms Action Entry Form: EXAMINE 07/25/90 14:55
Forms awaiting your action 30 records
-----------------------------------------------------------------------------
*---------------------------------------------------------*
| Your transaction was not processed. |
| |
| You have already taken action on this item; GET not |
| allowed. |
*---------------------------------------------------------*
-GET command not processed
Set $STATUS to SYSERROR to indicate an unexpected command failure, as in the example below:
++Reporting Set Format $Report Options Title = 'Summary Report' If $No Then Jump Syserror : For Result In Active Continue Display All If $No Then Jump Syserror : Return : ++SysError Set Status = 'SYSERROR' Return
Setting $STATUS to 'SYSERROR' helps Prism back end-users out of system errors gracefully, while performing essential error logging.
Note that the status of 'SYSERROR' is meant to mark a totally unexpected error, probably a bug. Do not set 'SYSERROR' when your code is prepared to deal with the command failure on its own, so that the end-user can finish the requested task. Also, when you set $STATUS to 'SYSERROR' it should be the last thing you do before issuing the RETURN command.
In addition to system errors that you trap within your own code, Prism traps and reports any errors it discovers while executing your code. It's important that you trap all potential system errors while testing your application, before releasing it to production.
Prism sends immediate online notification to an application's contact account when system errors occur to end-users unless you turn this feature off using MOD PROFILE -- immediate notification is in addition to the automatic error notification that Prism sends the following morning.
If system errors do occur in a production application, they need to be trapped and fixed as quickly as possible -- if possible, within the same day (or hour) that they occur. Your Prism/SPIRES consultant can help you find the problem and fix it. You should also notify your end-user when the problem is resolved.
- on setting the message line (with the $MSGLINE variable) see the appendix on variables.
- on setting status (with the $STATUS variable) see the chapter on Entry Forms and the appendix on variables. [See 11.]
- on catching errors during data entry, see the chapters on Entry Forms and Custom Control of Data Entry. [See 11, 12.]
- on error logging, see the appendix on The Prism Log.
Relatively complex applications in Prism and SPIRES sometimes need to link to one or more additional files (or formats) behind the scenes. In SPIRES, you perform this linking using a technique called "path processing", which lets you select several subfiles (or set several formats) at the same time, using different "paths".
Path processing is available in Prism protocols too, but there is also a more efficient and secure way to link to another file within Prism:
The advantages of PERFORM PRISM LINK over path processing come in the realms of efficiency and security. PERFORM PRISM LINK uses system memory more efficiently, because it causes Prism to pre-load each of your linkages when the file is selected, rather than "dynamically" when the protocol step containing it is executed. In addition, installing a secondary file whose file definition has the PROGRAM = PRISM statement ensures effective security for the secondary file's data. [See 16.]
If you choose not to use PERFORM PRISM LINK, regular SPIRES path processing is also available. In general, you would only need to set a path in order to set an additional format:
- In searching, the primary path is left open for your use in a protocol. (Even your display format is set indirectly as a load format via a path.)
- In reporting, your protocol code can set a report format through the primary path. Or if Prism sets the report format for you, that format will be set on the primary path, and you would need to set any additional format(s) using PERFORM PRISM LINK or by setting up a path.
- In data entry, the format for the entry form that a user selects will be set through the primary path. Again, you must set any additional format using PERFORM PRISM LINK or by setting up a path.
You must explicitly specify the name of any path you set in a protocol. Don't begin the pathname with a dollar sign ($). Also be sure to clear a path when you are finished with it. There may be situations where you wish a path to span more than one processing step or transaction -- if, say they shared common variables -- but you should clear the path as soon as the task using those variables has been completed. (The path will automatically be cleared when your file is de-selected.)
For more information on this and other restrictions on protocols, see the following page.
In order to function smoothly the Prism interface counts on various internal settings and parameters remaining stable. If you change one of these settings by mistake, disaster will result -- for the interface and for end-users of your file. This section will list actions and commands that you must avoid in your protocols -- because using them would cause the Prism interface to malfunction.
Your protocol code should work behind the scenes without altering the Prism environment as end-users perceive it:
Although you can often count on using the primary path, at certain times you will need to establish secondary paths. [See 9.2.6 for information on the primary path.] These paths must be set (and cleared) with great care, so that they don't disturb the basic Prism environment:
This may seem to be quite a few restrictions, but in actual practice, since your protocol code and Prism are working toward the same goals, conflicts in coding patterns should rarely arise.
Processing steps, when they are necessary to your application, should be declared in Prism Profile as follows:
- Processing steps for general file-related tasks (selecting a file, clearing the select and processing a search result) must be declared in ADD PROFILE for a new application, or MOD PROFILE for an existing application. [See 4.1 for sample screens where this is done.]
- Processing steps associated with a report must be declared in MOD REPORTS. [See 10.6 for sample screens showing this process.]
- Processing steps associated with data entry must be declared in MOD FORMS. [See 11.5 for sample screens showing this process.]
The process of declaring steps is basically the same in all of these cases, except that there are some special options available to you for controlling the flow of an entry form. These special options will be discussed later. [See 11.]
The general method of declaring processing steps to Prism follows this pattern:
Enter 'Yes' to see screens for declaring steps - when the file is selected or cleared: Yes - when search is completed: Yes
STEP# STEP ID TYPE TITLE/COMMENT
1 <step-id>... s Input Screen.............
2 <step-id>... p (Act on previous input)..
3 ............ . .........................
STEP# STEP ID TYPE CONDITIONS
1 <step1>..... S No........
2 <step2>..... P No........
3 <step3>..... P No........
1 <step1> DO ONLY IF: ....................... 2 <step2> DO ONLY IF: .......................
Conditional execution would probably depend on variables that had been set in your format: for instance, DO ONLY IF: #MOREDATA = $TRUE.
A rule of thumb for special conditions anywhere in Prism: any syntax allowed between IF and THEN in SPIRES is allowed in the syntax of a special condition in Prism.
One important thing to remember is that steps are executed from the top down. It is the order of installation of steps that determines their order of execution (the order of their coding within a format or a protocol should generally make no difference). In the cases where you need to manipulate the order of step execution, you may be able to apply some of the complex methods discussed in later chapters in regard to data entry. [See 12.]
You should validate the names of your step ids as you install them: Prism will not check their validity until run-time when they are invoked. So, for instance, if during data entry Prism can't find one of the screens you have named, it will terminate the entry cycle with a system error.
To remove a processing step, choose the appropriate form in Prism Profile, page forward to the screen where you first declared the step, and delete its step id.
If you want to remove a special condition, page forward to the screen where you specifically declared what the condition was, (e.g., the DO ONLY IF page) and blank out the conditional text from the field.
In addition to providing for searching and display, Prism lets you create pre-defined reports for your users, as well as entry forms for data entry. This chapter covers how to create and install pre-defined reports.
Prism also allows users to create Personal Reports, which are based on the reporting fields you install for your file. [See 5 for more on Personal Reporting.]
Reporting covers the middle branch of the familiar diagram:
WELCOME TO PRISM
|
Select a file or
service
|
(User selects your file)---> |
Welcome to
the file
/ | \
(Search) / |REPORT \ (Entry)
/ | \
(Search performed Pick a report
either before |
(A) -------------------------------------------------------------------
or after report |
is selected) |
|
DISPLAY REPORT
or PRINT
Your report format is set at point (A) when end-users select the report, and is cleared when end-users pick a different report, a different activity (such as Entry), a different file, or when they leave Prism.
A pre-defined report in Prism is a packaged view, usually of a set of your file's records taken as a whole. Where the numbered FULL and BRIEF displays emphasize individual records, reports often emphasize records in homogenous groups or clusters (and often include summary statistics for each group or cluster). Thus in a report the dividing line between individual records need not be clearly marked, since the report takes on its meaning as a whole, not simply on a record by record basis. A report's best reason for existing may be that it provides a grouping or summarizing function that single-record displays by nature do not provide.
A report in Prism can also be a means of providing end-users with special materials (for instance, a document) that are not directly derived from your data base. [See 10.2.]
If the main purpose of your report is to offer end-users a special format (besides BRIEF and FULL) for printing records, you may want to consider installing an additional display instead of a report. [See 3.4.]
The advantage of an additional display is that your end-user doesn't have to issue the REPORT command before using the formatted display. For instance, suppose your end-user has just added a new record and wants to print it with a format that has the same "look" as the entry form that was used to add the record. You could install such a format as an additional display instead of a report -- then when the end-user types PRINT, the additional display will appear automatically as one of the "formatting" options to choose from.
To support reporting in your Prism application, here are the steps to take:
The rest of this chapter will discuss standards and techniques for report formats, and show how to declare a report to Prism with XSETUP REPORTS. The end of the chapter covers help records for reporting.
Many Prism reports will be created using the SPIRES formats language, though you can also create a Prism report using $REPORT commands in a protocols step. [See 10.5.] In most respects, coding a report format for Prism is the same as coding a SPIRES report format anywhere else -- you will need to be familiar with the "SPIRES Formats" document before designing a customized report format for Prism.
When you install a report (with XSETUP REPORTS) you may specify whether the report may be displayed online or only available for printing. You may also define a separate format to be used for online display only. XSETUP REPORTS provides places for separate format names for the printed and online versions of a report, if necessary. [See 10.6.]
One reason for having separate formats for printed and online versions of the report is if the printed version is wider than the 79 columns available on the Prism screen. Since there is no automatic mechanism in Prism to adjust wide-margined reports for online display, you might provide a "condensed" version for use with the DISPLAY REPORT command rather than simply forbidding display altogether. (If your frame dimensions are wider than 79 columns, an attempt to display the report online will cause S808 errors.) The two formats can be kept within one SPIRES format record, as long as they have separate format-names.
An alternative to defining two separate formats for printed and online use is to code the SET HCLIP Uproc in an initial frame of your report format. HCLIP stands for "horizontal clipping", and the effect is that for online display, the right portion of the report will simply not be displayed. You will see only what will fit in the dimensions of the Prism screen, without generating S808 errors. Even though the report will be truncated in online display, the entire wider report will be generated when it is printed. For details, EXPLAIN SET HCLIP in SPIRES.
In XSETUP REPORTS, you may specify that searching is not allowed when your report is selected. This option is useful when you supply a search result automatically in a processing step.
Enter 'Yes' if searching is permitted when this report is selected: Yes
XSETUP REPORTS lets you specify an element-list for report-sequencing that differs from the element-list you use for sequencing search displays. [See 4.1 for sequencing of search displays.]
Your report sequencing will not override display sequencing (either your automatic sequencing, or the user's SORT request) until either the PRINT or DISPLAY REPORT command is issued. But once the report-sequencing is in effect, it is used for DISPLAYs too, until the end-user performs a new search or selects a new report.
End-users of Prism can use the SORT command to sort search results in your file, taking advantage of the sorting fields you have installed. [See 5.]
If you have written a report for which the sequencing you install is basic -- so that re-sequencing the search result might destroy its meaning -- XSETUP REPORTS gives you a chance to request that the SORT command be disabled when your report is set. In fact, the default is to disable sorting within a pre-defined report [See 10.6.]
Enter 'Yes' if user-sorting is permitted for this report: No
Most likely, reports that use grouping will need to lock in sequencing in this way -- but if your pre-defined report remains meaningful even when records within it are resequenced, feel free to change the value above to a "Yes".
An "overflow" problem can arise with reports created through a SPIRES format when the report spans more than one screen in Prism. This overflow is corrected automatically for Prism reports using $REPORT commands. But if your report will be displayed online and you're using a SPIRES report format, you need to add an additional frame to the format, calling a special Prism load-format, $PRISM.OVERFLOW, to take care of paging automatically for you. The basic structure of the additional code is as follows:
FRAME-ID = OVERFLOW;
DIRECTION = OUTPUT;
USAGE = DISPLAY;
LOAD-FORMAT = $PRISM.OVERFLOW;
:
FRAME-NAME = OVERFLOW;
FRAME-TYPE = OVERFLOW;
In addition, to guarantee that information in individual label groups is not broken between two screens, it is recommended that you code the Uproc SET PUTDATA 4 in the frame-declaration for your data frames. PUTDATA = 4 ensures that each value handled by a label group within the frame is treated as a segment to be displayed in one piece. (The PUTDATA = 4 statement is also available as a Uproc within individual label groups.) If you want to create segments that are larger than individual values, you can use the HOLDATA and FLUSHDATA statements. [See 3.3.]
Incidentally, the SET PUTDATA = 4 Uproc is never needed in a Prism display format, because Prism provides this facility automatically for displays. [See 11.3.1 for controlling overflow in a REVIEW frame after data entry.]
Processing steps for reporting can be used at the following points in a Prism session:
- When an end-user selects your report. (Both screen and protocol steps can appear here.)
- After an end-user has issued either the PRINT or DISPLAY REPORT command. (Both screen and protocol steps are allowed.)
- After the successful completion of a PRINT or DISPLAY REPORT request. (Only a protocol step is allowed here.)
- When an end-user clears the report, e.g. by selecting a different one. (Only a protocol step is allowed here.)
The charts on later pages will make the timing of these access points clearer.
Note that if your application includes parm screens when the file is selected or during reporting, you must take special steps to enable the report for use with Prism's SETUP TASK command. [See 10.8.]
Here are some possible uses for processing steps in reporting:
- Processing steps at report-selection might ask for and then validate behind the scenes an authorizing code to determine an end-user's freedom of access to the report.
- Steps at report-selection time might ask end-users for their report option preferences, such as "detailed" vs. "summary", then set the report accordingly.
- A protocol step, most likely at report-selection time, might assemble the report's population for end-users, saving them the need of performing a search.
- A protocol step might issue $REPORT commands to prepare a report, in lieu of using a report format. [See 10.5.]
- Processing steps might prepare a "canned" report to access and print a document or data set associated with your file. The contents of such a report need not come directly out of your data base. (But note that reports not directly derived from your data base cannot currently be displayed online in Prism.)
- In response to the PRINT command, processing steps might ask end-users for other printing options in addition to the options specified on Prism's own PRINT screen. A protocol processing step might be used to dispatch the report itself (i.e., issue the internal PRINT command) instead of having Prism do this automatically. [See 10.3.]
- A processing step after the successful completion of a PRINT or DISPLAY REPORT request might be used to gather statistics or to reset internal information (for instance, to clear filters).
The following highly-simplified charts illustrate when extra processing steps might be applied during report-selection and report-execution. [See 10.6 for illustrations of the XSETUP REPORT screens where these processing steps are declared.] The horizontal line shows the flow of a basic Prism session, the blocks above the line show automatic Prism processes that you can override, and the blocks below the line show places where your own processing steps and help records would affect a session:
User User
selects ------>-------------------->---------------clears------------>
report report
| /|\ | /|\ | /|\
| | | | | |
\|/ | \|/ | \|/ |
PROCESSING STEPS INTRO TO REPORT PROCESSING
(A) (in place of or in (B) (?INTRO help STEP
addition to your record)
?INTRO record)
Your application should include at least one of (A) or (B) below the line, so that the report has an introductory screen. [See 10.7.]
Note that if your report uses a pre-defined search population, you could code a protocol processing step at point (A) to perform the search. The report's introductory screen at point (B) could inform end-users that the search has been performed for them.
Prism distinguishes generating a report (running the report population through the format) from dispatching the report (e.g., printing it). In the diagram below, Prism's automatic generation and dispatching are both shown above the horizontal line, because you can turn off either or both of them in XSETUP REPORTS. (In that case, your processing steps below the line would have to take care of these tasks.)
Prism Prism
(C) generates dispatches
report report
/|\ | /|\ |
(A) | | | |
User Prism's | \|/ | \|/
issues ----- PRINT ----->----------->------------------------->--------
PRINT screen | /|\ | /|\ | /|\
command | | | | | |
\|/ | \|/ | \|/ |
(B) PROCESSING (D) PROCESSING (E) PROCESSING
STEP STEP STEP
As the chart indicates, the Prism screen that asks for print parameters (A) always appears in response to the PRINT command. You cannot turn it off, though you might gather additional print-options from your end-users, by coding a screen processing step at point (B).
The processing step at (D) is for generating and/or dispatching the report output yourself (i.e. if you have turned off Prism's automatic report generation and report dispatch). This is the step labelled OUTPUT in XSETUP REPORTS.
Generally speaking, the steps at (B) are for setting up the print -- where any interaction with the user or authorization checks should take place -- while the output step at (D) actually does the work of producing the output or dispatching it.
Note that the Prism PRINT screen (A) gathers values for $DESTINATION and $PARM, based on what the end-user entered on the PRINT screen. If you decide to dispatch the report yourself, you will need to use these values in the generate/dispatch step (D). An easier way to control dispatching of a report, rather than to dispatch it yourself, is to enter PRINT defaults in XSETUP REPORTS as shown later in the chapter.
An important rule to remember: Prism can only generate a report for you (C) if the report consists of either a search result or stack from your data base. This restriction applies to online display (DISPLAY REPORT) as well as to offline printing. Thus, for instance, if your report actually accesses a data set, you will need to turn off Prism's automatic report-generation and instead "generate" the report yourself in a processing step.
At point (E) -- after the successful completion of the PRINT request -- you could code a protocol processing step (labelled CLEAR in XSETUP REPORTS) to record statistics, clear filters, or accomplish other tasks.
Users may request that a report be printed during off-peak hours or overnight, by choosing one of these options on the PRINT screen. To do this, Prism submits a batch job which recreates the essentials of the online environment up until the point of output generation, then proceeds to complete the user's print request. When a user requests deferred printing, only the processing steps marked (B) in the above diagram are executed online. The others, at (D) and (E) occur in the batch.
Processing steps for a DISPLAY REPORT request are a little bit simpler than steps after a PRINT request.
User Prism Prism
types ------------------->---- generates ------ displays -->-----------
DISPLAY | /|\ report report | /|\
REPORT | | (B) (C) online | |
\|/ | \|/ |
(A) PROCESSING (D) PROCESSING
STEPS STEP
You can use processing steps at point (A), e.g., to get some sort of title for the online display. You cannot turn off Prism's generation (B) of the report if the report is to be displayed online. Nor can you turn off Prism's control of display at point (C).
At point (D) -- after the successful completion of the DISPLAY REPORT request -- you could code a single protocol processing step (labelled CLEAR in XSETUP REPORTS) to record statistics or for some other purpose.
Remember that Prism currently can only generate a report for you (i.e., run the report through its format) if the report consists of either a search result or stack from your data base. Thus a report accessing a computer file, say, can be output with the PRINT command but not with DISPLAY REPORT.
"Generating report output" refers to the process by which the formatted report data is created. For most reports, this means running the report population (a stack or result from your file) through a SPIRES report format. And for most reports, Prism can automatically generate the output, and you don't need to think about this process yourself.
In more precise terms, Prism generates report output by issuing a TYPE command against the current stack or result. If your report processing requires any other operation, then you'll need to generate the report yourself. One example of when you might need to do this is if a report simply provides access to a dataset. In this case, "generating report output" means issuing the commands to gain access to the data and prepare it for printing (dispatch).
The next step after generating report output is "dispatching" the output -- that is, printing it (or mailing it or saving it in a computer file, depending on what the user requests).
If you are generating report output, you must do it in the protocol step labelled OUTPUT in XSETUP REPORTS.
You may also dispatch (print) the report output yourself, if you wish. If you choose to do this, you must use the same OUTPUT protocol step for this purpose. [See 10.4.] That is, the OUTPUT step is used for both generation and dispatch of the report output.
If you generate report output yourself, you must turn off the DISPLAY REPORT command (by answering the applicable question in XSETUP REPORTS). It is a good idea to explain on your report's introductory screen that this has happened and that one must use the PRINT command to get a printed (or downloaded or mailed) copy of the report.
You might also consider whether searching should be turned off while the report is set. This is not a technical requirement, strictly speaking. But if your report performs a task that is clearly unrelated to looking at records from the database, you might want to emphasize this by disabling FIND and SORT.
In XSETUP REPORTS, if you are going to generate report output yourself, first answer "no" to the questions about generating output and whether display is permitted:
Prism or the application may generate and/or dispatch output from PRINT.
Enter 'Yes' if Prism should generate the output: no
Enter 'Yes' if Prism should dispatch the output: ___
Enter 'Yes' to see screen to add or modify default Print Parameters: ___
Enter 'Yes' if on-line report display is permitted: no
Then ask to see screens for adding processing steps related to PRINT:
Enter 'Yes' to see screens to add, modify, or delete processing steps.
- when this report is selected or cleared: ___
- before or after PRINT REPORT: yes
- before or after DISPLAY REPORT: ___
Prism gives you as many as three processing steps for preparing your report for printing, one protocol step for generating and/or dispatching the OUTPUT and one protocol step to CLEAR the report. You might use the three "set up" steps to set filters, check an authority file, or prompt the user for a report name. As mentioned above, the actual generation of the output must take place in the protocol step named OUTPUT below:
Processing steps to prepare the report for printing:
STEP# STEP ID TYPE TITLE/COMMENT
1 ____________ _ ________________________________
2 ____________ _ ________________________________
3 ____________ _ ________________________________
Processing step to generate or dispatch output (occurs after Prism
generation and before Prism dispatching, if applicable):
OUTPUT ____________ P ________________________________
Processing step at completion of report print:
CLEAR ____________ P ________________________________
Prism automatically opens a new active file for each of your protocol steps. [See 9.2.4.] (The end-user never sees this active file and never knows of its existence.) Thus a single active file remains open for use by your code throughout any given protocol step, even if the step temporarily passes control back to Prism (e.g., with the PERFORM PRISM SCREEN command). In earlier versions of Prism, it was often necessary to write data to the end of the end-user's own active file and delete the lines when finished, but this is no longer required.
"Dispatching report output" refers to printing the report (or mailing it or saving it in a computer file, if requested by the user). In most cases, Prism can dispatch printed output itself (e.g., Prism's code, not yours, will usually issue the internal PRINT command). However, you can turn off Prism's automatic dispatching if you prefer to dispatch the report yourself through a protocol step, and have your own code issue the internal PRINT command.
The most likely use for custom dispatch is to "lock" options into a report. For instance, if you absolutely want to forbid users to print a report in the daytime, even in emergencies, you would need to dispatch this report yourself in a protocol step. Otherwise, users might override your "overnight" parameter when they reach the Prism PRINT screen.
Besides dispatching the report output yourself, there is another way that you can control printing options for your report. As part of installing a report you can request customized PRINT parameters -- these parameters include:
- The syntax of the PRINT command issued internally by Prism. By default, Prism issues the command PRINT UNN CC CHARS=TN12.
- The timing of the report's generation and dispatch. (E.g., you can specify that the report be generated and dispatched by default at night, when rates are lowest.)
- The default destination of the report. (E.g., you can specify that the report should by default be printed at Forsythe.)
In order to take advantage of these features, you do not have to go to the trouble of dispatching the report yourself (i.e., issuing the PRINT command within your own code). Instead, you simply need to fill in the applicable screen in XSETUP REPORTS. [See 10.6.]
To dispatch your report, you will need to code a protocol processing step (installed as the OUTPUT step in XSETUP REPORTS) in which you issue the PRINT (or MAIL or SAVE) command to produce the report output. Your OUTPUT protocol step is executed after the PRINT screen is presented to the user. [See 10.2 for more about timing of report protocol steps.]
When the user completes the PRINT screen, the $DEST, $DESTVAL, and $PARM variables are assigned values. $DEST and $DESTVAL tell where the output is to be directed (e.g., printer, file, email address), while $PARM carries associated options such as forms for printing or filename. [See 17.2 for details about values assigned to these variables.] Your protocol step would most likely test these variables and use the values to construct a PRINT, MAIL, or SAVE command.
In XSETUP REPORTS, if you are going to dispatch report output yourself, first answer "no" to the question about dispatching output:
Prism or the application may generate and/or dispatch output from PRINT.
Enter 'Yes' if Prism should generate the output: ___
Enter 'Yes' if Prism should dispatch the output: no
Then ask to see screens for adding processing steps related to PRINT:
Enter 'Yes' to see screens to add, modify, or delete processing steps.
- when this report is selected or cleared: ___
- before or after PRINT REPORT: yes
- before or after DISPLAY REPORT: ___
The dispatch must take place in the protocol step named OUTPUT below:
Processing steps to prepare the report for printing:
STEP# STEP ID TYPE TITLE/COMMENT
1 ____________ _ ________________________________
2 ____________ _ ________________________________
3 ____________ _ ________________________________
Processing step to generate or dispatch output (occurs after Prism
generation and before Prism dispatching, if applicable):
OUTPUT ____________ P ________________________________
Processing step at completion of report print:
CLEAR ____________ P ________________________________
If you are unfamiliar with SPIRES report formats, you can create a simple Prism report relatively quickly, by using either Report Definer or $REPORT and storing the resulting report commands as a Proc in a Prism protocol.
Although you need to know some basic SPIRES to create a report with either of these tools, you do not need to know anything about full-screen programming or the SPIRES formats language. See the "SPIRES Searching and Updating" manual if you would like more information about either $REPORT or Report Definer.
One small limitation to reports created from $REPORT code that will be displayed online in Prism: the header must be the $REPORT default header -- the customized headers available in SPIRES are not supported in Prism.
Here are the steps to create a report protocol out of a $REPORT report:
For example, here is a protocol for a report named ROSTER, with a step-id of STAFF.REPORT:
* report/roster ++STAFF.REPORT SET FORMAT $REPORT OPTIONS TITLE = 'Staff Report' SET FORMAT * + name(1,25,HEADING='Name') SET FORMAT * + work.title(+2,20,HEADING='Title') SET FORMAT * + phone(+2,9,HEADING='Extension') SET FORMAT * + work.location(+2,20,HEADING='Location') return
Note that in XSETUP REPORTS, when Prism asks for the report format name, you should leave that space blank:
Prism can set the report format, or it must be set in a processing step.
If Prism should set it, enter its name: _________________________
Then, enter "yes" to declare processing steps for when the report is selected:
Enter 'Yes' to see screens to add, modify, or delete processing steps.
- when this report is selected or cleared: Yes
On the screen for declaring processing steps, enter the step-id:
Processing steps for when report is selected:
STEP# STEP ID TYPE TITLE/COMMENT
1 staff.report____ P Roster report___________
To install or modify a report of your own, use the XSETUP REPORTS command (or the MOD REPORTS entry form in Prism Profile). XSETUP REPORTS is one of a family of XSETUP commands with which you may maintain your application. [See 8 for more information about XSETUP.] As with all XSETUP commands, type XSETUP REPORTS while you have your own application selected.
An alternative to XSETUP REPORTS is the MOD REPORTS entry form in Prism Profile. Both tools provide the same function (and the screens shown for both are almost identical), but XSETUP REPORTS offers the convenience of being able to maintain your application without having to move to Prism Profile.
Here is an example of the first screen of XSETUP REPORTS, if you already have at least one report installed. (If you don't yet have any reports, you are taken directly to the screen shown on the next page.)
_____________________________________________________________________________
United States XSetup Report 04/06/90 14:03
Select Function
-----------------------------------------------------------------------------
_ <-- Type the number of the function you want to perform (1-3).
1. DEFINE a new report.
2. MODIFY or REMOVE an existing report.
3. CHANGE the order of reports on the Prism REPORT menu.
___ <-- For MODIFY or REMOVE, type a number from the list below.
1. CAPITALS State Capitals (including date of statehood)
2. REGIONS Regional Report (includes area and zip codes)
<etc.>
_____________________________________________________________________________
Here, you indicate the task you want to do -- defining or modifying a report definition, or changing the order in which reports are listed.
The list in the bottom of the screen includes all reports currently defined for your application.
Here is the screen where you give the details about an individual report:
_____________________________________________________________________________
United States XSetup Report 04/06/90 14:03
STATES: Report
-----------------------------------------------------------------------------
To remove, enter 'R': _
Enter the following information as it should appear on the report menu:
NAME of report DESCRIPTION for this report
____________ ______________________________________________
Prism can set the report format, or it must be set in a processing step. If
Prism should set it, enter its name: ....................................
Prism or the application may generate and/or dispatch output from PRINT.
Enter 'Yes' if Prism should generate the output: Yes
Enter 'Yes' if Prism should dispatch the output: Yes
Enter 'Yes' to see screen to add or modify default Print Parameters: Yes
Enter 'Yes' if on-line report display is permitted: Yes
If on-line display is permitted and a separate format is defined for online
display, enter its name: .........................
_____________________________________________________________________________
If you asked for default print options on the previous screen, this next screen lets you declare them:
____________________________________________________________________________
United States XSetup Report 04/06/90 14:03
STATES: Default Print Options for report SUMMARY
----------------------------------------------------------------------------
Enter internal WYLBUR PRINT options to use in dispatching the report:
PRINT UNN CC________________________________________________________
If this report REQUIRES landscape printing, type an "X" here: _
Enter default PRINT values. Leave blank if user's defaults should be used.
_ <-- WHEN to generate report: (1 = now, 2 = tonight, 3 = after peak)
__ <-- INDENT for Forsythe, Department, Attached printing or Fax
___ <-- LANDSCAPE for Forsythe, Department, Attached printing or Fax
1_ <-- Where to print
1. Forsythe 3. Attached printer 5. Download/save file
2. Department printer 4. Electronic mail 6. Fax
--------------------------------------------------------------------
Copies: __
Options: __________________________________________________________
____________________________________________________________________________
- Now means the report is generated and output at the time the user makes the request.
- Tonight means the report is generated and output later during the same night as part of a batch job that Prism submits. Since night rates are lower, this option saves users money, though they receive their output later.
- After peak means the report is generated and output at non-peak time (i.e., not between 10-12 or 2-4 on weekdays).
On the next screen you declare various additional features:
______________________________________________________________________________
United States XSetup Report 04/06/90 14:03
STATES: Report SUMMARY, continued
------------------------------------------------------------------------------
Enter 'Yes' if searching is permitted when this report is selected: Yes
Enter 'Yes' if user-sorting is permitted when this report is selected: No_
Enter elements to be used to sequence results:
................ ................ ................ ................
Enter 'Yes' to see screens to add, modify, or delete processing steps.
- when this report is selected or cleared: No_
- before or after PRINT REPORT: No_
- before or after DISPLAY REPORT: No_
Enter 'Yes' if the protocol processing steps for this rept are compiled: No
Indicate all accounts, groups, or access lists that may select this report:
gq.pup.testgroup____________________________________________________________
____________________________________________________________________________
____________________________________________________________________________
______________________________________________________________________________
The next series of screens only appear if you ask to "see screens for declaring processing steps" on earlier screens of XSETUP REPORTS. Skip these screens unless you are ready to install steps.
_____________________________________________________________________________
United States XSetup Report 04/06/90 14:03
STATES: Select/Clear Steps, Report BUDGETS
-----------------------------------------------------------------------------
Please identify processing steps that Prism should execute. For TYPE, enter
"S" for a screen step, "P" for a protocol step. TITLE is required for
screen steps since that title is used to label the screen.
Processing steps for when report is selected:
STEP# STEP ID TYPE TITLE/COMMENT Note: To remove
1 ................ . ................................ a processing
2 ................ . ................................ step, delete
3 ................ . ................................ the value
under STEP ID
Processing step for when report is cleared:
STEP# STEP ID TYPE TITLE/COMMENT
CLEAR ................ P ................................
______________________________________________________________________________
If you have coded screen steps or protocol steps to be invoked when your report is selected or when a user leaves the report, declare them to Prism here.
Here is the screen for declaring processing steps for printing:
_____________________________________________________________________________
United States XSetup Report 04/06/90 14:03
STATES: Print Steps for report BUDGETS
-----------------------------------------------------------------------------
Please identify processing steps that Prism should execute. For TYPE, enter
"S" for a screen step, "P" for a protocol step.
Processing steps to prepare the report for printing: Note: To
remove a
STEP# STEP_ID TYPE TITLE/COMMENT processing
1 ________________ _ ______________________________ step,
2 ________________ _ ______________________________ delete the
3 ________________ _ ______________________________ value under
STEP ID.
Processing step to generate or dispatch output (occurs after Prism generation
and before Prism dispatching, if applicable):
OUTPUT ________________ P ________________________________
Processing step at completion of report print:
CLEAR ________________ P ________________________________
_____________________________________________________________________________
Processing steps for DISPLAY REPORT:
_____________________________________________________________________________
United States XSetup Report 04/06/90 14:03
STATES: Print Steps for report BUDGETS
-----------------------------------------------------------------------------
Please identify processing steps that Prism should execute. For TYPE, enter
"S" for a screen step, "P" for a protocol step. Title is required for SCREEN
steps since that title is used to label the screen.
Processing steps at beginning of report display:
STEP# STEP_ID TYPE TITLE/COMMENT Note: To
1 ________________ _ _____________________________ remove a
2 ________________ _ _____________________________ processing
3 ________________ _ _____________________________ step,
delete the
Processing step at completion of report display: value under
STEP ID.
STEP# STEP_ID TYPE TITLE/COMMENT
CLEAR ________________ P ________________________________
_____________________________________________________________________________
On the next two screens (condensed onto one page below), you declare whether your processing steps should only be invoked under special conditions, and if so, what those conditions are.
_____________________________________________________________________________
United States XSetup Report 04/06/90 14:03
STATES: Select/Clear Steps, Report: SUMMARY
-----------------------------------------------------------------------------
SPECIAL CONDITIONS: Enter "Yes" to declare or change conditional statements.
Processing steps for when report is selected:
STEP# STEP ID TYPE CONDITIONS
1 <step1>......... S No. <----Change "No" to "Yes"
2 <step2>......... P No. for any step that you
3 <step3>......... P No. want conditionally
performed.
/
Processing step for when report is cleared: /
/
STEP# STEP ID TYPE CONDITIONS /
CLEAR <laststep>...... P No. <----/
______________________________________________________________________________
______________________________________________________________________________
United States XSetup Report 04/06/90 14:03
STATES: Select/Clear Steps, Report: SUMMARY
------------------------------------------------------------------------------
DO ONLY IF: This condition must be true for the step to be done a first time.
1 <step1> DO ONLY IF: .......................................
2 <step2> DO ONLY IF: .......................................
CLEAR <laststep> DO ONLY IF: .......................................
______________________________________________________________________________
The blank beginning "DO ONLY IF:" appears by steps for which you requested "special conditions" on the previous page. Specify here the condition that must be true for the step to be performed. In terms of syntax, anything allowed between IF and THEN in SPIRES is allowed in a special condition in Prism.
The number of help records you need for reporting may vary, but the minimum recommended help records are:
?INTRO/REPORT/<report-name> Introductory text for
when report is selected
<report-name> REPORT Text explaining the report
when users type
HELP <report-name>
?REPORT/<report-name> Context help for report
?INPUT/REPORT/<report-name>/<step-id> Context help for parm screen
associated with a report
Each report that you install needs an introductory "welcome screen" help record whose key has the form '?INTRO/REPORT/<report-name>'. E.g., a report called BUDGETS would need a help record with key as follows:
* ?INTRO/REPORT/BUDGETS <---Intro screen that end-users
see automatically.
To fit within the Guided Mode display, the ?INTRO record must be 15 lines or less (not counting lines with control words like $ALIAS), unless you want it to overflow onto a second screen. The ?INTRO record would answer questions such as these:
- Will end-users need to search your file before producing the report, or will the report use a pre-defined search result? (If the population is pre-defined, be sure to tell your end-users here what the population consists of.)
- What will the final report look like? (E.g., if the final report is a one-line summary of a thousand records, be sure to warn them of this!)
- Will end-users be able to display the report online? Or will they need to wait, say, for an offline printout or overnight processing?
- Is there any time delay involved in accessing the report? You may need to alert your end-users if the report involves a batch process such as SPISORT.
In some cases you may need to ask for input from your end-users when they select your report. To accomplish this you can code a parm screen (via a screen processing step) to appear right after end-users choose the report. This screen can either take the place of the ?INTRO screen or appear in addition to the ?INTRO screen.
If your screen step uses PERFORM PRISM SCREEN... NOPROMPT, then that screen is left visible as the welcome screen when the report is selected, and Prism doesn't use a ?INTRO help record.
Otherwise, if you do a standard screen step, then after the screen step is completed, Prism will go on to display your ?INTRO help record if it exists.
The ?INTRO record covers the situation where end-users have just selected your report. But end-users may also ask for help, specifically naming your report (whether or not they have selected it, or even want to). For instance, if you had a report named Budgets, interested end-users might type HELP BUDGETS REPORT. There are two possible steps you can take to meet this case:
- Add a $ALIAS control word to your ?INTRO record:
* ?INTRO/REPORT/BUDGETS $ALIAS BUDGETS REPORT
- Or write a new help record with a key of <report-name> REPORT:
* BUDGETS REPORT
If your introductory screen implies that an end-user has already selected the report (e.g. "You have now selected the Budgets Report..."), you would have to use the second method listed above to avoid ambiguity.
On the HELP TOPICS menu, if the user is displaying a report, one entry on the menu is "Help for the report you were just viewing". If the user chooses that item from HELP TOPICS, the <report-name> REPORT record is shown.
It's recommended that you include a $CATEGORY REPORTING control word in the <report-name> REPORT help record, so that it is listed on the HELP TOPICS menu, in the section "Reporting in this file".
There is another situation where Prism looks for a help record describing a particular report. If a user is displaying a report and simply types HELP (or "?") Prism looks first for a context help for the report. This help has a key in the form ?REPORT/<report-name>. You may either create a separate help record with this key, or you may add this term as an alias in the <report-name> REPORT help record.
If you code parm screens (e.g. when your report is selected, or elsewhere during report processing) you should provide a help record to be shown if the user types HELP whil looking at the parm screen. This help has a key in the form ?INPUT/REPORT/<report-name>/<step-id>. [See 9.1.1.]
Prism's SETUP TASK command allows users to package together a search, a report or display format, a sort request, and printing options into a "task" that can be scheduled to run automatically. Tasks are run in a "batch" version of Prism as part of the overnight SUBMIT job stream.
If your application has parm screens -- either at file-select, or as part of a report -- you must add a statement to your protocol code in order to enable the SETUP TASK command and/or allow end-users to use particular reports in tasks.
Your parm screens may be gathering information crucial to the session. For example, you may limit the scope of searches or modify the appearance of a report (e.g. with filters) based on information from a parm screen. Prism needs to capture this information as part of the task definition so that the automatically-scheduled task that is run offline can reproduce an online session correctly.
If you do have parm screens, you must add one of the following DECLARE sections to your FILE or REPORT/report-name protocol:
DECLARE PARMS variable, variable, ... ENDDECLARE or, if there are no variables to declare: DECLARE NOPARMS ENDDECLARE
DECLARE PARMS is simply followed by a list of variable or array names whose values should be saved by Prism and restored when a task executes offline. When DECLARE PARMS is coded, Prism saves the current variable values as they are set during a user's session, so that they can be saved in a task definition record if the user happens to define a task under his current session environment.
Use DECLARE NOPARMS if you have parm screens, but there are no variables being set that are critical to printing reports or displays.
ENDDECLARE signals the end of the DECLARE section in the protocol.
If you have a file-selection parm screen, add the DECLARE PARMS/NOPARMS statement to your FILE protocol. In fact, Prism will disallow the SETUP TASK command completely in your application until the DECLARE statement is added.
If a report has a parm screen, add the DECLARE PARMS/NOPARMS statement to your REPORT/report-name protocol. You must add a DECLARE in each report protocol that has a parm screen. An end-user will not be allowed to choose a report for his task until you add the DECLARE statement, if the report has a parm screen.
Within a given protocol, you may code multiple DECLARE PARM statements if needed (or use the backslash character for line continuation in a single statement). For example, both of these are valid:
DECLARE PARMS variable1, variable2, variable3, variable4 \ variable5, variable6 ENDDECLARE or DECLARE PARMS variable1 DECLARE PARMS variable2 DECLARE PARMS variable3 [etc.] ENDDECLARE
Note that if you use PERFORM PRISM PROMPT NAME, PIN to generate Prism's standard identification screen, this counts as a parm screen. Add a DECLARE NOPARMS statement to your protocol. Although this screen is setting important variables such as $UNIVID and $UNIVNAME, you do not have to declare these parms. Prism automatically saves off these variables for use in tasks.
If you have a custom identification parm screen that uses PERFORM PRISM LOOKUP NAME instead of PERFORM PRISM PROMPT NAME, declare any variables of your own that are being used, but you don't need to declare Prism's system variables $UNIVID, $UNIVNAME, $UNIVEMAIL, $UNIVPHONE, or the corresponding $PROXY... variables.
Technical note: For use in tasks, Prism saves the $UNIVID value. The values of the other related variables $UNIVNAME, $UNIVEMAIL, $UNIVPHONE are looked up when the task runs.
Note too that the name resolution process built into PERFORM PRISM LOOKUP NAME cannot happen in tasks. To ensure that your identification routines can work successfully in tasks, use the UNIVID and PROXYID options on this command. [See 25.3.2 for a more detailed explanation.]
Important note: If you add parm screens to an application for which tasks have already been defined, you need to contact DTR staff in order to upgrade the existing task definitions to take the new parms into account. You can check the PRISM DEFINITIONS subfile (in SPIRES) to see if tasks exist for your application. [See 7.10.]
If you have a parm screen that is presented via a screen step (i.e. you don't already have a FILE or REPORT protocol) you will still need to create a "placeholder" protocol step to hold this DECLARE PARMS or DECLARE NOPARMS statement.
Reports with parm screens after PRINT can't be enabled reliably for SETUP TASK. Even if you declared variables from this parm screen, they wouldn't be set properly for the user's task if he issued the SETUP TASK command before printing the report (or without actually printing it at all in the online session). Consider changing the position of your parm screen so that the report can be used in tasks.
When a task runs offline, Prism initializes the declared variables at the start of the protocol, which might be a different place than when the report is run in an online session. Keep this in mind if your protocol reinitializes variables or sets defaults near the beginning.
All of your protocol steps will be done when a task runs offline, but screen prompts do not happen in the batch. Beware of logic in your protocols code that depends on input from screens to avoid a loop or a failure.
If variable B is derived from variable A, you can just declare A and let the calculation for B happen when the task runs. This way, B will be up-to-date at the time the task runs. If you declared B as well as A, both would have the values set at the time the task was defined.
Your formats screen processing code won't happen when a task runs in the batch. So a variable that is set in your formats code won't be set during task execution. You might consider moving code from formats to protocols so that a variable can be declared and set correctly if it is important for the report to work correctly in a task.
In some cases, you might need to modify your parm screens to allow users to enter "symbolic" parameters. For example, if your parm screen currently asks which month should be reported on, you might want to allow room for users to enter values such as "current month" so that if the report were to be scheduled via SETUP TASK, the symbolic value "this month" could be used rather than a specific month and year.
Data entry covers the rightmost branch of the overall Prism diagram shown in the first chapter:
WELCOME TO PRISM
|
|
Select a file or
service
|
(User selects |
your file)---> |
Welcome to
the file
/ | \
(Search) (Report) ENTRY
/ | \
(Search performed Pick an
either before entry form
or after form |
is selected) |
|
CREATE
or GET
Your SPIRES input format is set when end-users select the entry form. The format is cleared when end-users pick a different form, a different activity (such as Report), a different file, or when they leave Prism.
Data entry begins when the end-user issues either the CREATE command (to add a new record to your data base) or the GET command (to modify a current record). After CREATE or GET, your SPIRES format works in cooperation with Prism, to "write" screens (each screen 17 lines maximum) to the terminal and to "read" and act upon the data that end-users input into each screen.
(Entry (Entry ends
begins \ \ \ when user
with GET ------ SCREEN#1 ------- SCREEN#n ----------- types SEND
or CREATE / / / or CANCEL)
command) | |
| |
Bottom of screen Bottom of screen
offers commands offers commands such
such as OK as PREVIOUS to page
to page forward backward or SEND to
enter the record
An entry form uses a SPIRES full-screen input format to present screens for data entry. In many cases you can use Screen Definer (a Prism application) to create the input format, or at least to create a base format that you can further modify.
After creating the input format for your entry screens, you use XSETUP FORMS (or the MOD FORMS form in Prism Profile) to install the entry form.
As part of installing your form in Prism, you tell Prism what order screens should be presented in and which commands should be enabled on each screen (PREVIOUS, OK, SEND).
When a Prism user types the command ENTRY, he is presented with a list of entry forms for the file. In general, an entry form should correspond to a particular data entry task appropriate for the file. For instance, an address file might have one form for adding new addresses to the file, and another for updating existing directory entries.
Entry forms can be defined for adding records, updating records, or removing records, but in general each form should cover only one of these tasks. Some "process-intensive" applications -- applications calling for bulk data entry by trained in-house professionals -- can benefit from a single form for multiple tasks, such as a single form both to add new records and modify old ones.
One of the questions you'll answer when installing an entry form is what "transaction type" the form supports. [See 11.5.] The transaction type you choose affects whether GET and CREATE are enabled and other behavior related to the entry form. The most common transaction types are:
ADD Entry form is used to add new records but not to update
existing records.
CREATE is enabled when form is selected; GET is not.
UPDATE Entry form is used to update records but not add new ones.
GET is enabled; CREATE is not.
ADDUPD Entry form is used for both adds and updates.
Both CREATE and GET are enabled.
REMOVE Entry form is used to remove records only.
GET is enabled; CREATE is not.
PROCESS Choosing the entry form starts a transaction automatically,
so neither CREATE nor GET are applicable. SEND or CANCEL
ends the transaction and also leaves the entry form.
Another option you may choose for your entry form is to streamline the entry process by causing the GET or CREATE commands to be issued automatically in some situations. Specifically, you may cause CREATE to happen automatically when a search gets a result of zero. And you may cause an automatic GET command when a search has a result of one. Here are the relevant questions you'll see when installing the entry form:
Enter 'Yes' for an automatic GET when result=1: No_ Enter 'Yes' for an automatic CREATE when result=0: No_
These options should be chosen cautiously, only if you are sure that this behavior best suits the nature of the entry tasks in your application.
Another convenience you can provide for users of your entry form is to request that after a SEND, Prism should automatically re-display the record that was just created or modified, for review purposes. This is the relevant question in the XSETUP FORMS installation process:
Enter 'Yes' for an automatic REVIEW after send: No_
[See 11.3.1 for details.]
As with other components of your application, you should write help records to describe your entry form. This includes context helps for each screen of your entry form and a special help record containing explanations of all the error codes used in your entry form. [See 9.1.1.]
If you wish, you may use the MOD OPTIONS entry form in Prism Profile in order to customize the wording of the Guided Mode options at the bottom of the screen during entry activity in your application. [See 14.]
There are two different methods for controlling the execution of an entry form in Prism -- the "automatic" method and the "custom" method. The current chapter will cover automatic control. [See 12 for the more complex "custom" method.] Here are some of the differences between these two methods:
AUTOMATIC CONTROL OF ENTRY CUSTOM CONTROL OF ENTRY (discussed in this chapter) _______________________________________________________________ - requires installation of - requires installation one screen step for each of one protocol step for screen (so a minimum of one the entire data entry screen step must be declared) process - does not require protocol - requires protocol coding (protocol steps are coding, so is more optional), so is easier difficult - assumes add or update of a - may involve add or single record per entry-cycle update of multiple (e.g., from GET through SEND) records per cycle - assumes access of a single - may access more than SPIRES subfile one SPIRES subfile - has Prism automatically - must "open" and "close" "open" and "close" the record records as part of its to be processed protocol Proc
For simple entry forms, you can usually use the automatic method of execution control described in this chapter unless one or more of the following conditions is true:
- Your form will add or update more than one record per entry cycle (between GET/CREATE and SEND).
- Your form must control the timing of when to OPEN a record (bring it into memory) or when to CLOSE it (put it into the data base).
- Your form will need to access more than one file for more than, say, a simple lookup.
- Your form needs a single active file to span more than one screen or processing step. [See 9.2.4.]
- Your form will initiate a process rather than updating a record per se.
- You want to generate boxes on entry screens. [See 12A.]
Another possible way to decide which method you need: your entry form may be a good candidate for custom installation if your code needs to make a number of subtle procedural decisions. For instance, if the order of your form's input screens will be highly variable, it might be better to specify their order dynamically through decisions made in your protocol coding, rather than to specify a single screen order through automatic installation.
[See 12 if still in doubt, to see whether it offers features you will need.] The chances are that most simple entry forms can take advantage of the greater convenience of automatic installation, but for more complex types of data entry the custom method can be indispensable.
The easiest way to create an entry form for Prism is to use the Prism application Screen Definer and paint the screens of your entry form online. Screen Definer takes care of translating your painted specifications into a SPIRES format; for simple entry forms, you don't have to work with formats code yourself -- in fact, you can create a Screen Definer form, install it in Prism, and use it for data entry without ever looking at the SPIRES format that supports the form.
For complete information on how to use Screen Definer, you will need a copy of the "Screen Definer" manual, available online via the PUBLISH command. There's also substantial online help when you select Screen Definer in Prism.
When you install your Screen Definer entry form into Prism Profile, the XSETUP FORMS screen will ask you for the "format name" of the SPIRES format supporting your form. Unless you have altered or customized your Screen Definer output, you can nearly always enter into this field your Screen Definer record key minus its account prefix:
If in Screen Definer your record key is this...
Screen Definer record key: GQ.JNK.BLDDONOR________
In XSETUP FORMS you should enter this value:
Enter format name to be used for this form: BLDDONOR______
Instead of accepting your Screen Definer form as is, you can modify the formats code that it creates, selecting the FORMATS subfile in SPIRES, and transferring out your generated record. This process makes sense if you need to add features to your form that exceed the current Screen Definer design, such as special editing with UPROC statements.
The next section discusses guidelines on modifying (or, in some cases, creating from scratch) the SPIRES formats code that underlies a Prism entry form. If Screen Definer meets all your needs for entry form creation, you can probably skip the next section.
No matter how familiar you are with SPIRES programming, you'll still probably want to create the first draft of your Prism entry form with Screen Definer, and save hours of labor. But you may in some cases want to take your Screen Definer output -- a SPIRES format and variable group or vgroup -- and customize it further, using conventional SPIRES coding techniques. (Note that if you alter a Screen Definer record outside Screen Definer, the alterations will not be reflected within Screen Definer.)
The rest of this section will discuss techniques and standards for modifying the SPIRES format that underlies a Prism entry form. You can skip this section if you have used Screen Definer for your form, and don't wish to modify the form any further.
Each of your entry forms in Prism requires a SPIRES format specifying at least one pair An exception to the need for a "pair" of frames: a "display-only" screen (one allowing no input) would only need one output frame for display. of frames for the particular function (for instance ADD or UPD) that the form carries out. (Multi-task forms, say for ADDUPD, might share common screens, with differences in function resolved within the code for the screens' frames.) Your SPIRES format can have any name you choose, as long as you enter this name in XSETUP FORMS.
Forms that allow adding new records must have an output frame (or one frame per screen for multi-screen forms) that will display an empty record into the input portion of the screen, plus an input frame (or one frame per screen for multi-screen forms) that will read the data from the input area and put it into the record being built.
Forms that allow updating of existing records must have an output frame (or one frame per screen for multi-screen forms) that will display a single record into the input portion of the screen, plus an input frame (or one frame per screen for multi-screen forms) that will read the data from the input area and put it into the record being modified.
Forms that allow removing of existing records would typically have a single output frame displaying the record to be removed and asking for confirmation of removal, along with a second frame (probably an XEQ-type frame) to read in the confirmation request. "Remove" forms are discussed in more detail later in the chapter.
For ADDs, UPDATEs and REMOVEs the Output Frame for each screen must be as follows:
DIRECTION = OUTPUT; (or) DIRECTION = OUTPUT;
USAGE = DISPLAY, NAMED; USAGE = NAMED;
: :
FRAME-TYPE = DATA; FRAME-TYPE = XEQ;
For ADDs, UPDATEs and REMOVEs the Input Frame for each screen must be as follows:
DIRECTION = INOUT; (or) DIRECTION = INOUT;
USAGE = MERGE, NAMED; USAGE = NAMED;
: :
FRAME-TYPE = DATA; FRAME-TYPE = XEQ;
The input frame for a REMOVE form would almost always be type XEQ, since there's little point in reading data into a record that is about to be removed.
As in any SPIRES format, the FRAME-TYPE must equal DATA whenever the frame will be getting data out of a record or putting (new or changed) data into a record. In other words, the FRAME-TYPE can be XEQ only when the frame is manipulating something other than record data, such as variables or user parameters.
A form can have "XEQ" input screens and "DATA" input screens in any combination and any order. The type XEQ frames will create screen processing steps like the ones for general file-related tasks or reporting. The frames of type DATA will have the added ability to access and change the data base.
Every processing step you code for Prism, including your screen processing steps for data entry, must have a unique identifier or "step id". Step id's will not be seen by end-users of your file, so you can name them what you want, but names should be as immediately descriptive as possible: e.g., INPUT1, INPUT2, and INPUT3 for three sequential input screens. Each step id for a screen step must be unique in its format. SPIRES note: In some cases you might code two forms that shared a particular screen: e.g., two forms named ADD RECORD and MOD RECORD might share a screen displaying the same record. You can code these two forms together in a single SPIRES format -- the two forms would share code only for the screen(s) they shared, and otherwise would not overlap within the format.
In addition to its step id, every screen processing step needs a title to appear at the top of the screen. Prism Profile will require you to declare the title for a screen step when you install it.
Frame-names for your entry form's frames must closely match the step id that you use when you declare the screen in XSETUP FORMS. The frame name takes the form <step-id>.IN for the input frame and <step-id>,OUT for the output frame. For instance, frames for a screen step with step id INPUT1 must be named INPUT1.IN and INPUT1.OUT. (This same naming convention applies for screen steps everywhere in Prism, not just in data entry. Sometimes, as in Screen Definer, screens are identified by "Screen ID", which is essentially the same as "step id".) [See 9.1.]
Just as a reminder, here is the chart on screen processing step naming conventions that also appeared earlier: [See 9.]
Screen step (12 char. max.) Frame-names (16 char. max.)
as installed in Prism in your SPIRES format
--------------------------- ------------------------------
<STEP-ID> or <SCREEN-ID> <STEP-ID>.OUT or <SCREEN-ID>.OUT
<STEP-ID>.IN or <SCREEN-ID>.IN
As mentioned earlier, entry forms installed by the "automatic" method only add or update one record per entry cycle (e.g., one record per GET-through-SEND transaction), and this record is always from the SPIRES subfile named on the first page of ADD PROFILE. [See 12 if you need multi-record or multi-file entry transactions.]
If you use the "automatic" method, Prism automatically opens the transaction process for you (i.e., brings the record into memory and prepares it for input) and closes the transaction process for you (where "closing" means to write the record back to the data base with any changes the end-user has made).
Here is what happens in an entry transaction from the SPIRES viewpoint:
An important point to note is that, for "automatic" entry forms, Prism automatically performs the appropriate Partial FOR actions for you before your entry form steps begin to take effect. Also, Prism automatically performs appropriate closeout processing (for ADD or UPDATE) after your entry form processing steps have finished taking effect. An automatic form can thus concentrate on gathering and validating data without worrying about such things as referencing the record.
Prism standards for screen layouts and for placement and characteristics of error codes are already implicit in current applications such as Prism Profile. Here is a brief guide to standards for the display attributes on an entry form. Note that if you use Screen Definer and stick with its default values, you will automatically get these attributes coded for your screens:
BRIGHT COLOR BLINKING UNDERLINING
Unprotected yes yellow no yes*
required fields
Unprotected no green no yes*
optional fields
Protected fields yes white no no
Error fields yes red yes no
Title fields no cyan no no
Text no white no no
For detailed information on how to customize the display of fields in entry forms, see the chapter on display attributes in the manual "SPIRES Device Services".
Prism end-users will more and more expect to be able to move backward and forward within a multi-page entry form, using the PREVIOUS and OK options. You may need to take care that all the separate screens of your form stay consistent, no matter whether an end-user reaches the screen by PREVIOUS or by OK.
As one example, if information on "Page 1" is closely related to information on "Page 2", you wouldn't want end-users to fill in both pages, then go back to "Page 1" with PREVIOUS, change important information on "Page 1", and SEND the record without also changing "Page 2" to make it consistent. (You could solve this problem by not allowing SEND on "Page 1", or by making some fields on "Page 1" unprotected the first time an end-user sees them, but protected after the PREVIOUS command. The variable $LASTCMD, described in the appendix on variables, can tell you whether the end-user issued the PREVIOUS command to reach a screen.)
End-users who want to look at the record they most recently created or modified in Prism can issue the REVIEW command anytime after a successful SEND. Alternatively they could issue the DISPLAY CURRENT or DISPLAY * command. (Neither REVIEW nor DISPLAY CURRENT can be used to see removed records, however.)
If you'd like REVIEW to be automatic for your end-users, so that after SEND the user automatically sees the record that was just input, you can ask for this in XSETUP FORMS. [See 11.5.]
Enter 'Yes' for an automatic REVIEW after send: No_
Ordinarily the REVIEW command uses your FULL display to show an added record. However, if you prefer, you can use instead any of the additional displays installed for your application. [See 3.4 for additional displays.]
A third option is to code a special frame for REVIEWing the record and add it to your input format (or Screen Definer-generated format).
Whatever your choice, you tell Prism the name of the display or frame to be used for the REVIEW command: [See 11.5.]
For REVIEW, use this display defined for the file: FULL......
or, use this FRAME defined for the form: ..........
Be sure to note that this special REVIEW frame goes into your input format, not into your display format.
If you code a special frame for REVIEW, it will generally have a frame-type of DATA -- Prism will automatically refetch the just-updated record for it to display. If you would rather not access the record again (perhaps for efficiency reasons), you could code it as an XEQ frame instead. [See 12.2 for other situations where you may want to code an XEQ frame.]
An important caution: if the special REVIEW display that you code will use more than one screen, be sure to use the overflow and "putdata" techniques similar to the ones described for reporting. [See 10.1.]
For instance, for a REVIEW frame called REVUE:
FRAME-ID = REVUE;
:
:
FRAME-ID = OVERFLOW;
DIRECTION = OUTPUT;
USAGE = DISPLAY;
LOAD-FORMAT = $PRISM.OVERFLOW;
:
FRAME-NAME = REVUE;
FRAME-TYPE = DATA;
UPROC = SET PUTDATA 4;
FRAME-NAME = OVERFLOW;
FRAME-TYPE = OVERFLOW;
The REVIEW command doesn't provide an automatic way to redisplay all the records an end-user has newly input -- just the most recently input record. If your end-users want to redisplay a whole series of newly input records during a current session, the record-key would have to be immediately indexed in the SPIRES file definition.
To signal to Prism that reprompting is necessary, use the $STATUS Variable, giving it the value REPROMPT:
UPROC = SET STATUS = 'REPROMPT';
In response to a $STATUS value of REPROMPT, Prism rewrites your screen to the end-user, displays the appropriate error codes, and reinvokes your input frame. (What's more, if you are doing changed field processing, Prism will remember and preserve this changed field information across multiple transmissions.) Note that, since setting $STATUS in this way is all Prism needs to handle inputting errors correctly, your format will never issue its own UPROC=REPROMPT.
It is important that whenever a screen reading fails from an end-user's error, you set the $STATUS Variable before returning, thus signalling to Prism that input has failed and reprompting is needed. When you do set STATUS, always set it as the very last thing you do before returning. If you set the value of STATUS too early, and your format later happens to fail for a different reason, the value in $STATUS will send misleading signals to Prism and to your end-users.
To cause screen reprompting of warning-only conditions you also use $STATUS (i.e., SET STATUS 'WARN'). By the way, Prism makes no internal distinction in the way it reprompts for STATUS 'WARN' and STATUS 'REPROMPT'. The main distinction is that the value for the $SCRNSTAT variable changes to match the value ('WARN' or 'REPROMPT') that you set for $STATUS. Your code can read the value of $SCRNSTAT to determine whether a screen has been reprompted as a warning only, or because of serious input errors.
[See A.15 for information about other $STATUS values that you can use to control the cycle of screen presentation.]
Note that $STATUS is set by you to signal Prism that processing did not end as expected. The various $STATUS values invoke specific processing options in Prism (such as reprompting a screen). On the other hand $SCRNSTAT is maintained by Prism to let the application know how the end-user arrived at a particular processing step, via normal processing or as a part of special processing of $STATUS values.
Currently, Prism does not support a method for detecting record closeout errors. You must detect errors while you are processing an individual screen.
Whenever an end-user is allowed access to input fields on a screen, Prism will always process that screen through the input frame defined for the screen, regardless of whether the command that the end-user issues to leave the screen is OK, SEND, or PREVIOUS. Therefore, if your application offers end-users the ability to move to an optional screen via the OK command, you should also be prepared for the situation in which, after reaching the optional screen, end-users decide that they are in fact finished and wish to SEND the transaction without inputting any more data.
The input frame associated with this "optional" screen must accept "null input" from an end-user without forcing a reprompt. (Technically, null input occurs when a merge request is processed and no change is made to the record.) In other words, your format will need to be prepared to accept this input (or lack of input) as valid.
If a screen in your entry form is optional in the sense that end-users might leave the screen completely blank without jeopardizing the rest of their data entry, make certain that individual fields on the screen are either optional or only conditionally required (depending on whether data on the screen has been changed). Be careful, for instance, not to code default PUTELEMs on such a screen (or PUTELEMS on hidden elements), since Prism would consider this to be "non-null" input even when the end-user had not actually input anything on the screen.
When you reprompt an entry screen because of error conditions, you should display 2-character error codes beside the fields in error (typically, to the left of the entry field). When the screen is reprompted, Prism displays this message in the message line: "-Errors found; type HELP <error code> below for more information". When a user types HELP followed by the error code, Prism looks for the error explanation in your ?ERROR help record -- you must include in that help record all error codes used in your application, along with a one-line explanation of each. [See 9.1.1.]
There are two ways to define the error codes that should display when an entry screen is reprompted in an error condition:
Here is an example of file definition code using the $MSG Inproc:
STRUCTURE = VISIT;
FIXED;
ELEM = DATE;
OCCURS = 1;
LENGTH = 4;
INPROC = $MSG('D1')/ $DATE;
OUTPROC = $DATE.OUT;
In general, it's most straightforward to define your error codes with $MSG in your file definition, as shown here. However, some types of errors cannot be handled this way, such as errors resulting from INCLOSE processing (e.g. requiredness, inter-element edits, edits to check how many occurrences are present). In that case, you will have to use the SET UCODE technique (see below).
The $MSG text is also used in SPIRES, e.g. during $PROMPT input. If you need to provide error messages both for Prism and for SPIRES input for your subfile, you might code $MSG text like this:
INPROC = $MSG('D1 - Invalid Date')/ $DATE;
In this case, the longer, more descriptive phrase would be shown during SPIRES input, while the first two characters only of the $MSG text would be used as the Prism error code. (The length of the error message area in a full-screen input format is determined by the SET ELENGTH Uproc. Screen Definer automatically supplies a "UPROC = SET ELENGTH = 2;" statement in your frame definitions.)
If the $MSG technique cannot be used, an alternative way to define your error codes is with the SET UCODE Uproc, which may occur in both file definition userprocs and in input formats.
If you create your input format with Screen Definer, the RQ error code will automatically be coded for all required elements. Here is an example of a label group from the code generated by Screen Definer, showing use of SET UCODE:
LABEL = NAME.1; ESTART = 2,2; LENGTH = 20; START = 2,18; GETDATA = 7; UPROC = IF $ULEN = 0 THEN SET UCODE = 'RQ'; UPROC = THEN SET ERROR = 'S'; PUTELEM = NAME;
For details about this technique, EXPLAIN SET UCODE.
Here is an example of error explanations in your ?ERROR help record. [See 9.1.1 for further details.]
* ?ERROR -D1: Invalid form of date. Use mm/dd/yy (mm=month; dd=day; yy=year). -RQ: Required field.
Sometimes an entry form includes fields of text too long to fit onto a single line:
Description: ________________________________________ _____________________________________________________ _____________________________________________________
When one types to the end of the line, the expected behavior is probably that the cursor should move to the next line, and words that don't fit on one line should "wrap" to the next. However, unless you explicitly enable word wrapping, when one types to the end of a line, the cursor remains at the end of the line.
To enable word-wrapping in an entry field, code the WRAP display attribute in the label group for that field in your format. For example:
LABEL; VALUE = ' '; MARGINS = 5; MAXROWS = 3; DISPLAY = OPTIONAL, WRAP; PUTDATA;
Note that Screen Definer does not automatically include DISPLAY = WRAP in the input format that it creates. Modify the generated format if you want to add this feature. The DISPLAY = WRAP attribute goes in the .OUT frame.
Note: word wrapping is not available for 3270-type terminals.
The WRAP attribute also enables some other editing features: ESC-S to split a line, ESC-J to join a line, DEL-L to delete a line, and ESC-A to align a block (the same editing key sequences used in Page WYLBUR). [See 12A.4 for another use of DISPLAY = WRAP, for trigger fields.]
For a field to wrap, all rows within the field must end in the same column, and all rows except the first row must begin in the same column. Thus your field could be a rectangular block or a "paragraph" block with the first line indented:
(These shapes are allowed:)
............. ............. .........
......... ............. ..............
......... ............. ..............
If you have successive entry fields for which you want word wrap, either put a blank line between the fields, or use a different starting margin for each field. For example, these layouts are good:
Description: ......... Description: .........
...................... ......................
...................... ......................
Comments: ............
...................... Comments: ............
...................... ......................
......................
Description: .............
......................
......................
Comments: ................
......................
......................
But this layout will cause an undesirable behavior:
Description: .................... <--- odd word wrapping
.................... will happen in this
Comments: .................... layout
....................
In this case, Prism/SPIRES treats the entire block as one word wrap area, since the margins are the same all around. When you type to the end of the "Description" field, you'll wrap to the start of the "Comments" field, even though these are defined as two separate entry fields in your input format.
The following guidelines are recommended for record-removal entry forms:
- Typically a simple 1-screen entry form is sufficient.
- The screen should display enough data from the record that the user can be sure that the correct record is being removed. You might duplicate all or part of your FULL display, for example.
- Supply a prompt at the bottom or top of the screen with text such as "To remove this record, type YES here -->" followed by an input field where YES can be entered. This should be the only input field on the screen.
- You should edit to ensure that "yes" is entered in the input field. (See the sample format label groups below that accomplish that.) This provides extra assurance that the user really intends to remove the record -- both SEND and the specific value "yes" are required to complete the transaction. (The user would CANCEL to back out of the remove transaction.)
In pictorial form, here is a recommended pattern to follow for an entry screen for removing records:
_____________________________________________________________________________
Directory Entry Form: REMOVE 04/07/92 10:16
Removing a directory entry
-----------------------------------------------------------------------------
To remove this record, type YES here --> ___
_____________________________________________________________________________
Name: John Doe
Address: 5 Main St.
<Display enough of the record to verify that
this is the one that should be removed.>
_____________________________________________________________________________
If your record-removal entry form is installed under "automatic control" (i.e. you just tell Prism the names of screens to be presented) then Prism takes care of removing the record from your database, after a successful SEND. The thing that makes this happen is specifying in XSETUP FORMS that this entry form is for transaction type of REMOVE. [See 11.5.]
If your entry form is installed under "custom control" (where you code a protocol that issues PERFORM PRISM SCREEN commands) then your protocol must include a PERFORM PRISM REMOVE CURRENT command to accomplish the record removal. [See 12.1.5.]
From the user's perspective, after a successful SEND the removed record disappears from Prism. (If necessary the transaction could be UNQUEUEd in SPIRES.) Prism adjusts the user's search result count and renumbers the records in the search result to take account of the removed record.
You can create the first draft of your remove screen with Screen Definer, thus helping ensure that display attributes and terminal characteristics will be assigned correctly. But to create the input field for the "yes" value, you'll need to add a few label groups to the input and output frames that Screen Definer generates.
These label groups create the input field and label shown at the top of the screen sample above:
LABEL = PROMPT.FOR.YES; VALUE = 'To remove this record, type YES here -->'; START = 1,4; DISPLAY = TEXT; PUTDATA; LABEL = FIELD.FOR.YES; VALUE = ''; <--- (Creates input field in LENGTH = 3; which user types YES) START = 1,45; DISPLAY = REQUIRED; PUTDATA;
These label groups in the input frame check to make sure something is typed in the blank (if not, the screen is reprompted with an 'RQ' error). They also edit the value to make sure it's some form of 'Yes'; if not, the screen is reprompted with a YC error code.
LABEL = READ.INPUT; ESTART = 1,1; LENGTH = 3; START = 1,45; GETDATA; INPROC = $CAP; UPROC = If $PMATCH($CVAL,Y?ES) Then Jump EXIT; UPROC = If $ULEN = 0 Then Set Ucode = 'RQ'; UPROC = Else Set Ucode = 'YC'; UPROC = Set Error S; LABEL = EXIT; UPROC = IF $GPROCERR Then Set Status = 'Reprompt';
If you follow the pattern shown above, remember to add a YC explanation in your ?ERROR help record. [See 9.1.1.] Here is a recommended error message:
-YC Answer YES and issue the SEND command, or issue the CANCEL command.
You could also use the message-line (i.e., use SET MSGLINE within a Uproc) to tell how to cancel the removal.
If efficiency is a major concern in your application, you may wish to change the .IN frame for your record-removal form to FRAME-TYPE = XEQ, since the frame will not be putting data into the database. The savings in doing this are likely negligible, however, so for simplicity's sake you can just use FRAME-TYPE = DATA, as in the .OUT frame. (If your .OUT frame is displaying a record from the database, it must use FRAME-TYPE = DATA.)
When installing the entry form (with XSETUP FORMS), mark it with a "transaction type" of REMOVE:
_____________________________________________________________________________
Directory XSetup Form 04/07/92 10:16
-----------------------------------------------------------------------------
NAME of form PURPOSE of this form
____________ ________________________________________________
Enter transaction type for this form*: _______
:
:
_____________________________________________________________________________
The REMOVE transaction type does two things -- it causes Prism to enable the GET command but not CREATE when the entry form is selected; it signals Prism to do the actual record removal when SEND is successful (for AUTOMATIC control forms only). (As explained earlier in this section, for CUSTOM control, your protocol must issue a PERFORM PRISM REMOVE CURRENT command.)
All Prism entry forms have at least one processing step -- even the simplest one-screen entry form would install that screen as a processing step in XSETUP FORMS. Since screen processing steps are basic to Prism entry, you should probably look over the material on screen processing steps before reading this chapter. [See 9.]
In the current chapter, we will assume that your entry form is used for adding or updating a single record per entry-cycle (i.e., the process between GET/CREATE and SEND will add or update only a single record). We will also assume that the form invokes screens from only a single SPIRES file, namely the file you named in ADD PROFILE.
If these two conditions are true for you, you can take advantage of the "automatic installation" of entry forms described earlier in this chapter. (But if these two conditions are not true for you, you will need to use the more complex "custom installation".) [See 12.]
As part of installing your entry form, you give explicit instructions on how the flow of the input transaction process should be controlled. The processing steps that you install for data entry control the timing and nature of everything from CREATE/GET to SEND/CANCEL.
For automatic control of data entry, you install each of the screens coded in your format as a separate screen processing step in XSETUP FORMS. These screen steps will be executed, along with their associated protocol steps, starting from the top down, in the order of their installation in XSETUP FORMS (and not in their order in your format). Since steps are executed from the top down, once end-users have typed SEND, any screen steps that have not yet been executed will simply be passed over, though the two protocol steps, PRE and POST, if coded, would be executed at this point.
For each screen, you determine whether SEND is a valid option when you install the screen in XSETUP FORMS. Once you allow SEND as an end-user option for any screen in your entry form, all the screens installed after it by definition become optional, so you would not allow the SEND option on a screen until all the required data for a record had been prompted for.
If you choose "automatic" processing, these characteristics of your entry form will be determined through the installation of processing steps in XSETUP FORMS:
- The order of each screen (and the order of the protocol steps, if any, between the screens)
Remember that the order in which you install processing steps for data entry determines the order in which the steps are executed when an end-user uses the form.
- The maximum number of times a screen can be displayed
- The command options to appear below the screen
- The condition that must be true before a screen is displayed
- The interaction between screens and protocol steps
This modification of the earlier chart for entry indicates roughly the interaction and timing of your screen steps and your protocol steps. There can be as many as eight screens under automatic control:
(P - mult) --- indicates points where more than one protocol
step might occur
(P - sing) --- indicates where a single protocol step might
occur
\ \ \ \
(GET or -------- SCREEN#1 -------- SCREEN#n -----------(SEND)----------
CREATE) | / | / | / | /
| | | |
| | | |
(P - mult) (P - mult) (P - sing) (P - sing)
Note the many points at which protocol steps can come into play:
- before any screen including the first
- between any two screens
- after any screen
- before or after SEND (but not after CANCEL)
There are two special protocol steps associated with the SEND command and labeled PRE and POST in XSETUP FORMS. These steps, if coded, would be executed even when end-users issue SEND before seeing all of the screens.
The PRE step is executed while the record is still in memory and allows you to perform final processing before the record is put into the data base.
The POST step occurs only after the record has been put into the data base and thus always implies a successful data entry transaction. You could use it for compiling statistics or sending notification to your account.
To declare processing steps for "automatic" data entry, follow this procedure in XSETUP FORMS:
STEP# STEP ID TYPE TITLE/COMMENT
1 <step-id#1>. s First Screen...............
2 <step-id#2>. p (Protocol step)............
3 <step-id#3>. s Second Screen..............
: :
: :
PRE <step-id#m>. p Do after SEND..............
POST <step-id#n>. p Do after record is closed..
(You can have as many as eight steps in automatic processing, plus two additional "SEND" steps, one which would take effect before and one after a record was successfully added or updated.)
Some of these options are protected (e.g., PREV on the first screen), and some of them are mutually exclusive (a "display only" screen cannot have multiple iterations, for instance). Also indicate whether the step should be executed only under "special conditions":
--Patron Options-- DISPLAY DO n SPECIAL
STEP ID TYPE OK SEND PREV ONLY TIMES CONDITIONS
<step-id>... S --- Yes No. No. 1. No.
For protocol steps indicate whether there are "special conditions".
--Patron Options-- DISPLAY DO n SPECIAL
STEP ID TYPE OK SEND PREV ONLY TIMES CONDITIONS
<step-id>... P --- --- --- --- --- No.
Note that for protocol steps the command and display options are protected, but you can ask for conditional execution of the protocol step by changing the value under SPECIAL CONDITIONS to 'Yes'.
1 <step1> FIRST, DO ONLY IF: .......................
AND THEN CONTINUE AS LONG AS .......................
2 <step2> FIRST, DO ONLY IF: .......................
Conditional execution would probably depend on variables previously set in your format. Remember that the syntax of a special condition in Prism allows whatever is allowed in SPIRES between IF and THEN.
Prism does not verify the validity of the steps you name until they are evoked when your application is running. If, during a data entry session, Prism is unable to find one of the screens you have named, it will terminate the entry process with a system error. (The same holds for processing steps everywhere in Prism.)
Note that you can always make the invocation of a "display only" (protected) screen conditional based on end-user preference. For instance, you can code processing steps at form-selection time to ask end-users whether or not they want a redisplay option to be available, then activate your "display-only" screen only if they have said yes.
Note also that if you want to redisplay a screen for confirmation after input into the screen is finished (but before the end-user has typed SEND), you can install its step-id twice, the second time as a "display only" screen. [See 11.3.1 to redisplay a record after it has been added or updated.]
Although enabling the PREVIOUS option for a multi-page form is usually straightforward, sometimes you will need to make sure that information on all of the screens stays consistent, even though the end-user may have gone backwards with PREVIOUS and changed an earlier page. [See 11.3 For more information on PREVIOUS.]
As you've seen, entry forms in Prism require at minimum one processing step to identify data entry screen(s). There are a few other places, within Entry Activity but outside the entry cycle (CREATE/GET through SEND/CANCEL), where you could add steps.
The following highly-simplified chart shows how extra processing rules might be applied during the process of form-selection. The horizontal line shows the flow of a basic Prism session, and the boxes below the line show places where your own processing steps and help records would affect a session:
FORM-SELECTION:
(User \ \ \
selects ---------------------------------------------------------------
form) / / /
| /|\ | /|\
| | | |
\|/ | \|/ |
PROCESSING STEPS INTRO TO FORM
(in place of or in (the ?INTRO help
(A) addition to your (B) record
?INTRO record)
At least one of (A) or (B) is required, so that the form has an introductory screen.
At point (A) of the diagram, you could code a protocol step to perform a "hidden search", if you wanted your entry form always to deal with a particular subset of your file's records. [See 13 for details.]
NOTE: you can also code a protocol processing step (not shown in the diagram) for when end-users leave your form.
To install or modify an entry form for your application, use the XSETUP FORMS command. As with all XSETUP commands for application maintenance, issue the command from within your own application. XSETUP FORMS is one of a family of XSETUP commands with which you may maintain your application. [See 8 for more information about XSETUP.]
As an alternative to XSETUP FORMS, you may use the MOD FORMS entry form in Prism Profile to install or maintain entry form definitions. Both methods present the same screens to fill in; XSETUP FORMS offers the advantage of being able to modify your application without having to move to Prism Profile.
Here is an example of the first screen of XSETUP FORMS, if you already have at least one form installed. (If you don't yet have any forms, you are taken directly to the screen shown on the next page.)
_____________________________________________________________________________
Directory XSetup Form 04/07/90 10:16
Select Function
-----------------------------------------------------------------------------
_ <-- Type the number of the function you want to perform (1-3).
1. DEFINE a new entry form.
2. MODIFY or REMOVE an existing entry form.
3. CHANGE the order of entry forms on the Prism ENTRY menu.
___ <-- For MODIFY or REMOVE, type a number from the list below.
1. ADD To add a complete directory listing
2. UPDATE To update a directory listing
_____________________________________________________________________________
Here you indicate the task you want to do -- defining or modifying an entry form, or changing the order in which forms are listed.
The list in the bottom of the screen includes all entry forms currently defined for your application.
Here is the first screen where you give details about an individual entry form:
_____________________________________________________________________________
Directory XSetup Form 04/07/90 10:16
STAFFDIR: Form
-----------------------------------------------------------------------------
To remove, enter 'R': _
NAME of form PURPOSE of this form
____________ ________________________________________________
Enter the format name to be used for this form: ____________________________
Enter transaction type for this form*: _______
Enter the type of processing step control (AUTOMATIC or CUSTOM): AUTOMATIC
Are protocol processing steps compiled? No_
Indicate all accounts, groups, or access lists that may use this form:
____________________________________________________________________________
____________________________________________________________________________
____________________________________________________________________________
_____________________________________________________________________________
ADD used to add records but not update (CREATE enabled; GET is not)
ADDUPD used for both adds and updates (CREATE and GET enabled)
LINK entry form is called from another application and is not
visible on ENTRY menu. (currently used only for "approval
entry forms" for routing -- entry forms used for
"modification-during-examination" in Forms Action)
PROCESS CREATE/GET not needed; choosing entry form starts transaction
and SEND/CANCEL leaves the entry form
REMOVE used to remove records only (GET enabled; CREATE is not);
with automatic control, Prism removes current record on SEND
UPDATE used to update records but not add (GET enabled; CREATE is not)
UPLOAD used for upload transactions (contact DTR staff for details)
On this screen you can request features to streamline execution of your form and can ask to add processing steps:
_____________________________________________________________________________
Directory XSetup Form 04/07/90 10:16
STAFFDIR: Form CHANGE PHONE
-----------------------------------------------------------------------------
Enter 'Yes' if searching is permitted when this form is selected: Yes
Enter 'Yes' for an automatic GET when result=1: No_
Enter 'Yes' for an automatic CREATE when result=0: No_
Enter 'Yes' for an automatic REVIEW after send: No_
For REVIEW, use this display defined for the file: FULL____________
or, use this FRAME defined for the form: ________________
Enter 'Yes' to see screens to add, modify, or delete processing steps.
- when this form is selected or cleared: No_
- during data entry: Yes
_____________________________________________________________________________
On this screen, you declare the individual step(s) making up your entry form, in the order in which they should be executed.
______________________________________________________________________________
Directory XSetup Form 04/07/90 10:16
STAFFDIR: Transaction Steps, FORM, CHANGE PHONE
------------------------------------------------------------------------------
Please identify processing steps that Prism should execute. For TYPE,
enter "S" for a screen step, "P" for a protocol step. The step labeled PRE
will be processed after the SEND command is issued. The step labeled POST
will be processed after successful completion of the input transaction.
STEP# STEP ID TYPE TITLE/COMMENT
1 SCREEN1____ s First input screen______________
2 PROC1....... p ................................ <--(SCREEN1,
3 SCREEN2..... s Second input screen............. PROC1, and
4 ............ . ................................ SCREEN2 are
5 ............ . ................................ sample values
6 ............ . ................................ only)
7 ............ . ................................
8 ............ . ................................
SEND steps: PRE and POST
PRE ............ P ................................
POST ............ P ................................
______________________________________________________________________________
NOTE: for forms previously installed, the step-id's appear automatically. Alter or remove them here if you want.
For a custom-controlled entry form, you would fill out a different screen from this one. [See 12.]
On this screen you declare which command options are linked to each screen, and establish other characteristics of the screens in an automatically-controlled entry form. [See 11.4.]
______________________________________________________________________________
Directory XSetup Form 04/07/90 10:16
STAFFDIR: Transaction Steps, FORM, CHANGE PHONE
------------------------------------------------------------------------------
PATRON OPTIONS: Enter "Yes" under options allowed for this screen.
DISPLAY ONLY: Enter "Yes" if the screen data will not be read back.
DO n TIMES: Indicate the number of times Prism should process this step.
SPECIAL CONDITIONS: Enter "Yes" to declare or change conditional statements.
--Patron Options-- DISPLAY DO n SPECIAL
STEP# STEP ID TYPE OK SEND PREV ONLY TIMES CONDITIONS
1 SCREEN1..... S Yes No. No. No. 1. No.
2 PROC1....... P --- --- --- --- --- No.
3 SCREEN2..... S --- Yes No. No. 1. No.
______________________________________________________________________________
For all steps, the fields for STEP#, STEP ID, and TYPE are protected.
- Patron Options. Indicate which commands (SEND, OK, and/or PREVIOUS) you want to make available to end-users when the screen is invoked during data entry. (Some of these commands are protected for certain screens.)
- Display Only. If you wish all the fields on the screen to be protected (i.e., unavailable for input), change "No" to "Yes" here.
- Do n Times. Indicate the maximum number of times you would like the screen to be invoked.
- Special Conditions. Change the "No" to a "Yes" for any screen step that you would like to be conditionally executed. (The following screen lets you specify the conditions.)
(Note: for custom-controlled entry forms, these options and conditions would be specified in your protocol code.)
If you entered "Yes" under Conditions on the previous screen, here you specify the conditions. (To make the screen clearer, the sample below asks for special conditions for both screens as well as for the Proc.)
______________________________________________________________________________
Directory XSetup Form 04/07/90 10:16
STAFFDIR: Transaction Steps, FORM, CHANGE PHONE
------------------------------------------------------------------------------
DO ONLY IF: This condition must be true for the step to be done.
AND THEN CONTINUE AS LONG AS: This condition must be true for every subsequent
execution of a step.
1 SCREEN1 FIRST, DO ONLY IF: .......................................
AND THEN CONTINUE AS LONG AS: .......................................
2 PROC1 FIRST, DO ONLY IF: .......................................
3 SCREEN2 FIRST, DO ONLY IF: .......................................
AND THEN CONTINUE AS LONG AS: .......................................
______________________________________________________________________________
In terms of syntax, anything allowed between IF and THEN in SPIRES is allowed for a special condition in Prism.
IMPORTANT NOTE: the second condition need not be true for the first iteration of the screen, nor need the first condition be true for iterations after the first one.
This additional series of processing step installation screens only appears if you ask to "see screens for declaring processing steps" at form selection or clearing:
______________________________________________________________________________
Directory XSetup Form 04/07/90 10:16
STAFFDIR: Select/Clear Steps, FORM, CHANGE PHONE
------------------------------------------------------------------------------
Please identify any processing steps that Prism should execute. For TYPE,
enter "S" for a screen step, "P" for a protocol step. TITLE is required for
screen steps since that title is used to label the screen.
Processing steps for when form is selected:
STEP# STEP ID TYPE TITLE/COMMENT Note: To remove
1 ............ . ................................ a processing
2 ............ . ................................ step, delete
3 ............ . ................................ the value
under STEP ID
Processing step for when form is cleared:
STEP# STEP ID TYPE TITLE/COMMENT
CLEAR ............ P ................................
______________________________________________________________________________
If you have coded screen steps or protocol steps for when your form is selected or when a user leaves the form, declare them to Prism here.
On the next two screens (condensed onto one page below), you declare whether your steps for form-selection or clearing should only be invoked under special conditions, and if so, what those conditions are.
______________________________________________________________________________
Directory XSetup Form 04/07/90 10:16
STAFFDIR: Select/Clear Steps, FORM, CHANGE PHONE
------------------------------------------------------------------------------
SPECIAL CONDITIONS: Enter "Yes" to declare or change conditional statements.
Processing steps for when form is selected:
STEP# STEP ID TYPE CONDITIONS
1 <step1>..... S No. <----Change "No" to "Yes"
2 <step2>..... P No. for any step that you
3 <step3>..... P No. want conditionally
performed.
/
Processing step for when form is cleared: /
/
STEP# STEP ID TYPE CONDITIONS /
CLEAR <laststep>.. P No. <-------/
______________________________________________________________________________
______________________________________________________________________________
Directory XSetup Form 04/07/90 10:16
STAFFDIR: Select/Clear Steps, FORM, CHANGE PHONE
------------------------------------------------------------------------------
DO ONLY IF: This condition must be true for the step to be done a first time.
1 <step1> DO ONLY IF: .......................................
2 <step2> DO ONLY IF: .......................................
CLEAR <laststep> DO ONLY IF: .......................................
/|\
______________________________________|_______________________________________
|
|
The blank beginning "DO ONLY IF:" appears only by
those steps for which you requested "special con-
ditions" on the previous page. Specify here the
condition that must be true for the step to be
performed. Once again, in terms of syntax,
anything allowed between IF and THEN in SPIRES
is allowed for a special condition in Prism.
You will need to install most or all of the following help records for each of your entry forms:
?INTRO/FORM/<form-name> Introductory text for when
form is selected
<form-name> FORM Text explaining the form for
when end-users type HELP
<form-name>
?ERROR One line explanations of error
codes
?INPUT/FORM/<form-name>/ Context help for each screen
<step-id> of the entry form
The ?ERROR help record contains short explanations of all error codes used in any screen in your Prism application. [See 9.1.1 for details, 11.3.2a for an explanation of how to add error codes to your application.]
For each screen of an entry form, you should create a ?INPUT help record describing the input fields on that screen. This context help record is shown when a user types HELP while on an entry screen. [See 9.1.1 for further information about these help records.]
For each entry form that you install, unless you have screen processing steps to do your introductory work for you, you should write an introductory help record whose key has this form:
?INTRO/FORM/<form-name>
E.g., an entry form called MICRO ORDERS would need a help record with a first line as follows:
* ?INTRO/FORM/MICRO ORDERS
The record should be no longer than 15 lines (excluding lines with control words like $XFILE) and should tell end-users everything they need to know before using the form, for instance:
Remember that you do not need to explain the mechanics of data entry in general; all you need to explain are the specific features of your particular form.
In some cases you may need to ask for input from your end-users just at the point when they are selecting your form. To accomplish this you can code a screen processing step to appear right after end-users choose the form. This screen can either take the place of the ?INTRO screen or appear in addition to the ?INTRO screen. It would appear before ?INTRO if both were installed. [See 9 for details for coding this screen step.] Remember to install it as part of form-selection processing, not as part of data entry processing (which only includes screens invoked between GET/CREATE and SEND/CANCEL).
The ?INTRO record covers situations where end-users have just selected your entry form. But end-users may also ask for help, specifically naming your form (whether or not they have selected it, or even want to). For instance, in the case of a MICRO ORDERS form, end-users might type HELP MICRO ORDERS simply out of curiosity. There are two different steps you might take to provide this help information:
$ALIAS MICRO ORDERS FORM
* MICRO ORDERS FORM
If your introductory screen implies that an end-user has already selected the form (e.g. "You have now selected the Micro Orders entry form..."), you would have to use the second method listed above to avoid ambiguity.
On the HELP TOPICS menu, if the user has selected a form, one entry on the menu is "Help for the entry form you have selected". If the user chooses that item from HELP TOPICS, the <form-name> FORM record is shown.
It's recommended that you include a $CATEGORY ENTRY control word in the <form-name> FORM help record, so that it is listed on the HELP TOPICS menu, in the section "Entering data in this file". [See 6.3.5 for an explanation of the $CATEGORY control word.]
If the number of different help records seems confusing, use the Appendix and Index to keep them all straight. [See 6 to see how they are installed.] Help records may be crucial to the success of your application, so it's worth the trouble even to install the optional ones.
For applications with complex needs, Prism offers you various ways of customizing the standard application that this document has described so far. This chapter will cover customized control of data entry. [See 13 for a discussion of ways of customizing the search process, 14 for a discussion of a relatively easy way of customizing some of the option text that accompanies your application, 16 for a description of how to install a file to be used for linking behind the scenes (a "secondary" file).]
This chapter covers "custom control" of data entry, an alternate method of controlling execution of Prism entry forms. Custom control gives you more power over the entry cycle than the automatic control, but requires a greater command of SPIRES programming. Some of the details that Prism would have taken care of automatically suddenly become the developer's responsibility in a customized application.
This trade-off (of more power for less safety and convenience) makes sense for more complex entry forms. For simple entry forms that do not require much procedural coding, you can use the method described earlier. [See 11.]
If you do choose to control entry form execution by custom processing, you will still need some of the information (e.g., on formats coding standards) presented in the preceding chapter. You still install your entry form through XSETUP FORMS (though in a slightly different manner described below), and you still install help records in PRISM HELP, though the form of the key for some of the records is slightly different.
You will need to customize control of your entry form's execution if any of the conditions below is true:
- Your form links to another, "secondary" Prism file behind the scenes and invokes screens from that file. If you wanted to link to a secondary file without invoking screens from that file, you could do this within the limits of the automatic method described in the previous chapter.
- Your form potentially adds or updates more than one record per entry cycle (whether or not these multiple records are in the same file)
- Your form needs to control the timing of opening and closing a record. [See 11.3 for the method by which this timing is handled automatically.]
- You wish to create "boxes" on your entry screens (e.g., to implement the f2=*Choices command). [See 12A.]
- Your form needs more steps or more conditions than are allowed in automatic installation, or needs some other customized feature.
(Note: this is not necessarily an exhaustive list; other situations besides these may call for custom control.)
Whereas in automatic installation, you install each screen of your entry form by its step-id, in custom installation you only install one protocol processing step to run the entire data entry cycle from GET/CREATE to SEND/CANCEL. The step-id of this protocol step corresponds to a Proc or subroutine in the protocol coded for the form. [See 9 for a discussion of protocol processing steps.]
IMPORTANT NOTE: The single protocol step running a "custom" entry form must contain within its code all of the commands necessary to invoke your screens in their proper order. The Proc must also contain whatever additional protocol code you need for executing the form -- that is, all the coding that you would have put in separate protocol steps for an "automatic" form generally goes within this single Proc for a "custom" form.
Since the procedural code running a "custom" form is no longer separated into multiple steps with distinct step-id's, it becomes your responsibility, within your protocol, to control the flow and timing of the entry form, and make certain that each part executes at the proper time and in the proper order. For instance, if you code a form with two screens and want your end-users on the second screen to be able to return to the first screen with PREVIOUS, you must give Prism specific instructions to this effect in the code that invokes the second screen. [See 12.1.3 for how to do this.] This is completely unlike "automatic" processing, where Prism would automatically know which screen was the "previous" one.
Through the single protocol step for custom data entry, you (and not Prism) become responsible for controlling the flow of screens, listing the correct command options, and opening and closing the record(s) in your application at the proper time. The protocol Proc for custom data entry, like all Procs for Prism, must be structured with a label statement at the beginning and a RETURN statement at the end. The label statement of this protocol step must correspond exactly to the single step-id for form execution that you install in XSETUP FORMS.
Installation of a custom-controlled entry form is fairly similar to installation of an automatically-controlled form. [See 11.] The main difference is that in XSETUP FORMS you ask to declare processing steps for custom instead of automatic data entry:
Prism supports automatic or custom control ... Enter...control for this form (AUTOMATIC or CUSTOM): CUSTOM
Then, on the following screen, you would enter the single step-id of the protocol Proc that controls execution of the entry form. In addition, if your entry form processes multiple transactions, you should request transaction group processing to make certain the transactions happen in an "all or nothing" fashion. (For more on transaction groups, see the end of this chapter.)
Enter custom processing step id: <step-id> Enter 'Yes' if transaction processing is required: Yes
The following charts may help show how custom control of data entry differs in its essential structure from the automatic control described in the previous chapter:
(GET or \ (Prism (Prism (Prism \
CREATE) ----- opens --- calls ..... calls --- (SEND) --------
/ record) 1st step) nth step) /
\ (Prism (Prism (Prism
----------- calls --- closes --- calls
/ PRE record) POST
step) step)
In automatic processing, Prism retains control of form-execution and calls your steps in the order that you have installed them. Prism opens and closes the record for you.
(User \ (Prism (Your Proc
types ----- calls your responds to
GET or / protocol step SEND and
CREATE) and turns some returns
control over control to
to you) Prism)
| /
| /
\|/ /
Within Proc, Within Proc, \
(A) you ask Prism ...... you ask Prism ---- (SEND)
to invoke to invoke /
1st screen nth screen
In custom processing, you take control of the flow and timing of the entry process. Starting at point (A) you use various PERFORM PRISM commands to ask Prism to invoke screens, open records, etc.
As you saw in the previous charts, custom entry requires you to initiate a number of sophisticated processes from within your protocol code. Prism provides a set of special prepackaged commands to help you accomplish this task. These commands, all of which begin with the words PERFORM PRISM, will be described in detail in this section.
There are also some PERFORM PRISM commands that are designed for customizing the search process in Prism. [See 13.] And other commands are used in routing applications [See 12.3.] and to implement "boxes" on entry screens. [See 12A.]
The PERFORM PRISM command is used to deliver high level functions to an application's protocol code. Essentially each PERFORM PRISM command packages together a complex sequence of events related to a single operation, such as prompting the end-user for input. A PERFORM PRISM command not only lets you accomplish a multi-part task through one command, but also guarantees a certain uniformity to the manner in which the task is accomplished.
Some of the functions provided by the PERFORM command are only accessible via the PERFORM command during input processing. Other options duplicate features built into Prism itself, and can be built into procedural code and executed within any protocol step anywhere in Prism.
PERFORM PRISM OPEN - Prepares a SPIRES record
for input
PERFORM PRISM CLOSE - Closes out a SPIRES record
that had been opened
PERFORM PRISM ASSIGN - Forces a specific record to be
CURRENT the "current" record for REVIEW
________________________________________________________________
PERFORM PRISM SCREEN - Invokes a complete screen, e.g.,
to prompt end-user for data
PERFORM PRISM LINK - Transfers control to a secondary
file's environment
PERFORM PRISM UNLINK - Returns control to the
primary file
________________________________________________________________
PERFORM PRISM REMOVE... - Causes the currently OPENed
record to be removed from its
data base
________________________________________________________________
PERFORM PRISM GENERATE - Overlays a display image with
OVERLAY an input screen
PERFORM PRISM OUTPUT - Allows multiple records to be
PERFORM PRISM INPUT updated on a single screen.
PERFORM PRISM PAUSE - Pause from Prism to WYLBUR
[See 13 for PERFORM PRISM commands for searching, 12.3 for commands used in routing applications, 12A for commands used in events and to generate boxes on entry screens.]
Most PERFORM PRISM commands can be (sometimes must be) followed by one or more options. Some options are single keywords, while others have associated values. Except where information is placed within quotes or apostrophes, case and punctuation is not significant. You can separate options by commas or by blanks, and can separate values from options either with an equal-sign or with blanks. Options can be abbreviated to three characters.
As in regular SPIRES protocol commands, you can use variables within PERFORM PRISM commands, preceding the command by a slash to force variable substitution:
/PERFORM PRISM SCREEN screen1, TITLE='#scrntitle' ...
If there is a chance that the variable value contains apostrophes, surround the value with quotation marks rather than with apostrophes.
The PERFORM PRISM OPEN and PERFORM PRISM CLOSE commands act together to control adding or updating individual SPIRES records through Prism, especially when record modification involves prompting the end-user for data. In custom data entry, you must first use PERFORM PRISM OPEN to bring a record from the data base into main computer memory, before you can ask Prism to place data into it. Likewise, before creating a new record, the custom entry form must first use PERFORM PRISM OPEN to open space for it in main memory.
The PERFORM PRISM CLOSE command, nearly always paired with PERFORM PRISM OPEN, takes the record in computer memory and puts it into the data base (if it is a new record) or returns it to the data base (if it is an old record newly updated). Thus the natural sequence of a custom transaction is to OPEN a record, prompt the end-user for input into the record, then CLOSE it and send it (new or in changed form) back into the data base.
Note that in "automatic" control of data entry, Prism itself opens and closes the SPIRES record for you, so you should not need to use PERFORM PRISM OPEN or PERFORM PRISM CLOSE in an automatic form. [See 11.] Rather, you need these two commands when the timing of opening or closing a record becomes too complex for the standard method, or when you have to open more than one SPIRES record during a single CREATE/SEND or GET/SEND entry cycle.
In SPIRES terms, when you issue the OPEN command, Prism performs a GENERATE REFERENCE or a REFERENCE <key>, and a FOR * command. Thus, internally all input into an OPENed record is by way of merge processing. When you issue the CLOSE command, Prism issues an ENDFOR * and an ADD or UPDATE, as appropriate.
The syntax of PERFORM PRISM OPEN is:
PERFORM PRISM OPEN {NEW|CURRENT|RECORD='key of record'} | NOUPDATE
The three options, NEW, CURRENT, and RECORD='key', are mutually exclusive, and one of the three must be specified as part of the PERFORM PRISM OPEN command.
The syntax of PERFORM PRISM CLOSE is:
PERFORM PRISM CLOSE [NEW | CURRENT | RECORD='key'] [NOUPDATE]
The option NEW, CURRENT, or RECORD='key' is not required on the PERFORM PRISM CLOSE command (as it is on PERFORM PRISM OPEN), but any value you specify should match the value given in the corresponding OPEN command, unless you are deriving a new record from one that was already in the data base. For example:
legal pair of commands:
PERFORM PRISM OPEN NEW <--- Prism assumes you mean
PERFORM PRISM CLOSE PERFORM PRISM CLOSE NEW
illegal pair of commands:
PERFORM PRISM OPEN NEW <--- illegal because CURRENT
PERFORM PRISM CLOSE CURRENT doesn't match NEW
legal pair of commands:
PERFORM PRISM OPEN CURRENT <--- legal, assuming you want to
PERFORM PRISM CLOSE NEW derive a new record from the
current one that you opened
legal pair of commands:
PERFORM PRISM OPEN CURRENT <--- current record opened as if it
PERFORM PRISM CLOSE NOUPDATE will be updated, but closed without
updating, for some reason
Except in the two cases listed below, every OPEN command must be paired with a CLOSE command -- the two commands work together, and Prism treats an incomplete pair as an error.
- Exception 1: the PERFORM PRISM OPEN ... NOUPDATE, which asks for a record to be brought into memory for "read" access only, does not usually need to be matched with a PERFORM PRISM CLOSE. You might need PERFORM PRISM CLOSE if subsequent protocol processing requires that no record be open. For example, a SPIRES REMOVE command can't be done while a record is open.
- Exception 2: After opening a record, with PERFORM PRISM OPEN CURRENT, you can remove it with the command PERFORM PRISM REMOVE CURRENT, in which case you should not CLOSE the record: [See 12.1.5.]
PERFORM PRISM OPEN CURRENT
:
PERFORM PRISM REMOVE CURRENT <---instead of PERFORM PRISM CLOSE
Issuing two PERFORM PRISM OPEN commands in a row (without a PERFORM PRISM CLOSE in between) is generally an error, but you can have two or more records OPENed simultaneously if one record is in the primary file and each of the other records is in a separate secondary file (a file accessed via the PERFORM PRISM LINK command). [See 12.1.4 for more on the PERFORM PRISM LINK command, 16 for more on secondary files.]
The technique for deriving a new record from one already in the data base is to open an existing record, modify it, and then CLOSE it as a new record:
PERFORM PRISM OPEN CURRENT
...or
PERFORM PRISM OPEN RECORD='key'
:
<modify the record>
:
PERFORM PRISM CLOSE NEW
When deriving a new record from an existing one, you must take care that the source record's key is properly removed or altered in the new record, before it is sent into the data base.
In this condensed example, the protocol code opens the end-user's current record (1), issues the PERFORM PRISM SCREEN command [See 12.1.3.] to ask Prism to invoke screens INPUT1 and INPUT2 (2a and 2b), then issues the PERFORM PRISM CLOSE command to send the updated record back into the data base (3).
++GET
PERFORM PRISM OPEN CURRENT (1)
:
++PAYMENT.ONE (2a)
PERFORM PRISM SCREEN INPUT1, TITLE='Payment Plan' \
SEND='Jump CLOSE', OK
:
++PAYMENT.CONT (2b)
PERFORM PRISM SCREEN INPUT2, TITLE='Amount' \
SEND='Jump CLOSE', OK, PREV = 'Jump PAYMENT.ONE'
:
++CLOSE
PERFORM PRISM CLOSE CURRENT (3)
RETURN
Although the example above shows a single-record transaction, you can also issue the PERFORM PRISM OPEN and PERFORM PRISM CLOSE commands multiple times within one entry form, if you want your form to update multiple records within a single GET/SEND entry cycle. To the end-user, this transaction should still look like the update of a single record, however. (Some cautions on multi-record updating in Prism are discussed later in the chapter.)
Prism tries to accommodate large records by determining the size of the record and setting SUPERMAX to 120% of that size, to guarantee a successful OPEN. If SUPERMAX is already larger than the computed requisite size, the larger value is used. SUPERMAX is restored to its original value after the record is opened.
Within an entry transaction, the PERFORM PRISM ASSIGN CURRENT command allows you to force a specific record to be the current record for purposes of the REVIEW or DISPLAY * command, in situations where Prism's usual rules for establishing a current record do not meet your needs.
For example, if you are using multiple PERFORM PRISM OPEN and PERFORM PRISM CLOSE commands to update several records within a single GET/SEND entry cycle, you may wish to specify exactly which of those records should be the one displayed with the REVIEW command at the end of the transaction. (Normally, the last record closed in the primary path is considered the current record.)
The syntax of PERFORM PRISM ASSIGN CURRENT is:
PERFORM PRISM ASSIGN CURRENT RECORD='key'
The PERFORM PRISM SCREEN command invokes a particular screen and displays it online to the end-users of the form. In SPIRES terms, PERFORM PRISM SCREEN invokes a pair of frames from your SPIRES input format, where the names of the invoked frames closely parallel the "screen-id" named in PERFORM PRISM SCREEN. [See 12a.1 for details about Prism screen processing.]
Although most often used in entry forms, PERFORM PRISM SCREEN can also be used in other places in Prism, e.g., to invoke a parm screen in reporting.
PERFORM PRISM SCREEN screen-id
ID = 'id'
TITLE = 'title'
WRITE | READ | PROMPT | REPROMPT | PROTECT | NOPROMPT
OK | OK = 'command'
SEND | SEND = 'command'
PREVIOUS | PREVIOUS = 'command'
CANCEL | CANCEL = 'command'
DONE | DONE = 'command'
YES | YES = 'command'
NO | NO = 'command'
OVERLAY = n
OPTOK = 'text'
OPTSENd = 'text'
OPTPREvious = 'text'
OPTCANcel = 'text'
OPTDONe = 'text'
OPTYES = 'text'
OPTNO = 'text'
ENDPROC = 'step-name'
TIMELIMIT = n
CURSOR = (row,col) | CMD
In the list of options above, screen-id is required, and the TITLE option is required for most screens (see below). In addition, either OK or SEND must be enabled for any screen except a NOPROMPT screen that is used for post-SEND confirmation.
Screen-id is the unique identifier of the screen, corresponding to frame names in your format.
Screen-id is used:
- To identify format frames that Prism should execute.
- As part of the key of the context help record for the screen (in the form ?INPUT/FORM/form-name/screen-id or ?INPUT/REPORT/report-name/screen-id)
- In DECLARE SCREEN statements in protocols when events are defined as part of the screen processing
Schematic illustration of how screen-id is used:
for PERFORM PRISM SCREEN SCREEN1 ...
screen-id frame names
--------- -----------
SCREEN1 SCREEN1.IN
SCREEN1.OUT
help keys
-------------------------------
?INPUT/FORM/form-name/SCREEN1 (if screen is in entry form)
...or
?INPUT/REPORT/rept-name/SCREEN1 (if parm screen for a report)
to define screen events
-----------------------------------------------------
DECLARE SCREEN SCREEN1
ON EVENT CHOICE IN ZONE zone-name, PROC proto-step
ON COMMAND SEND, PROC proto-step
[See 12a.2 for explanations of DECLARE SCREEN, 6, 10.7, 11.6 to read about help records.]
The ID option names an ID other than "screen-id" to be used for context helps and for declaring events for the screen. Using ID lets you separate the controls for naming the format frames and identifying the screen for purposes of helps and events.
In the TITLE option, specify the screen title, to appear in the status area (2nd line of the screen). A title is required except when you are only reading the screen (READ), are reusing an existing screen (PROMPT or REPROMPT), or have created a post-SEND confirmation screen using NOPROMPT.
The processing of a screen consists of three phases -- generating the image via an output frame (Generate), presenting the end-user with the image and waiting for a response (Display), and reading the altered image back via an input frame (Process). The options listed above let you control each part of the process independently in cases where you need program control, say, after the screen is generated but before it is shown to the user. They let you control the timing of screen transmission much more precisely than automatic data entry allows.
Generate Display Process
<default>: yes yes yes
PROTECT: yes yes n/a
WRITE: yes yes no
READ: no no yes
NOPROMPT: yes no no
PROMPT: no yes yes
REPROMPT: no yes yes
PROTECT is useful when you have a display-only screen (such as a confirmation screen) that requires no input frame. It also allows you to use a regular screen, one that normally would create input fields, and display it protected, bypassing the input phase.
The WRITE/READ combination provides flexibility in how you process a screen image. For instance, you could use the command to display data from one file (with the WRITE option), next issue a PERFORM PRISM LINK or UNLINK command, and finally read the end-user's input into the linked file (with the READ option). [See 12.1.4.] As another possibility, separate WRITE/READ operations would allow an application to access the same image repeatedly for multiple record processing.
NOPROMPT/PROMPT/REPROMPT offer flexibility in the presentation of the screen image. For example, you may not know until the screen image is generated whether or not OK or SEND should be enabled:
PERFORM PRISM SCREEN TOTALS, NOPROMPT If #LastScreen then PERFORM PRISM SCREEN TOTALS, PROMPT, SEND Else PERFORM PRISM SCREEN TOTALS, PROMPT, OK
REPROMPT provides a function similar to $STATUS=REPROMPT during screen processing, but allows you to invoke reprompting from within protocol code in cases where the error can only be detected in the protocol, not the format. As with $STATUS=REPROMPT in a format, the REPROMPT option here will cause changed field information to be remembered and transmitted back to your input format. REPROMPT can even be used the first time a screen is written to cause it to behave as a reprompt screen, e.g., any message will be presented BRIGHT and YELLOW, and $ScrnStat will be set to REPROMPT. This is useful in cases where an application is set up to detect errors in existing data and wishes to alert the user when they first visit a screen.
PROMPT is just like REPROMPT, except it does not set $ScrnStat to REPROMPT nor cause any message in $MsgLine to be treated as error messages.
The NOPROMPT option lets you invoke a confirmation screen to appear after the end-user has typed SEND and a record (or more than one) has been successfully added or updated. The screen occurs "outside" the entry form from the end-user's point of view and so it does not prompt for input or enable paging commands such as SEND or OK. Because of the extra options that appear underneath this screen in Guided Mode, 15 lines is the maximum length for a confirmation screen on a standard 24-line terminal.
A record must be OPENed (1) before its data can be displayed by PERFORM PRISM SCREEN...NOPROMPT (2). In other words, you would ordinarily invoke the NOPROMPT screen (2) before CLOSing the record (3):
++OPEN.IT
PERFORM PRISM OPEN NEW (1)
:
++MODIFY.IT
PERFORM PRISM SCREEN screen1 ....
:
++CONFIRMATION
PERFORM PRISM SCREEN screenlast NOPROMPT (2)
:
++CLOSE.IT
PERFORM PRISM CLOSE NEW (3)
RETURN
If because of SPIRES close-out processing, or for some other reason, you must CLOSE the record before invoking the NOPROMPT screen, you can refetch it using PERFORM PRISM OPEN...NOUPDATE, then PERFORM PRISM SCREEN...NOPROMPT.
You can also use NOPROMPT to invoke an introductory screen at the time of file-, report-, or entry-form-selection. The screen could display variable data unlike a normal help record, but would not enable the OK command.
The OK, PREVIOUS, SEND, CANCEL, DONE, YES, and NO options enable the corresponding commands for the end-user while the screen (or box) is prompted. You may follow them by a protocol command to be executed if or when the end-user issues the command.
PREVIOUS is virtually always followed by a protocol command to handle branching back to an earlier screen. Custom data entry does not automatically branch back to the "previous" screen, because it has no way of knowing what that screen is.
PERFORM PRISM SCREEN PAGE3, OK, PREV='Jump PAGE2', SEND='Jump DONE'
Details about command presentation at a screen level:
- SEND is not applicable on parm screens, so is ignored; you must enable it on entry form screens.
- OK is automatically supplied on parm screens; you must enable it on entry form screens.
- CANCEL is automatically supplied on parm and entry form screens.
- You must enable PREVIOUS on parm screens and entry form screens.
- None of the commands should be enabled on a NOPROMPT screen.
If you are using PERFORM PRISM SCREEN in a box, see the chapter on boxes for a discussion of commands that should be enabled. DONE, YES, and NO are applicable only within boxes. The CANCEL option enables either f8=Cancel (on a screen) or f9=Cancel Box (in a box). [See 12a.6.2.]
During an event proc, you may use the "PERFORM PRISM DISABLE (or ENABLE) pfkey" command to disable or enable commands (function keys) when the parent screen is shown again after the event. [See 12a.16.]
You may specify a protocol command to be executed when the CANCEL command is issued by the user on this screen. For example, you might branch to protocol code to perform "cleanup" activities or to set the $NextCmd variable. [See 17.6.] Of course, the current transaction should not continue once the user issues the command, so your CANCEL clause should not present additional screens. Note that the presence or absence of the CANCEL option in your PERFORM PRISM SCREEN command does not control whether or not the command is enabled on the screen -- Prism controls that automatically. The option simply provides a command clause for the case when the command is used.
This option is used in conjunction with a PERFORM PRISM GENERATE OVERLAY command in order to merge an input screen with a display screen image. The "n" here refers to which of a series of generated display images should be shown with the input screen. [See 12.1.6 for details and an example.]
This option allows a timeout interval to be associated with the screen read. "n" is an integer, from 1 to 6000, indicating seconds. This option would cause a session that has been idle for "n" seconds to invoke a timeout, cancelling the current process (input, file selection, etc.).
This option lets you specify cursor position on a screen. Row is specified relative to your display, not relative to the "absolute" row on the screen. The CMD option places the cursor on the command line.
You may control the wording of the Guided Mode options at the bottom of the screen with the OPTOK, OPTPREV, etc. options on PERFORM PRISM SCREEN. Your text may be up to 36 characters long, and it is used after Prism's leading text "Type: <command> ". A trailing period is supplied if it is not included in your text. The option text only appears, of course, if the corresponding command is enabled on the screen.
For example, this command:
PERFORM PRISM SCREEN PAGE1, OK, OPTOK='to see additional detail'
would cause the Guide Mode options for screen PAGE1 to appear as:
Type: OK to see additional detail. CANCEL to cancel this transaction.
Prism juggles the option text on the screen to take maximum advantage of the space available, as the relevant command options are presented. Although 36 characters are allowed, some of your text may be truncated if there are two long option text strings on the same line. Prism does the best it can, but it is prudent to check the appearance of the text online in cases of doubt.
Note that the MOD OPTIONS entry form in Prism Profile also lets you control the wording of Guided Mode options. MOD OPTIONS let you control the text for an entire entry form; these options on PERFORM PRISM SCREEN give you control on a screen-by-screen basis.
This option lets you specify a protocol processing step to be executed after all other screen work has been done. An ENDPROC protocol step is invoked after the <screen>.IN frame has executed, in response to an OK, PREVIOUS, or SEND command. This protocol step might be used for protocol code that does work not possible in your format, but which must be done to complete a particular screen, for example, lookups or inter-element edits that require PERFORM PRISM LINK or other PERFORM commands. You can think of the ENDPROC protocol step as an extension to your input frame processing.
Note that any interaction with the user during ENDPROC processing should be via boxes. One use of an ENDPROC option, in fact, is to name a protocol step to generate a resolution box. [See 12A for complete details about boxes.]
Note that the ENDPROC option is being phased out, in preference to the use of the ON COMMAND statement in the DECLARE SCREEN section of protocols. The new tool lets you declare protocol steps to be executed when specific commands are issued, including CANCEL. [See 12a.1, 12a.2.]
When PERFORM PRISM SCREEN is issued, control passes from your protocol to the format supporting the screen. After appropriate prompting, control remains with Prism or the format until the end-user types SEND, OK, or PREVIOUS. Prism will process a $STATUS value of REPROMPT or WARN, and will also process the UNDO command. Should a CANCEL request, a timeout, or a system error occur, Prism will clean up the uncompleted transaction, back out of both the PERFORM and the custom Proc, and prompt the end-user for a new command. Some other system-wide commands (including PAUSE, SHOW, SUGGEST, and HELP) also continue to be processed by Prism even within an entry environment.
The PERFORM PRISM LINK command lets you link your application to a secondary Prism file to which you have authorized access. While the link is in effect any command you issue (e.g., to invoke a screen or to input data into a file) will take place in the secondary file, not in your primary file.
PERFORM PRISM UNLINK breaks the linkage and restores your primary application as the environment in which commands take effect.
For a PERFORM PRISM LINK request to succeed, the file to which your application links must be installed in Prism Profile as a "secondary" file and your application's name (or your account as file owner of the application) must be installed as having access to the secondary file. This process is carried out using the ADD LINK entry form. [See 16.]
The syntax of PERFORM PRISM LINK is:
PERFORM PRISM LINK file-id [FORMAT format-name]
The LINK command changes the file environment to the secondary file specified by its file-id. You can also name a SPIRES format to be set in the secondary environment to support any screen, menu or other formats processing required there. If the format name contains a blank, enclose the name in quotes.
The syntax of PERFORM PRISM UNLINK is simply:
PERFORM PRISM UNLINK [CLEAR]
PERFORM PRISM UNLINK removes your application from the environment of your secondary file and returns you to your calling application's environment. The CLEAR option unloads the code associated with the secondary file from memory, increasing efficiency and making more memory available to the rest of your application. It's a good idea to include this option when a LINK is used only once at the start of a select, report or an entry form. It should not be used if a LINK is used more than once, for instance, during searching, printing or an input transaction.
PERFORM PRISM LINK and UNLINK can also be used in protocol steps outside data entry, e.g. to look up information in a secondary file.
Note that installing a secondary file with the ADD LINK form in Prism Profile is a better way to support linking files than using SPIRES path processing in a protocol step, because of the security offered by the PROGRAM = PRISM statement in the secondary file's file definition, and by ADD LINK. [See 16.] If the SPIRES file definition for a secondary file includes a PROGRAM = PRISM statement in its subfile-section, other Prism applications will not be able to select or link to the secondary file through a path, but only through the PERFORM PRISM LINK command.
In this condensed example, the protocol code opens and closes a new record in the primary file (1), then performs a link to a secondary file that was installed with file-id TESTLINK (2). At the time of the link it also asks Prism to set the format named "LINK FILE". (This format was written for the secondary file, not the primary, and did not need to be installed or declared in Prism Profile.)
Within the secondary file, the protocol step opens a new record (3), invokes a screen for input (4), closes the new record, and breaks the link, returning to the environment of the primary file. The end-user never needs to be aware at any point that data entry is actually going on in two files, instead of just one.
++OPEN.PRIMARY
PERFORM PRISM OPEN NEW (1)
:
PERFORM PRISM SCREEN ADD1, TITLE ...
PERFORM PRISM CLOSE NEW
:
++DO.LINK
PERFORM PRISM LINK TESTLINK, FORMAT "LINK FILE" (2)
PERFORM PRISM OPEN NEW (3)
:
PERFORM PRISM SCREEN LINKSCREEN, TITLE ... (4)
PERFORM PRISM CLOSE NEW
PERFORM PRISM UNLINK (5)
RETURN
As mentioned earlier, in general you need to "close" a PERFORM PRISM OPEN command with PERFORM PRISM CLOSE before you issue a second OPEN command. [See 12.1.1.] But this is not the case when the second record is in a linked secondary file. For instance:
PERFORM PRISM OPEN NEW <---This sequence of commands would be PERFORM PRISM OPEN NEW an error without an intervening CLOSE PERFORM PRISM OPEN NEW <---This sequence of commands is legal PERFORM PRISM LINK ... because the second OPENed record is PERFORM PRISM OPEN NEW in a secondary file
(Some cautions on multi-record transactions are discussed later in the chapter.)
The PERFORM PRISM REMOVE command can be used to remove a record within custom data entry. Many record removal entry forms can be simple enough to handle with automatic control and would therefore not need to use PERFORM PRISM REMOVE. [See 11.3.4 for guidelines for designing record removal screens and information about installing an automatic-control entry form for removing records.]
The syntax of PERFORM PRISM REMOVE is:
PERFORM PRISM REMOVE CURRENT
CURRENT refers to the current record -- i.e., the record that the end-user specified with the GET command.
A removal transaction follows the general pattern shown here:
++OPEN
PERFORM PRISM OPEN CURRENT
:
++DISPLAY.RECORD
PERFORM PRISM SCREEN RemoveScreen \
TITLE ='Confirm REMOVE request' \
SEND = 'Jump REMOVE.IT'
:
++REMOVE.IT
PERFORM PRISM REMOVE CURRENT
This is one of the rare cases where PERFORM PRISM OPEN is not paired with a PERFORM PRISM CLOSE command.
Note that only the currently OPENed record (the CURRENT record) can be removed with the PERFORM PRISM REMOVE command.
Also, once this command is issued, no more screens with frame-type of DATA can be invoked from that record, though other records might be opened with PERFORM PRISM OPEN, and screens with frame-type of XEQ might still be invoked with PERFORM PRISM SCREEN.
Entry forms for record removal should generally be devoted to that one task only. But it's technically possible to install an entry form with transaction type of UPDATE that conditionally issues a PERFORM PRISM REMOVE of the retrieved record.
In addition, there is no way directly to REVIEW a removed record, though you can code a confirmation screen using an XEQ frame to confirm the record's removal after the end-user types SEND.
The PERFORM PRISM GENERATE OVERLAY command supports a technique of generating a multi-page display image and then merging that image with an input screen.
To see an example of how this is used, look at the EXAMINE entry form in the Forms Action file. (See screen sample below.) Briefly, the first input screen that you see when you GET a record in EXAMINE is composed of a section at the top of the screen with a single input field and some text. This part of the screen is generated by the routing application. Below that is a protected area consisting of data formatted by a display format in the sub-application. (That is, Prism's routing application calls the sub-application's display format.)
Forms Action Entry Form: EXAMINE 02/06/92 16:01
REGISTRATION # 4039 Record 13 of 14
_ <-- Action (A=Acknowledge FYI)
Enter "A" and type SEND below to indicate that you've seen the form.
To examine the complete form, add remarks, or add to the routing list,
leave "Action" blank and type OK below.
-------------------------------------------------------------------------
REGISTRATION # 4039: Jeffrey Powell -- Registered for DSG.999E. [Last
approved by Stevens on 12/13/91.]
Student: Jeffrey Powell
Course: SNAP Checks Travel Screens Demo(DSG.224)
Date: Location: Turing Aud (Polya 111 12:00 - 1:30)
[etc. ... the display image continues]
How is this accomplished? The PERFORM PRISM GENERATE OVERLAY command generates a display image and places it into stored CRT areas. The SPIRES variable $CRTCNT then contains the number of stored screen images (e.g., if the generated display image takes several screens).
The syntax is:
PERFORM PRISM GENERATE OVERLAY FRAME=frame
[RECORD=key]
[PROTECT]
Then, a PERFORM PRISM SCREEN command with an OVERLAY=n option tells Prism to merge the screen output with the nth stored display image. To support paging through a multi-screen display image, your protocol needs to use $CRTCNT to keep track of which stored image the user is currently looking at, and how many remain.
Here is a simple template outlining how these commands might be used:
perform prism generate overlay frame=full ; Prism generates a display image using the FULL frame let CurrentPage = 1 repeat let cmds = 'SEND' /if #CurrentPage < $CRTCNT then let cmds = #cmds ', OK' /if #CurrentPage > 1 then let cmds = #cmds ', PREVIOUS' /perform prism screen pick.action ... overlay = #CurrentPage #cmds ; This merges the PICK.ACTION input screen with a stored display ; image from the FULL frame. if $LastCmd = 'PREVIOUS' : let CurrentPage = #CurrentPage - 1 else if $LastCmd = 'OK' : let CurrentPage = #CurrentPage + 1 until #CurrentPage > $CRTCNT
Note: These commands have been used for many years in applications maintained by Prism staff, but have never been documented for public use. This documentation is from internal technical notes and may be incomplete; if you have questions, contact DTR staff.
The PERFORM PRISM OUTPUT and INPUT commands allow a Prism application to write multiple records to the screen and then process them iteratively on input. Multiple pages (OK and PREVIOUS) are handled by Prism automatically.
To see an example of how this is used, look at the SUMMARY entry form in the Forms Action file. (See screen sample below.) Each of the input fields on this screen applies to a different record.
Forms Action Entry Form: SUMMARY 07/17/92 17:41
18 records
---------------------------------------------------------------------------
APPROVAL forms - "Actions" are A=Approve, R=Return to originator, H=Hold
Action Form and summary (* indicates urgent items)
__ PURCHASING # A00870: DEMO Standard Requisition Total $14.95 --
7SKP101-94610 First Account. (Paste pots for Patty)
[Originated by John Klemm. Last approved by Johnstone on
03/23/90. Remarks by Klemm]
__ PURCHASING # A00872: DEMO Standard Requisition Total $11.80 --
7SKP101-94610 First Account. (Pencil cup cleaners for Cleo)
[Originated by John Klemm. Last approved by Nardini on 09/07/89.
Remarks by Klemm]
__ PURCHASING # A00873: DEMO Standard Requisition Total $13.30 --
7SKP101-94610 First Account. (Paper clip detanglers for Denise)
[Originated by John Klemm. Last approved by Sebald on 08/14/91.
Remarks by Klemm]
__ TJOURNAL # 8908730AR: Transfer of Expense # 730 08/31/89 1 Items
2 Lines Tot.Cr 44.97. (Correct charges for film "Basic Dimple
Removal".) [Originated by John Klemm. Last approved by dietrich
on 09/21/89.]
__ TJOURNAL # 8908730AV: Transfer of Expense # 730 08/31/89 1 Items
2 Lines Tot.Cr 31.19. (Correct charges for film "Getting
Control of Your Armpits".) [Originated by John Klemm. Last
approved by Gotelli on 09/14/89.]
__ TJOURNAL # 8908730AZ: Transfer of Expense # 730AZ 08/31/89 1
Items 2 Lines Tot.Cr 75.66. (Correct charges for film
"Sphygmomanometers: Why so hard to spell?".) [Originated by
John Klemm. Last approved by Sebald on 08/14/91.]
The entire multi-record sequence is set up in an initial PERFORM PRISM OUTPUT, then a subsequent PERFORM PRISM INPUT is used to read records one at a time. It is similar to GLOBAL FOR processing in SPIRES where a single command (e.g., FOR RESULT) establishes the sequential processing environment while later commands (e.g., DISPLAY) deal with the records one at a time.
The initial PERFORM currently looks like this:
PERFORM PRISM OUTPUT screen-id
[ALL | range]
TITLE='title'
[NEW | FROM source]
[TIMELIMIT=n]
[CURSOR='n,m'] <not yet supported>
Records output may be variable in length. You must use PUTDATA=1 in order to trigger overflow when a record is too large for the screen. You must also make sure that the first PUTDATA done will access the highest row required for that record, otherwise partial records may be written.
If multiple pages are generated, Prism allows OK on all pages but the last, PREVIOUS on all pages but the first.
PERFORM PRISM OUTPUT only establishes the information required for multiple record processing; it does not actually output any record. This does not happen until you request the first record to be processed. Once the multi-page processing parameters are established, you actually do the processing with the PERFORM PRISM INPUT command:
PERFORM PRISM INPUT [NEXT]
[REFERENCE]
END='command'
[CURRENT | *]
When this command is issued, Prism will first check to see if the requested record is on the current page. If not, the next (or first) screen of records is generated and shown to the user for input. After the user has input values into the records on the screen and that screen is transmitted back to Prism, then Prism invokes the input frame against the requested record.
Each invocation of PERFORM...INPUT processes the frame against the entire DATA area on CRT. $PARM is set to the starting row for the current record. This way the input frame can start at $PARM and do relative row processing, yet still do a GETDATA on an absolute row,
The END clause is executed when the application requests input from the next record and no more exists, or if the user has typed SEND on the current screen and the last record on the screen had been processed.
The output frame ("screen-id.OUT") must be a DATA frame. The input frame ("screen-id.IN") can be either a DATA for XEQ frame. If it is a DATA frame, each PERFORM PRISM INPUT automatically opens and closes each transaction; nothing else is required of the application. If "screen-id.IN" is an XEQ frame, Prism will merely XEQ the frame against the DATA area on the screen. Processing of any information read from the screen must be done by the application in subsequent protocol statements.
If the REFERENCE option is included in PERFORM PRISM INPUT, Prism will re-fetch the record and drive it through a frame named "screen-id.REF", which must be a DATA frame.
Here is a COMPLETE multiple record process using a DATA input frame:
++STEPID PERFORM PRISM OUTPUT screen ++LOOP PERFORM PRISM INPUT, END='RETURN' JUMP LOOP
Here's how it looks if the application uses XEQ frames. This gives an application the opportunity to only do an update if data read on the screen is changed.
++STEPID PERFORM PRISM OUTPUT screen ++LOOP PERFORM PRISM INPUT, END='RETURN' IF ~#CHANGED : JUMP LOOP PERFORM PRISM OPEN CURRENT USING frame MERGE PERFORM PRISM CLOSE JUMP LOOP
Note that the "CURRENT" record stays in sync with the record that is being read off the screen.
Ideally the user should see the screen as just like any other, and if an error occurs they should be able to move about and change anything on the screen. This means that in any REPROMPT situation, Prism reprompts the user, completes the processing of the current record, but on the next PERFORM...INPUT request it backs up to the top of the screen and resumes processing with the first record on the current page. This works fine for UPDATES, but could cause redundant ADDs if reprompting took place during NEW processing. This is an area for future consideration.
The PERFORM PRISM PAUSE command provides a programmatic way to pause from a Prism input screen to WYLBUR, so that a user might work on data in a WYLBUR active file.
Prism manages the transition from Prism to WYLBUR and back to Prism. But your code needs to do everything else, including opening a new active file, doing something with the contents of the active file, and restoring the user's previous active file.
It is recommended that you OPEN a new, temporary, named and titled active file for the user (e.g. OPEN EditText TEMP TITLE 'Edit description').
The syntax is:
PERFORM PRISM PAUSE TEXT = 'text'
The TEXT option on PERFORM PRISM PAUSE is required. This text is shown after Prism pauses and before the WYLBUR command prompt. Prism itself supplies the message "-Type CONT to re-enter Prism" after your text. (Use // in your text to signal line breaks.)
For example, this command:
PERFORM PRISM PAUSE \ TEXT='The description is in your active file.\ //Type VIEW to edit the description, then CONT.\ //To cancel description modification,\ type CLEAR ACTIVE and then CONT.'
would produce this interaction:
[user types X on a button on the input screen and a proc executes] [the Prism screen clears] The description is in your active file. Type VIEW to edit the description, then CONT. To cancel description modification, type CLEAR ACTIVE and then CONT. -Type CONT to re-enter Prism Command>
Here is a more complete protocol example showing how you might use PERFORM PRISM PAUSE to allow a user to edit data in the active file after activating an on-screen button.
* form/donations
declare screen new.donation
on event button, in zone desc.button, proc pause
:
++new.donation
; -----------------------------------------------------------
; Main code for DONATIONS input.
; -----------------------------------------------------------
:
; generate the input screen. User may enter text directly
; or use a button to edit the text in the active file.
;
perform prism screen NEW.DONATION, send
:
return
++pause
; -----------------------------------------------------------
; This proc executes when user types X in the button labeled
; "Edit text in the active file?" on the input screen.
; -----------------------------------------------------------
:
; Read contents of description field into an array
perform prism screen NEW.DONATION read
; Save current active file number and open new temp active file
let PrevActive = $ActNum
open DESCEDIT temp title='Donation description'
using DESC.TO.ACTIVE in active display
perform prism pause \
TEXT='The description is in your active file.\
//Type VIEW to edit the description, then CONT.\
//To cancel modification, type CLEAR ACTIVE and then CONT.'
; Read in the active file. An empty active file means the
; user has canceled changes, so skip processing it.
while $Int($SysEval(Lines)) > 0
xeq frame ACTIVE.TO.DESC
if #LongLine > 0 : begin
; If any line is longer than 79 characters, return to
; WYLBUR to correct the problem.
/perform prism pause text= \
'Line #LongLine is longer than the 79 characters allowed.\
//Correct the line length and type CONT.'
endb
else leave
endwhile
/pick #PrevActive
set status = 'REPEAT'
return
In General Access Prism (aka Anonymous Logon Prism or GA PRISM), the PAUSE command is blocked. But in regular Prism, at the "Your Response" prompt, you may respond with the PAUSE command. You are placed in a line-by-line command prompt loop that limits your commands to the list below.
1. CONtinue or RETurn ; gets you back to Prism session.
2. ?anything or HELp anything ; gives you the message:
-Type CONT to re-enter Prism
3. EXIt, Quit, END ; all exit you from Prism.
LOGanything ; also exits you from Prism.
4. The following do what you'd expect:
/*anything
..protocol (executes protocol from PUBLIC PROTOCOLS)
SHOw anything
IN ACTive {CLR|CLN|CONtinue|CLEar|CLEan} SHOw anything
EXPlain anything
PERform SYStem something (PRInt, MAIL, SEND, DUMP) ...
5. SELect, LET, EVAl ; are blocked with error message.
6. Anything else is sent to the underlying Emulator,
which may pass it to Unix. These include:
a. SET commands, such as: SET PREFIX ...
b. USE, PICK, OPEN, CLOSE, SAVE, ...
c. ls, pwd, vi, wylbur, %commands, ...
d. Wylbur commands over the interconnecting pipe.
DELETE, COPY, CHANGE, ...
There are three important things to consider when you code an entry form that will add or update more than one record:
Because bracketed transaction groups are essential to the success of a multi-record update, Prism provides them for you, as long as you request them within XSETUP FORMS. E.g., for a custom form whose single step-id is CUSTOMSTEP:
Enter custom processing step-id: CUSTOMSTEP Enter 'Yes' if transaction processing is required: Yes
If your form potentially adds or updates more than one record, you should definitely answer 'Yes' to this prompt.
You should take care to reserve exclusive use of all records to be OPENed within a multi-record transaction; you can accomplish this for each individual record by issuing (within your protocol step) the SPIRES command SET RECORD LOCK followed by the key of the record to be reserved.
These locks must also be cleared later so that other end-users can get to them later -- this happens automatically in most cases, but in some situations you may need to issue the CLEAR RECORD LOCK command in order to free records that you earlier locked. See SPIRES documentation on transaction groups and on record-locking for more information.
In the future, Prism may allow end-users to update multiple records within a single GET/SEND or CREATE/SEND entry cycle, but currently each entry cycle works with only one visible record per transaction. For instance, if an end-user has a search result of five records, and has chosen an entry form to modify all the records, each GET/SEND cycle will update only one of the five records in the search result. (The end-user would have to use the GET command five times to modify all five records.) For the sake of consistency with end-user expectations, a multi-record entry form should probably maintain the appearance that a single record is being updated.
The REVIEW command works for customized entry the same way as described earlier. [See 11.3.1.] Normally, Prism assumes that the last record closed in the primary path is the "current" record, so that is the one that is displayed with the REVIEW command.
If necessary, you may use the PERFORM PRISM ASSIGN CURRENT command to force a different record to be the current record for purposes of REVIEW. [See 12.1.2.]
As mentioned earlier,most REVIEW frames are of frame-type DATA. [See 11.] However, you can also code a frame of type XEQ, which Prism will execute without accessing any records. If your end-user's Prism transaction actually updates multiple records behind the scenes, you can code a XEQ frame that provides a summary of all the data entry, displaying values that were assigned to variables during the entry process.
If you install context help as described earlier for a custom-controlled input screen, the help record's key should identify the screen it supports by "screen-id" rather than by "step-id" (since all your screens are invoked within a single processing step). [See 9.1.1 for installing context help.] The screen-id is the root of the frame-id of the frames supporting the screen -- i.e., a screen CUSTOM1.
In addition to the entry forms described in the last few chapters, Prism also offers a facility for creating routing applications: entry-oriented applications that not only process transactions but also "route" the completed record for approval and action.
Instructions for creating a forms routing application are in a separate manual called "How to Install a Routing Application in Prism". Use the PUBLISH command to print a copy.
The following PERFORM PRISM commands are covered in detail in that document:
PERFORM PRISM ROUTE - Invokes the routing page
in Prism
PERFORM PRISM ASSIGN ROUTE - Supplies approver names on routing
pages automatically
PERFORM PRISM ASSIGN ENDROUTE - Supplies endroute approvers
This chapter describes tools and techniques available to control application flow above and beyond the normal screen processing provided by PERFORM PRISM SCREEN:
- Events: places during screen processing where independent modules of protocols code can be executed.
- Boxes: overlays on top of the background screen image, where you can present new text or input areas.
- Zones: designated places on an input screen to which your protocol code might refer, or where an action might occur that should invoke an event protocol step.
- Trigger fields and buttons: input fields that can cause a change in the screen image simply by the fact that data enters the field.
In addition to describing extensions to the Prism protocols language and providing examples, standards, and guidelines for the use of events, boxes, zones, and trigger fields, this chapter covers a number of PERFORM PRISM commands that are useful with these tools:
PERFORM PRISM SET SUBAREA - Defines size and placement of
a box on a background screen
PERFORM PRISM CHOOSE - Presents a list of items for
the user to choose from
PERFORM PRISM PROMPT TEXT - Prompts text for the user
PERFORM PRISM PROMPT VALUE - Provides a simple input field
PERFORM PRISM COPY - Copies values to or from a screen
PERFORM PRISM SET ERROR - Updates a screen image with an error
PERFORM PRISM RESET UNDO - To control scope of UNDO command
PERFORM PRISM DISABLE pfkey - Disables or enables commands (and
PERFORM PRISM ENABLE pfkey function keys) in an event proc
This section explains what happens during processing of a PERFORM PRISM SCREEN command, how "events" and "boxes" fit into the picture, and what some of your options are for controlling the flow of your application during screen processing.
"Events" are places where your application can take control during screen processing, when one of several pre-defined situations occurs. Events happen within a single PERFORM PRISM SCREEN call, but are independent of your main flow of screen logic. You could describe events as "asynchronous interrupts" (to borrow terminology from other programming languages) or as independent modules of protocols code that may or may not get called from your mainline screen code.
When a screen is presented to a user, there are a number of things that might happen under Prism's control and without application knowledge, such as the user issuing a HELP or SUGGEST command. Prism executes its own code to process the HELP or SUGGEST command and then returns control back to your screen processing code. Similarly, you can think of events as things that can happen during screen presentation in response to some action, where your application (rather than Prism) does have control, but still independent of the main screen flow.
"Boxes" are an extension of normal screen presentation in which new text or input fields are displayed in a box that overlays part of the screen. [See 12a.5.1 for examples of boxes.]
Boxes happen in response to events. One of the primary uses of events is to generate boxes on screens, but events may do other things besides present boxes.
There are several different types of events whose timing and purpose differ.
- Choice events -- invoked when a user presses the f2=*Choices key while his cursor is positioned in a field labeled with an asterisk. The purpose of a choice event is to present a "choice box" where the user sees a list of possible values for the field.
- Trigger or button events -- invoked when a trigger field or "button" is activated. The purpose of a trigger or button event is to present a "trigger box" or to refresh a screen image. [See 12a.4.]
- Command events -- invoked when a particular command is issued. One use of command events is to present a "resolution box". These are also known as ON COMMAND events, referring to the protocol statement with which they are declared.
When you declare a choice, trigger, or button event, you also specify a "zone" where the relevant choice field, trigger field, or button is located on the screen. A particular screen might have several buttons or choice fields, each of which might activate its own event protocol step. The zone name links a particular event to the correct protocol step. [See 12a.3.]
First, let's see where events fit into the normal screen processing flow. Then the details of how events are declared in your code will be presented.
(A)
set status restart PERF PRISM SCREEN set status restart
or set status repeat | or set status repeat
-->>---------->> | <<----------------<<----------------<<----
| | |
| set status (B) | |
| reprompt or .OUT frame |
| redisplay | screen redisplayed (default) |
|----->>----->> | <<----------------<<--------------- |
| | | -or- |
| (C) | (D) f2=*Choices | |
if screen ---<<- prompt screen -->>-------------->> event proc
should display | | trigger/button executes
again, event | |
proc sets | (E) |
$status | OK, PREV, SEND,
| | YES, NO, DONE
| CANCEL |
| (bypasses |
| .IN) (F) |
| | .IN frame
| | |
| | |
| ---->> (G) |
| ON COMMAND event
| proc executes
------------<<-- (if coded) **
|
|
(H) |
return from screen
processing to
mainline code
(Letters in parentheses refer to notes on the next page.)
Notes on the diagram:
If an unexpected error happens in an event (such as a PERFORM PRISM syntax error) or if the event explicitly sets $STATUS to STOP or SYSERROR, Prism will terminate the entry transaction. An exception is that if an error occurs in a choice event, Prism will give a message "Error processing CHOICES command" but will not stop the transaction.
So what do you need to learn in order to add events and boxes to your application?
- Examples of Boxes [See 12a.5.1.]
- Standards and Guidelines for Boxes [See 12a.6.]
- How to Code Boxes [See 12a.7.]
- and the sections about the PERFORM PRISM commands that are primarily of use for boxes and events. [See 12a.8 and following.]
The DECLARE SCREEN section of your protocol lets you specify which protocol step should be executed when particular events occur.
* <protocol name> DECLARE SCREEN screen-id[, screen-id...] ON EVENT CHOICE IN ZONE [LIKE] zonename, PROC proto-step ON EVENT TRIGGER IN ZONE [LIKE] zonename, PROC proto-step ON EVENT BUTTON IN ZONE [LIKE] zonename, PROC proto-step ON COMMAND command-list, PROC proto-step ENDDECLARE ++label :
This DECLARE SCREEN section goes in whichever protocol is controlling the screen for which you are declaring events -- in an entry form protocol (when defining events or boxes for an entry form screen) or a report protocol (for an event on a report parm screen) or a file protocol (for an event on an initial parm screen when the file is selected).
The DECLARE section is shown here at the beginning of the protocol, before the first label, but it may occur anywhere in the protocol. Blank lines and comment lines, including control words like -$SUBJECT, may also occur in the DECLARE block.
ENDDECLARE signals the end of the DECLARE section of the protocol.
The DECLARE SCREEN section must be in the main, top-level protocol (the FILE or FORM/form-name or REPORT/report-name protocol). The event proc itself must be located in the same protocol that contains the PERFORM PRISM SCREEN command for the screen being declared. This might be a nested protocol, if your main protocol includes an XEQ FROM or "..protocol" command.
"Screen-id" here should match the "screen-id" or ID in the PERFORM PRISM command for the screen where the event occurs (e.g., the screen where the box will be generated). If several screens share the same event definitions, you may name multiple screen-ids in the DECLARE SCREEN statement.
Screen-ids are specified in the ID parm of PERFORM PRISM CHOOSE, ... PROMPT VALUE, ... PROMPT TEXT, ... ROUTE. For PERFORM PRISM SCREEN, there is both an ID option and the explicit "screen-id" (as in PERFORM PRISM SCREEN "screen-id"). If ID is present, that's the ID to use in DECLARE SCREEN; otherwise use "screen-id". [See 12.1.3.]
"Zonename" should match the name in your EVAL $ZONEDEF... Uproc in your input format. [See 12A.3.] If you include the LIKE option, Prism will do stem-matching against the "zonename" and will execute the named protocol step when an event happens in any zone whose name begins with the stem in "zonename". This is useful when you need to create a series of zones to invoke the same protocol code, e.g. multiple buttons for multiple occurrences of a field. [See 12A.4A for an example of this technique.] The $EVENTZONE variable will contain the exact zone name that triggered the current event.
The "command-list" after ON COMMAND can be a single command from this list: PREVIOUS, OK, SEND, CANCEL, YES, NO, DONE. Or several commands can be listed inside parentheses if the same protocol step applies to all.
DECLARE SCREEN screen-id ON COMMAND CANCEL, PROC proto-step ON COMMAND (OK,SEND) PROC proto-step ENDDECLARE
Note that this command list is not what determines which commands are enabled on the screen. That is determined by the commands listed in PERFORM PRISM SCREEN commands (or other PERFORM PRISM commands with similar options to enable commands on the screen). There are no cross-checks between commands you enable with PERFORM PRISM commands and commands you list here in the DECLARE SCREEN section.
And "proto-step" is the label of the protocol step that should be executed when the event occurs. [See 12a.1 for details about events and PERFORM PRISM SCREEN processing.]
It's the presence of an ON EVENT CHOICE... statement that causes Prism to enable the f2=*Choices key on the named screen.
And an ON EVENT BUTTON... statement causes Prism to create a button on the screen, as long as the corresponding EVAL $ZONEDEF Uproc to define the button's zone has been executed in your format.
The maximum number of nested events possible is 8. [See 12A.6.3 for an example of nested events.]
Prism allows a maximum of 160 declared "resources" per file select, 120 of which may be events. "Resources" include preloaded code (via the DECLARE PRELOAD statement), declared events, and also resources that Prism loads on your behalf (such as code needed for a routing application to work).
The ENDPROC=step-name option on PERFORM PRISM SCREEN is an alternative way to declare a protocol step to be executed for a "command event". However, it is more limited than the ON COMMAND declaration and is being phased out of Prism.
An ENDPROC step will be executed when OK, PREVIOUS, or SEND is issued by the user.
It's important to understand the difference between nested event steps and mainline flow-control statements. For example, in the code sample below, there are two places where the protocol specifies things to happen when the SEND command is issued:
DECLARE SCREEN INPUT1
ON COMMAND SEND, PROC VERIFY
ENDDECLARE
++START
PERFORM PRISM SCREEN INPUT1, OK, SEND='JUMP DONE'
PERFORM PRISM SCREEN INPUT2, SEND
:
++DONE
:
RETURN
++VERIFY
:
RETURN
The VERIFY step is a part of the internal processing of the screen. As a nested event, it allows screen REPROMPTs and REPEATs. The SEND='JUMP DONE' clause is simply a mainline statement to branch past an optional second screen. That JUMP executes after the screen has successfully completed processing, which includes any ON COMMAND procs. [See 12a.1.]
It would technically be possible to present a resolution box by means of protocol code in either the VERIFY event step, or the DONE step. However, your application must do more work if a box is presented as part of the mainline code rather than in an event step. When the box occurs in an event step, Prism automatically keeps the mainline (screen) level environment distinct from the box level code. CANCEL BOX is supplied as specified, and subareas are automatically discarded after the event. If the box occurs as part of mainline code, you must specify what happens as a result of a CANCEL BOX command. That is, you must use the CANCEL='command' option (e.g. on PERFORM PRISM CHOOSE or PERFORM PRISM PROMPT VALUE) to explicitly clear any subarea in effect and branch back to repeat the screen the user was on when the resolution box occurred.
In order to create a choice or trigger or button event, you must define "zones" on your entry screen in which the event will occur. Zones are created in the output frame of your input format, using the $ZONEDEF function. You refer to zones by name in the DECLARE SCREEN section of a protocol. [See 12A.2.]
You can also refer to stems of zone names. One use of this technique is when you want to define multiple zones for multiple occurrences of elements or structures, each of which might have an event associated with it. In this case, you might want to add an occurrence counter to the zone names that you create with $ZONEDEF. [See 12A.4A for a complete example of how to do this.]
Zones may also be used with the PERFORM PRISM COPY command, which provides a way to copy values to and from a screen image. [See 12a.14.]
The syntax of the $ZONEDEF function is:
$ZONEDEF(areaname, zonename, row, column, height, width)
Here is an example of how to use $ZONEDEF in a format label group:
LABEL = APPL.ID; ENTRY-UPROC = eval $zonedef($areaname,Appl.ID,6,4,1,48); TSTART = 6,4; TITLE = 'Application ID*'; GETELEM = APPL.ID; DEFAULT; LENGTH = 32; START = 6,20; PUTDATA;
Notice that a zone does not have to correspond to a data field. Here, a zone has been defined to encompass both the title and the field. This example illustrates a zone supporting a choices event. The user can have his cursor either on the title or within the field, and a choices event for "Application ID" will work. This code example matches up with the Prism screen example shown in full in 12A.5.1 and excerpted here:
....v....1....v....2....v....3....v....4....v....5....v....6....v....7 <- - - - - - - -Appl.ID zone - - - - - - - - - -> Application ID* _________________________________
The sample label group shown above also illustrates another item in the coding checklist for choice boxes. Notice that the label for the "Application ID" field includes an asterisk, to alert the user that choices are available. [See 12A.6.1 for more on labeling fields for choices.]
When you create zones for use on Prism screens, you are using SPIRES Device Services coding techniques. (Prism itself uses Device Services capabilities to create its full-screen interface.)
There are a few Device Services techniques that you may find useful in managing your Prism zones. They are summarized here, in the context of Prism coding, and are fully documented in the manual SPIRES Device Services.
While your code is executing in Prism, you might find it helpful to exit to SPIRES and issue the SHOW ZONES command. This command displays information about the zones currently defined. For example
YOUR RESPONSE: spires
:
-Type CONTINUE XEQ to resume
> show zones
DEFINE ZONE APPL.ID (1,48) ON GUIDED.INPUT (6,4)
(Here, GUIDED.INPUT is the value of $AREANAME and $SCRNAREA while this Prism code is executing in Guided Mode.) EXPLAIN SHOW ZONES in SPIRES for further information about this command.
Note that SHOW ZONES will sometimes include information about zones that Prism itself defines, as well as those defined by your application. In particular, when a choice box is generated, Prism defines zones for the input fields in the box. Zones that Prism defines have names that start with "$". You can refer to these zones in coding your event procs, just like zones that you define yourself. [See 12A.10.]
The $EVENTZONE variable holds the name of the zone that triggered the current event.
You can use the $GETAREA function to determine 1) the current row and column position of the user's cursor on the screen, and 2) which zone is associated with that particular location on the screen.
Why would you need to do this? If you have a series of trigger fields or buttons on the screen, all of which invoke the same code (e.g., for multiple occurrences of an element or structure), you might need to figure out which occurrence of the element you are dealing with. You could define separate zones for each occurrence, but this is awkward. An alternative is to define one larger zone encompassing all occurrences, and then use techniques described here to determine where the user is in the zone.
Here is a composite example; each statement is explained in the paragraphs following:
let CursorRow = $GetArea(CRT, CRow) let CursorCol = $GetArea(CRT, CCol) let ZoneNumber = $GetArea($ScrnArea, ZLOC, #CursorRow-2, #CursorCol) let ZoneName = $GetArea($ScrnArea, ZNAM, #ZoneNumber)
The first two statements determine the position of the cursor:
let CursorRow = $GetArea(CRT, CRow) let CursorCol = $GetArea(CRT, CCol)
The CRow and CCol options refer to the current row and column of the cursor within the uncontained CRT area. CRow is an absolute position, and includes the top two status lines on the Prism screen.
Then, using this cursor position information, you can find the zone number for this position on the screen area:
let ZoneNumber = $GetArea($ScrnArea, ZLOC, #CursorRow-2, #CursorCol)
(If no zone is found for that location, "0" is returned.)
This statement uses $SCRNAREA instead of CRT for the area name. $SCRNAREA is a SPIRES variable that is managed by Prism, that contains the name of the area currently active within the CRT area. (And $AREANAME is a variable available in formats, with the same information). Here is a graphic representation of these two areas:
------------------------------------ <---
| status line 1 | |
| status line 2 | |
|....................................| |
: : <--- |
: : | |
: the data area on a Prism screen : $SCRNAREA |the CRT area
: : $AREANAME |
: : | |
|....................................| <--- |
| message line | |
| options text | |
| function key list | |
------------------------------------ <---
Note that the #CursorRow variable was decremented by 2 to account for the two Prism status lines, since $SCRNAREA was used as the area name in this $GETAREA statement.
And you can use this zone number to determine the corresponding zone name:
let ZoneName = $GetArea($ScrnArea, ZNAM, #ZoneNumber)
For complete details about this function, type EXPLAIN $GETAREA in SPIRES.
Of course, you could combine all of these operations into one statement, if you wish:
let ZoneName = $GetArea($ScrnArea, ZNAM, $GetArea($ScrnArea, ZLOC, \ $GetArea(CRT, CRow)-2, $GetArea(CRT, CCol)))
As mentioned at the beginning of this section, zones are used with PERFORM PRISM COPY, which lets you read values from a zone, or write values to a zone. In some situations, when PERFORM PRISM COPY and zones don't meet your needs, you might need to use $GETAREA (and its companion function $PUTAREA) to read and write values directly. [See 12a.14 for an explanation of PERFORM PRISM COPY, 12a.14.1 for examples of using $GETAREA and $PUTAREA.]
A trigger field is a field on an input screen in which user input automatically triggers a change in the screen, without the OK, SEND, or PREVIOUS commands being issued.
What kind of change might occur on a screen when a trigger field is activated?
Several different techniques are possible for implementing trigger behavior on a screen:
- You might use formats processing entirely. This is likely if you want input into a trigger field to cause highlighting on the screen or to rewrite the screen with new data.
- You might use protocol processing entirely, in a trigger or button event. This is likely if you want to create a button that generates a trigger box on the screen.
- Or, as you might guess, you can use a combination of formats and protocol processing. You might need protocol control but also need to invoke your .OUT frame again to rewrite the screen.
A "button" is a trigger field with specific characteristics managed by Prism itself. It is a 1-character trigger field, displayed in reverse video with a "+" symbol inside the reverse-video block, and with a text label (that your application supplies) telling the user what will happen when the button is activated (e.g. "Type an "X" on this button to see a complete course description"). [See 12a.6.1 for guidelines for labeling buttons and trigger fields.]
Buttons were designed as the recommended presentation for trigger fields whose purpose is to provide a place where the user "clicks" to cause something (perhaps in a box) to happen.
To create a trigger field, define an input field with LENGTH of 1 to 10 and DISPLAY = TRIGGER. (An alternative, DISPLAY = WRAP, is possible for trigger fields longer than one character. See below for an explanation of the difference between these two options.)
LABEL;
:
LENGTH = 5; <--- LENGTH can be 1 to 10
START = 2,13;
:
UPROC = EVAL $ZONEDEF($AREANAME,zone-name,2,13,1,5);
:
DISPLAY = TRIGGER; <--- or DISPLAY = WRAP;
:
If the trigger field will be used to invoke a trigger event, you must define a zone to encompass the trigger field. That's what the EVAL $ZONEDEF statement above does. [See 12a.1, 12a.3.] Along with defining the trigger field in your format, your protocol supporting the entry screen must declare a "trigger event" and define a protocol step to execute during that event. Then, input into the trigger field will cause that code to execute, generating a box on the screen or otherwise changing the screen image. For example:
in your protocol: DECLARE SCREEN screen-id ON EVENT TRIGGER, IN ZONE zone-name, PROC proto-step ENDDECLARE
To create a button, define a 1-character zone in your input format. Then declare the button in the protocol supporting the screen.
in your output frame: LABEL; UPROC = EVAL $ZONEDEF($AREANAME,zone-name,row,column,1,1); in your protocol: DECLARE SCREEN screen-id ON EVENT BUTTON, IN ZONE zone-name, PROC proto-step ENDDECLARE
This coding causes Prism to know that the 1-character zone should be treated as a button. Prism generates the reverse-video block and the + sign inside the block. [See 12a.3 for more about defining zones.]
Note that the ON EVENT BUTTON... statement by itself does not cause Prism to create the button on the screen. Both the protocol statement and the zone definition have to happen in order for the button to display. One implication of this is that your format can include logic to bypass the zone definition, if you want a button to display in some circumstances but not others.
If the trigger field will be used for screen-refresh, you must include logic in your input frame to recognize input in a trigger field and cause something appropriate to happen on the screen.
Note that the discussion of "Details of Trigger Field Processing" below is generally not needed for trigger fields or buttons used for trigger boxes. The exception to this is if you come back to your main screen after a trigger box with a REPEAT or RESTART status (i.e. if you need to invoke your .OUT frame again). In that case, the details are relevant to your code.
For trigger fields longer than one character, there are two possibilities. First, you may define the field so that input into any character position causes the trigger to happen (DISPLAY = TRIGGER). Or you may use DISPLAY = WRAP to specify that the trigger shouldn't be activated until the last character position is changed.
If you know that a trigger field will always be completely filled in, you might choose to use DISPLAY = WRAP so that the "triggering" happens when the last character is changed. In other cases, DISPLAY = TRIGGER would be better. For example, you might want a 2-character trigger field, to accommodate input of numbers from 1 through 99. You want the trigger to cause highlighting of the item the user chooses. With DISPLAY = WRAP, the trigger would only be activated if a 2-digit number were typed (or if a single digit were typed into the last position in the field). With DISPLAY = TRIGGER, highlighting would happen even if a single number is typed in the first character position.
Trigger fields with DISPLAY = WRAP use the same mechanism as fields with automatic word-wrap. In both cases, model terminal code in the front-ends signals Prism that input has happened in a field with a WRAP attribute. The distinguishing factor is the length of the field. The current system assumes that a 1 to 10 character field on a single row with DISPLAY = WRAP is a trigger field. Any field 11 or more characters and taking more than 1 row (and with DISPLAY = WRAP) invokes the automatic word-wrap. Simple word-wrapping (and invocation of a trigger "event" for trigger boxes) is handled by Prism without involving any application code. Trigger field processing for screen-refresh involves a cycle of events described below.
Note that VTAM terminals (327x models) do not support trigger field processing at all. Currently, f12 is used as an explicit substitute.
Trigger processing is handled within PERFORM PRISM SCREEN and its associated format frames:
The user may have input data on the screen besides the value in the trigger field. When the trigger is processed, you want to respond to the trigger, but probably not do normal data edits. That is, when the screen is refreshed for the user, you wouldn't present the error codes that you might when you are processing an OK or SEND command.
To do this, you can process user-input data on a trigger screen via variables in order to bypass PUTELEMs and GETDATAs. For example:
Output: LABEL; <-- Non-trigger only
GETELEM = NAME;
DEFAULT;
UPROC = let Name = $CVal;
LABEL; <-- Both trigger and non-trigger
VALUE = #Name;
PUTDATA;
Input: LABEL; <-- Both trigger and non-trigger
GETDATA;
UPROC = let Name = $UVal;
LABEL; <-- Non-trigger only
VALUE = #Name;
PUTELEM = NAME;
Input in a trigger field causes frame.IN to execute with $ScrnStat = 'TRIGGER'. Frame.IN tests $ScrnStat for 'TRIGGER' and branches accordingly. The trigger-processing component of frame.IN must then instruct Prism to execute frame.OUT again by including the Uproc SET STATUS='REPEAT' or SET STATUS='RESTART'.
The difference between the statuses REPEAT and RESTART is the scope of UNDO: if $Status = 'REPEAT' when Prism starts to execute frame.OUT, UNDO will restore the screen to what it was just prior to trigger processing; if $Status = 'RESTART', UNDO will restore the screen to what it was when Prism first executed frame.OUT for the current PERFORM PRISM SCREEN.
For each non-trigger input field that has changed, be sure to update the corresponding variable with $UVal so that the user's latest input doesn't get "undone". The trigger field itself is a special case: update its variable or not depending on whether the triggering value should stay there when the screen is repainted.
As well as bypassing all PUTELEMs during trigger processing, be sure to bypass all inprocs and other edits. Otherwise, unexpected errors may pop up in response to a trigger processing. The only edits should be those that pertain to the trigger field itself.
Frame.OUT tests $ScrnStat for 'REPEAT' or 'RESTART' and branches accordingly.
By default, the cursor will appear in the next input field past the trigger field. If the trigger field was the last field on the screen, the cursor appears in the command line. To alter default cursor positioning, use one of the following uprocs:
set Parm = 'Cursor=(<row>,<column>)' <-- Cursor appears at
<row>,<column> if unprotected;
otherwise at the next
OR unprotected field
set Parm = 'Cursor=(COMMAND)' <-- Cursor appears on command line
.
$SCRNSTAT=REPROMPT <--- $STATUS=REPROMPT
/ /\
\/ \
+----------+ +-------------+ +------------+ $STATUS=''
-->| OUTPUT |------>| write/read |------>| INPUT |------->
| FRAME | | screen | | FRAME |
| | __\| | ___\| |__
| | / /| | / /| | \
+----------+ | +-------------+ / +------------+ |
/\ \ / \ / $SCRNSTAT=TRIGGER |
\ word-wrap trigger /
\ /
\ /
$SCRNSTAT=REPEAT <---------------- $STATUS=REPEAT
This section describes a technique to use stem-matching of zone names in order to refer to groups of zones in ON EVENT declarations. The most direct application of this technique is to support multiple buttons or trigger fields on an entry screen, in a situation where you have multiple occurrences of a field or structure, each of which needs to have a button or trigger field associated with it.
For example, the screen below is from the New Patients file, which is a demonstration application used to help teach people how to make Prism applications. The bottom half of the screen has a series of lines for multiple occurrences of a VISIT structure, with information about each visit this patient has made to the doctor. The "Code" is a trigger field; if you type a valid code in that space, the "Treatment Name" area is automatically updated with the code expansion.
=============================================================================
NEW Patients Entry Form: ADDUPD2 07/22/91 11:12 PEAK
Patient Demographic Data Record 5 of 9
-----------------------------------------------------------------------------
NAME: Programmer,_Ace_____ Type an 'X' to view/modify Notes... +
No notes for this record.
ADDRESS: 273_Silicon_Ave.____
Homebody,_IO_84501__
____________________
VISIT INFORMATION - To remove a visit, mark an X under '(Delete)'
No. (Delete) Date Code* Treatment Name Cost
-----------------------------------------------------------------------------
1) _ 05/13/83 E66 Eye strain relaxant ____$9.40
2) _ 02/20/84 X12 Shot in the arm ____$5.00
3) _ ________ ___ _________
4) _ ________ ___ _________
5) _ ________ ___ _________
6) _ ________ ___ _________
-Form continues on the next page
Type: OK below to continue to next page. Use CHOICES key for fields marked *
SEND to complete this transaction. CANCEL to cancel transaction.
YOUR RESPONSE:
f1=Help f2=*Choices f5=OK f6=Send f7=Undo f8=Cancel f0=Display
=============================================================================
Each trigger field needs to do the same work -- looking up the code in a table and copying the expansion onto the screen (using PERFORM PRISM COPY). A single proc can take care of this; the tricky part is keeping track of which VISIT occurrence you're dealing with.
First, here's the event declaration for this part of the screen:
declare screen scn1 on event trigger, in zone like treatmentcd, proc ev.copy.tname enddeclare
IN ZONE LIKE TREATMENTCD here means that the EV.COPY.TNAME proc will be executed when a trigger field is activated in any zone whose name starts out with "treatmentcd". [See 12A.2 to read about the DECLARE SCREEN section of a protocol.]
In the format for this screen, an indirect frame deals with the VISIT structure, generating the four input fields on each line (one line is one visit structure) and defining a zone for each "Code" field. Each "Code" zone has a name that includes the visit occurrence number as a suffix. (As SPIRES loops through the indirect frame, the visit occurrence counter is incremented by the format in the calling label group.)
The "Treatment Name" area is also given a zone name with an occurrence counter, since the protocol will be using PERFORM PRISM COPY to copy the code expansion into that zone. [See 12A.14.]
Here's what the SHOW ZONES command tells us (this is an excerpt):
> show zones DEFINE ZONE TREATMENTCD.0 (1,3) ON GUIDED.INPUT (15,30) DEFINE ZONE TREATMENTNM.0 (1,30) ON GUIDED.INPUT (15,37) DEFINE ZONE TREATMENTCD.1 (1,3) ON GUIDED.INPUT (16,30) DEFINE ZONE TREATMENTNM.1 (1,30) ON GUIDED.INPUT (16,37) DEFINE ZONE TREATMENTCD.2 (1,3) ON GUIDED.INPUT (17,30) DEFINE ZONE TREATMENTNM.2 (1,30) ON GUIDED.INPUT (17,37) DEFINE ZONE TREATMENTCD.3 (1,3) ON GUIDED.INPUT (18,30) DEFINE ZONE TREATMENTNM.3 (1,30) ON GUIDED.INPUT (18,37) etc.
And here are the label groups in the format that create the zones for "Code" and "Treatment Name": [See 12A.3 to read about defining zones.]
LABEL = TREATMENT.CODE;
COMMENTS = The Treatment Code field has a display attribute of
TRIGGER so that changing the part of the code will cause the Treatment
Name field to be updated. The updating of the Treatment name field is
done in the protocol in proc EV.COPY.TNAME;
GETELEM = TCODE;
DEFAULT;
LENGTH = 3;
START = *,30;
UPROC = Eval $ZoneDef($AreaName, TreatmentCd.#VisitOcc, $CRow, 30,
1, 3);
UPROC = Eval $ZoneDef($AreaName, TreatmentEr.#VisitOcc, $CRow, 27,
1, 2);
DISPLAY = OPTIONAL,TRIGGER;
PUTDATA;
LABEL = TREATMENT.NAME;
COMMENTS = Treatment Name is changed in the protocol in a TRIGGER
event if the user types in a code, or in a CHOICE event if s/he
selects a treatment code from a list.;
GETELEM = TNAME;
DEFAULT;
LENGTH = 30;
START = *,37;
UPROC = Eval $ZoneDef($AreaName, TreatmentNm.#VisitOcc, $CRow, 37,
1, 30);
DISPLAY = DATA;
PUTDATA;
Here is the EV.COPY.TNAME proc that does the work of looking up the code and copying the expansion into the correct line:
++ev.copy.tname
;---- This proc is invoked by any keystroke in the "Code"
;---- trigger field (the TreatmentCode.<n> zone).
;---- $FieldVal contains the value entered in the trigger field.
let xTreatmentName = $looksubf($cap($FieldVal), replace, \
'Prism NewPatntLink', TName)
let xTreatmentNameZ = 'TREATMENTNM.' || \
$rsub($EventZone, 'TREATMENTCD.')
/perform prism copy var xTreatmentName to zone #xTreatmentNameZ
return
Note that this proc uses the $EventZone variable to determine exactly which zone (which trigger field) has been triggered in the current event.
If you would like to see the complete format or protocols code for this screen, or if you have questions about the techniqes illustrated here, contact Peter Tuttle.
Most of the rest of this chapter describes the use of on-screen "boxes" -- an adjunct to normal screen presentation in which new fields or information are displayed in a box that overlays part of the screen, in response to some event on that screen.
There are three types of boxes, corresponding to three ways in which they are invoked:
Boxes appear on top of a screen image, and the background screen is disabled. Part of the box paradigm is the ability to return to that background screen, either optionally or implicitly as a natural result of finishing an interaction with the box. Choice and trigger boxes always take the user back to the original screen, while resolution boxes should allow the user to continue to the next screen if the conflict can be resolved, or to return to the original screen for other actions.
Function key labels appear inside a box, to remind the user of the navigation commands available. At the same time, all of the normal function labels at the bottom of the screen are disabled and dimmed by Prism, except for f1=Help, which is always available.
Boxes on Prism screens are similar to dialog boxes on a Macintosh. Some of the standards and guidelines recommended here for format and placement of boxes, and navigation between the box and the main screen are meant to reinforce this image for users.
Prism provides tools to define the size and placement of a box, as well as tools to easily place in a box a choice list, text, or a simple input field. You may also use PERFORM PRISM SCREEN and a format to provide the contents of a box.
Here is an example of a screen on which the f2=*Choices key is enabled. Two fields on this screen -- "Application ID" and "Reported Incident Type" -- are labeled with an asterisk, indicating that the CHOICES command is available to provide assistance for those fields.
Prism enables the f2=*Choices key on any screen for which a choices "event" is defined in the supporting protocol. It is up to your application code to define those choices events (i.e. what should be shown to the user when f2=*Choices is pressed and where the box should be drawn on the screen) and also to include an asterisk in the applicable field labels on the input screen. [See 12A.2 for how to define a choices event, 12A.6.1 for standards for labeling input fields.]
XSAQA Incidents Entry Form: INCIDENT 08/07/90 16:20
INCIDENT INFORMATION
--------------------------------------------------------------------------
Incident No.: 100239 Incident Date: 08/07/90
JES2 Job No.: ____ Job Time (HHMM): ____ Number of Retries: ___
Application ID* ________________________________
Reported Incident Type* ___
Reported By: Jimmie Burgess
Contacted* ________________________________________
-------------------------- Incident Description --------------------------
__________________________________________________________________________
__________________________________________________________________________
__________________________________________________________________________
__________________________________________________________________________
__________________________________________________________________________
Type: OK below to continue to next page. CANCEL to cancel transaction.
Use CHOICES key for fields marked *. UNDO to discard changes to page.
YOUR RESPONSE:
f1=Help f2=*Choices f5=OK f7=Undo f8=Cancel
Here is what happens when the user places the cursor in the "Application ID" field and presses f2=*Choices. Note that the choices box is placed in close proximity to the field to which it applies. You determine how big the box is and where it is placed, as well as what values are listed as choices. (Prism automatically provides the "paging" mechanism for long lists that don't fit in one page of the box.) You also control the wording of the explanatory text in the box.
XSAQA Incidents Entry Form: INCIDENT 08/07/90 16:20
INCIDENT INFORMATION
--------------------------------------------------------------------------
Incident No.: 100239 Incident Date: 08/07/90
JES2 Job No.: ____ Job Time (HHMM): ____ Number of Retries: ___
Application ID* ________________________________
*--------------------------------------------------------------*
Repo| __ <-- Choose one from the list below. |
Repo| 1. ADMUTD, SSA DAILY AND RELATED FILES |
Co| 2. ADMUTN, AIS-SSA Communication Programs |
| 3. ADMUTP, PMT Processing Program |
-------| 4. ADMUTS, SSA SUPPORTED COMPONENTS | --
_______| 5. ADMUTU, USER STAGING PROGRAMS | __
_______| 6. AUTOSAQA, AutoSAQA online | __
_______| (No. 1-6 of 50) | __
_______| f3=Done f5=OK f9=Cancel Box | __
_______*--------------------------------------------------------------* __
Type: OK to continue forward. CANCEL BOX to cancel box.
DONE to leave this box.
YOUR RESPONSE:
f1=Help f2=*Choices f5=OK f7=Undo f8=Cancel
When the user picks an item from the list and presses f3=Done, the value from the list is automatically copied back into the entry field on the main screen and the box is "closed", returning the user to the screen from which the f2=*Choices command was issued. You have control over exactly what is copied back onto the main screen.
The example above illustrates a choice box asking for a single choice; you may also provide a list where multiple choices are possible. You also can use the value of the $FIELDVAL variable (which contains any value the user may have typed in the input field before pressing f2=*Choices) to limit the scope of the list in the box. These features and other details of choice boxes are explained in a later section. [See 12A.7.]
Below is an example of a screen that employs a trigger box. To implement a trigger box, you would code a trigger field on your input screen and label it so that it's clear to the user what to do. And in the protocol code for this screen, you would define the placement and contents of the box that will be drawn on the screen in response to the trigger field. [See 12A.4 to learn how to code trigger fields, 12A.6.1 for guidelines for use and labeling of trigger fields.]
Here is the sample screen with a trigger field (the "Add Component->" field).
XSAQA Applications Entry Form: APPLICATION 08/09/90 08:45
APPLICATION COMPONENTS
-----------------------------------------------------------------------------
To add a component description to TAPELOAD, mark the ADD button. To modify a
component description, mark the button next to the appropriate ID.
Modify Component ID Component Name (or Type)
Add Component-> _ Borrow Component-> _
_ 1. LOADING.ROUTINE (Submit Job)
_ 2. MARC.CONVERSION (SPIRES Format)
_ 3. TAPE.BACKUP (Submit Job)
-Form continues on the next page
Type: OK below to continue to next page. PREVIOUS to return to prior page.
SEND to complete this transaction. CANCEL to cancel transaction.
YOUR RESPONSE:
f1=Help f4=Previous f5=OK f6=Send f7=Undo f8=Cancel
When the user types a value in the trigger field, the box is drawn on the screen. Note that neither OK nor SEND is required to cause the screen to be rewritten, but simply input into the trigger field.
Here is the screen with the trigger box drawn.
XSAQA Applications Entry Form: APPLICATION 08/09/90 08:45
APPLICATION COMPONENTS
-----------------------------------------------------------------------------
To add a component description to TAPELOAD, mark the ADD button. To modify a
component description, mark the button next to the appropriate ID.
Modify Component ID Component Name (or Type)
*------------------------------------------------------------------------*
_| Component ID: ________________________________ |
_| Component Name: __________________________________________________ |
_| Component Type* __ |
| |
| ----------------------- Component Description ----------------------- |
| ____________________________________________________________________ |
| ____________________________________________________________________ |
| ____________________________________________________________________ |
| ____________________________________________________________________ |
| ____________________________________________________________________ |
| f2=*Choices f3=Done f9=Cancel Box |
*------------------------------------------------------------------------*
Type: DONE to leave this box. Use CHOICES key for fields marked *.
CANCEL BOX to cancel box.
YOUR RESPONSE:
f1=Help f4=Previous f5=OK f6=Send f7=Undo f8=Cancel
As in the earlier example of a choices box, f3=Done takes the user back to the main screen after the box is filled in. (Or if he starts filling out the box and changes his mind, f9 will cancel the box and return to the main screen.)
Note that this box itself has a field for which f2=*Choices is enabled; this illustrates how you can provide "nested" boxes when appropriate. Here is the screen after f2=*Choices is used for the "Component Type" field.
XSAQA Applications Entry Form: APPLICATION 08/09/90 08:46
-----------------------------------------------------------------------------
To add a component description to TAPELOAD, mark the ADD button. To modify a
component description, mark the button next to the appropriate ID.
Modify Component ID Component Name (or Type)
*------------------------------------------------------------------------*
_| Component ID: archive_________________________ |
_| Component Name: Archive tape *--------------------------------------*
_| Component Type* __ | __ <-- Choose one from the list |
| | below. |
| ----------------------- Componen| 1. SPIRES Component (%) |
| ________________________________| 2. SPIRES File Definer (%D) |
| ________________________________| 3. SPIRES File Definition (%F) |
| ________________________________| 4. SPIRES Format (%G) |
| ________________________________| 5. SPIRES Protocol (%P) |
| ________________________________| 6. SPIRES Record Definition (%R) |
| f2=*Choices f3=Done f| (No. 1-6 of 57) |
*---------------------------------| f3=Done f5=OK f9=Cancel Box |
*--------------------------------------*
Type: OK to continue forward. CANCEL BOX to cancel box.
DONE to leave this box.
YOUR RESPONSE:
f1=Help f4=Previous f5=OK f6=Send f7=Undo f8=Cancel
Below are some examples of resolution boxes. Resolution boxes are used when you detect a condition needing some resolution while processing a user's OK, PREVIOUS, SEND, or CANCEL command, and the resolution can be handled most naturally and effectively by a box interaction rather than flashing error codes on the screen. [See 12A.6 for further guidelines.]
Here is an example of how a resolution box might be used. The (abbreviated) sample screen below lets the user specify a delivery method. Some of those methods require a small additional bit of information, which could be requested in a resolution box at the time the user issues an OK or SEND command.
SNAP Entry Form: CHECK REQUEST 08/09/90 09:24
-----------------------------------------------------------------------------
Check Amount: _______________
:
Payee SSN: ___________
Payee Name: __________________________________
:
:
:
:
Send by: _ I(D Mail), U(S Mail), W(ill Call), C(ourier)
:
Type: OK below to continue to next page. PREVIOUS to return to prior page.
SEND to complete this transaction. CANCEL to cancel transaction.
YOUR RESPONSE:
f1=Help f4=Previous f5=OK f6=Send f7=Undo f8=Cancel
If the user specifies delivery by ID mail, this resolution box would appear:
SNAP Entry Form: CHECK REQUEST 08/09/90 09:24
-----------------------------------------------------------------------------
*------------------------------------------*
Check Amount: ___________| ID Mail Address |
: | |
Payee SSN: ___________| In care of: __________________________ |
Payee Name: ___________| Department: __________________________ |
: | Address: __________________________ |
: | __________________________ |
: | f5=OK f9=Cancel Box |
: *------------------------------------------*
Send by: _ I(D Mail), U(S Mail), W(ill Call), C(ourier)
:
Type: OK to continue forward.
CANCEL BOX to cancel box.
YOUR RESPONSE:
f1=Help f4=Previous f5=OK f6=Send f7=Undo f8=Cancel
After the user fills in the box and issues the OK command, his previous command (OK or SEND) would be processed and the transaction would continue as usual.
Another example, already common in Prism routing applications, is the "name resolution box" that is shown when you enter a non-unique name on an identification screen. Here is an example:
Forms Action Search 08/09/90 09:18
-----------------------------------------------------------------------------
Enter your name or University ID:
j_williams______________________
Acting for: ________________________________
*-----------------------------------------------------------------*
| There are 4 names like J WILLIAMS. |
| | .
| _ <-- Choose a name by entering a number from the list below. |
| 1. Williams, Jane H |
| 2. Williams, Jo Ellen | g.
| 3. Williams, Joann |
| 4. Williams, Marli J |
| f5=OK f9=Cancel Box |
*-----------------------------------------------------------------*
Type OK to continue forward.
Type CANCEL BOX to cancel box.
YOUR RESPONSE:
f1=Help f5=OK f7=Undo f8=Cancel
The commands to navigate through a resolution box are different than for choice and trigger boxes. The reason for the difference is that the character of the interactions is somewhat different. Both choice and trigger boxes result from an explicit request from the user, while resolution boxes result from an application detecting a condition needing resolution.
The commands offered in a resolution box are OK (to continue forward with the process that was interrupted, once the conflict is resolved) or CANCEL BOX (to discard the box and return to the prior screen to change the data that caused the conflict). An OK from a resolution box causes the user's initial command (OK, PREVIOUS, SEND, or CANCEL) to be processed.
DONE and CANCEL BOX are offered instead on choice and trigger boxes, to signal that the user has finished with the box interaction and is ready to return to the main screen (DONE) or that he has changed his mind about using the box (CANCEL BOX).
[See 12A.6.2 for more on navigation commands.]
Confirmation boxes are a special category of resolution boxes, where the resolution can be expressed as a simple yes/no choice by the user. In this case, f4=No and f5=Yes are the commands offered in the box. In keeping with the intended purpose of Yes-No boxes, you should not provide data entry fields, but use it only to present the question and the yes/no choice.
Consider XSETUP FIELDS, with which you can remove a reporting field defined for your application. Rather than simply putting a warning error code on the screen if you attempt to remove a field that is currently in use in a Personal Report, the application could provide some explanatory text in a confirmation box and ask whether the field should really be removed or not:
United States XSetup Field 08/09/90 09:24
STATES: Field FLOWER
-----------------------------------------------------------------------------
To remove, enter 'R': r
NAME of field DESCRIPTION of this field
FLOWER________ State flower__________________________________
Enter an 'X' next to the Prism processes in which this field is available.
X REPORTING _ FILTERING _ SORTING
* --------------------------------------------------------------*
| Warning -- This field is in use in Personal Report(s). |
| Before removing the field, run the CHECK FIELDS report in |
| Prism Profile to see where it is used. Type HELP CHECK |
| FIELDS for further details. |
| Do you still want to remove the field? |
| f4=No f5=Yes |
* --------------------------------------------------------------*
Indicate all accounts, groups, or access lists that may use this field:
PUBLIC___________________________________________________________________
_________________________________________________________________________
_________________________________________________________________________
Type NO to keep the field.
Type YES to remove the field.
YOUR RESPONSE:
f1=Help f5=OK f6=Send f7=Undo f8=Cancel
Here, an f4=No command would presumably return the user to the screen from which he came, so that the remove request could be blanked out. And f5=Yes would proceed to process the original command (OK or SEND) that the user issued.
As application developers begin to implement boxes in production applications, we hope to share examples, problems, and solutions, and come up with standards and guidelines for the use of boxes. Following the guidelines will help the Prism user community see boxes as a coherent part of the Prism interface.
The guidelines and examples in the following sections will continue to evolve as discussions about boxes continue.
If you have questions or ideas to share, contact Lynn McRae (gq.ltm) or use the SUGGEST command in Prism.
The standard way to mark a field for which choices are available is to add an asterisk to the field label. The f2=*Choices function key label also includes an asterisk; the idea is that the user will be able to make a conceptual link between the function key and the fields with asterisks.
The asterisk should be placed near the start of the input field to which it applies. When the field title is in front of the input area, replace the colon with an asterisk. This will place the asterisk close to the input area. If the field title ends with a question mark (or other punctuation mark that can't be omitted) put the asterisk after the punctuation mark.
Application ID: __________ becomes Application ID* __________ <-- Which department do you want? _____ becomes Which department do you want?* _____ <--
If the input area is on the line below the field title, put the asterisk at the front of the input area:
Which GL codes do you want to include in your report? ______________________________________________________ becomes --> Which GL codes do you want to include in your report? * _____________________________________________________
For column headings, put the asterisk at the beginning of the first line of the heading:
GL codes becomes --> *GL codes or maybe --> *GL _____ _____ codes _____ _____ _____ _____ _____ _____
If space considerations on your screen will allow, we recommend that you follow these guidelines, so that users will see consistent labels from application to application for fields where f2=*Choices works.
Buttons or trigger fields that will generate a box on the screen should be labeled clearly to let the user know the purpose of the field. Buttons (rather than plain trigger fields) are the recommended signal to present when you are providing a place where the user should mark a field to cause something to happen. [See 12a.4 for a discussion of trigger fields and buttons.]
One good method is to use a sentence or phrase indicating both the action ("Type an X...") and effect ("...to add a comment") and to point to the button with an arrow. For example:
+ <-- Type an "X" to add a comment. + <-- Type an "X" on this button to add a comment.
Alternatively, if the label needs to be placed to the left of the button:
To add a comment, type an "X": + To add a comment, type an "X" on this button: +
This type of label might appear above a column of trigger fields or buttons:
Type an "X" next to each item you want to review: _ 1. ABC _ 2. DEF _ 3. GHI
Ideally, the instructions for a trigger field should be as close as possible to the trigger field itself.
It's preferable to let any character trigger the trigger field, rather than requiring an X, for example.
And the trigger should be blanked out when you return to the main screen after presenting the trigger box. You can do this with the command SET FIELDVAL " " in your trigger event protocol step. If you create a button, Prism itself will take care of presenting the button image before, during, and after activation.
The earlier section illustrating the different types of boxes referred to the navigation commands used to move between the main screen and a box. [See 12A.5.1.] This section summarizes the recommended presentation of function key commands in different situations.
Command presentation is under your application's control, via options on your PERFORM PRISM commands, and you should follow the guidelines here in deciding which commands to enable. [See 12a.7 for coding details.]
Note that it is the ON EVENT CHOICE statement in a protocol that enables the f2=*Choices function key on a screen.
DONE and CANCEL BOX are the primary navigation commands for boxes presented during choice and trigger events. Include DONE and CANCEL options on your PERFORM command to enable those function keys. [See 12a.1 for a definition of "events".]
These are the commands with which the user says that he is finished with the box interaction (DONE) or that he wants to simply discard the box (CANCEL BOX). Both commands take the user back to the main screen.
OK and PREVIOUS are automatically supplied in PERFORM PRISM CHOOSE lists when needed for scrolling through a long list. No option is required on your PERFORM PRISM CHOOSE command to enable OK and PREVIOUS for scrolling in this situation.
You may explicitly supply OK and PREVIOUS if needed to move between successive pages of a box; otherwise don't enable those commands. [See 12a.6.3 for more on multi-page boxes.]
SEND is never appropriate in a choice or trigger event, and Prism ignores it if included on your PERFORM command.
OK and CANCEL BOX are the commands to navigate through a resolution box. Include OK and CANCEL options on your PERFORM command to enable those function keys.
OK is the command with which the user says that he is finished with the resolution box and wants to proceed with the command he issued earlier. CANCEL BOX signals that the user wants to return to the main screen from which that command was issued.
SEND is never appropriate in a resolution box, and Prism ignores it if included on your PERFORM PRISM command.
Don't enable the DONE command in a resolution box; it is not appropriate. You may explicitly supply PREVIOUS if needed to move between successive pages of a box; otherwise don't enable it. That is, don't enable PREVIOUS as a paging command to move back to the original screen, since CANCEL BOX is intended to serve that function.
Why is there a difference between resolution boxes and choice/trigger boxes in the navigation commands recommended and/or allowed? The choice and trigger boxes introduce a new navigation model into Prism, distinct from the normal screen navigation using OK and PREVIOUS. You can think of it as a "nesting model" rather than a "paging model". With a choice/trigger box, the user is "nesting" to a detour, on demand, and is then specifying when the detour is done (with DONE). In contrast, the resolution box appears not on request by the user, but on the application's decision, so the user is led forward with the normal paging command of OK, continuing the same paging model as on the main screens.
Confirmation boxes are a special case. Their purpose is to present a yes/no question in a resolution box situation. Therefore, NO and YES are the appropriate navigation commands here -- include NO and YES options on your PERFORM command and don't enable the other commands.
Choice, trigger, and resolution boxes that are text-only (i.e. generated with PERFORM PRISM PROMPT TEXT or PERFORM PRISM SCREEN...PROTECT) only require one navigation command, in general -- DONE or OK is sufficient and CANCEL should not be enabled.
Here is a chart summarizing the recommendations in preceding paragraphs:
*PREVIOUS *OK DONE CANCEL YES NO
-----------------------------------------------
Choice box x x supply supply x x
Choice box, text-only ** x x supply x x x
Trigger box x x supply supply x x
Trigger box, text-only x x supply x x x
Resolution box x supply x supply x x
Resolution box, text-only x supply x x x x
Confirmation box x x x x supply supply
--------------------------------------------------------------------------
"supply" - means you should enable the command by including an option
on your PERFORM command
"x" - means you should not enable the command
Notes:
* PREVIOUS and OK are supplied automatically by Prism when needed
for scrolling in choice lists.
You should enable PREVIOUS if needed in a multi-page box. Enable
OK instead of DONE on the first page of a multi-page choice
or trigger box. That is, use OK for paging, and DONE to
return to the main screen after the event is finished.
** A "text-only choice box" is not likely, but you might imagine
a situation where the usual response to f2=*Choices is a choice
list, but in some exceptional circumstance you need to present
text explaining why a choice is not available this time.
Note that a CANCEL option on a PERFORM command causes either f8=Cancel or f9=Cancel Box to be enabled, depending on whether the PERFORM is presenting data on a screen or in a box, respectively.
The PERFORM commands discussed in this chapter are useful primarily in boxes, but it is also possible to use them at a screen level (PERFORM PRISM CHOOSE is the most likely of these commands to be useful on a screen, as things stand now). At the screen level, normal navigation rules apply:
- DONE, YES, and NO are not applicable, so are ignored.
- SEND is not applicable on parm screens, so is ignored; you must enable it on entry form screens.
- CANCEL is automatically supplied on parm and entry form screens.
- OK is automatically supplied on parm screens; you must enable it on entry form screens.
- You must enable PREVIOUS on parm screens and entry form screens.
During an event proc, you may use the "PERFORM PRISM DISABLE (or ENABLE) pfkey" command to disable or enable commands (function keys) when the parent screen is shown again after the event. [See 12a.16.]
A PERFORM PRISM CHOOSE list in a choice box (event) is circular until the DONE command is issued. That is, OK takes you to the next part of the list even if you've filled in a choice. If you're looking at the last part of the list, OK takes you back to the beginning. DONE is what takes you back to the main screen.
A PERFORM PRISM CHOOSE list in a resolution box (in an ON COMMAND event) or at the screen level is circular until you've made a choice, since DONE should not be present in a resolution box, according to current guidelines. Once you've made a choice, OK moves you forward out of the resolution box. One implication of this is that for a CHOOSE MULTIPLE list in a resolution box, once you've made at least one choice, you can't circle back to the first part of the list again. Once you've made a choice, OK at the end takes you forward out of the resolution box.
Boxes are an ancillary screen tool, generally relating to individual screens, and should not be used as a substitute for screen-to-screen navigation. In general, think of boxes as an optional or exceptional detour from the main processing flow, rather than a required step in a transaction. Don't nest into major portions of a transaction in boxes -- that's more appropriate for separate screens.
Boxes should provide a simple interaction directed toward a single purpose. The sequence of events within a box should not be so complicated as to bring about some of the same difficult navigation problems that complex cycles of optional screens do at the screen level -- the kinds of problems that boxes themselves were introduced to solve.
Here are some general guidelines, in no particular order:
Choice boxes are the most straightforward of the three types. Their purpose is to present a list of choices for the user. Their primary use is to help the user fill in an entry field by presenting possible values to choose from.
A choice event (i.e., what happens in response to the f2=*Choices key) must include the presentation of a choice list. You might decide to have an intervening prompt to ask a question of a user before presenting the list, but the main point of a choice event is the list of choices.
You might also imagine a situation where some condition on the main screen causes no choices to be applicable. You could code your protocol so that the response to f2=*Choices in this case is to present text explaining the situation (e.g. because of what you entered in field XYZ, none of the choices that are normally relevant for this field are applicable). This would be a case where no choice list is presented, because of exceptional circumstances, but it still follows the "spirit" of a choice box.
You might implement a trigger box to provide a detailed display for something that's summarized on the main screen (e.g., a full course description for a course listed by title). Adding comments or doing "table maintenance" activities are also candidates for trigger boxes. Keep in mind that a general goal is to use boxes for "optional" activities, and not as a substitute for screen navigation.
Consider a case where a screen is filled in, but based on some value the user gave, you need a small extra bit of information. For example, the user indicated they want delivery by ID mail, and now you need to prompt for an ID mail address. A resolution box here is a good alternative to an extra screen for a small amount of extra input.
Or you might be able to design a screen with boxes to avoid making the user tab through many fields that are likely to be used rarely (only needed in certain situations). That is, rather than providing spaces on a screen for every possible condition, ask questions to define the conditions, then present a box for the extra input needed for that condition.
For inter-element or consistency edits, it might be preferable to use a resolution box to present an error explanation instead of standard error codes. A resolution box could present the data that needs resolution and give the user a chance to change one or the other of the values.
Confirmation boxes are a special category of resolution boxes, where the resolution can be expressed as a simple yes/no choice by the user. In this type of box, you would offer f4=No and f5=Yes as the available "navigation" commands. The question you ask in the box should clearly state what the 2 choices are and what will happen as a result of a "No" or "Yes" response.
Confirmation boxes are most useful for a single-panel "alert"-style box. For example, you might provide a warning if the user issues a CANCEL command after a long and complex transaction (perhaps after a certain threshold that you keep track of). The confirmation box could ask whether the user really intends to cancel the transaction.
It is possible to generate "nested boxes". "Nested boxes" means having more than one box visible on the screen at once, as in this example of a trigger box that itself might have a choice box overlaid on top. [See 12a.5.1 for the original presentation of this example.] With nested boxes, you have to discard one box after another in order to get back to the main screen.
XSAQA Applications Entry Form: APPLICATION 08/09/90 08:46
-----------------------------------------------------------------------------
To add a component description to TAPELOAD, mark the ADD button. To modify a
component description, mark the button next to the appropriate ID.
Modify Component ID Component Name (or Type)
*------------------------------------------------------------------------*
_| Component ID: archive_________________________ |
_| Component Name: Archive tape *--------------------------------------*
_| Component Type* __ | __ <-- Choose one from the list |
| | below. |
| ----------------------- Componen| 1. SPIRES Component (%) |
| ________________________________| 2. SPIRES File Definer (%D) |
| ________________________________| 3. SPIRES File Definition (%F) |
| ________________________________| 4. SPIRES Format (%G) |
| ________________________________| 5. SPIRES Protocol (%P) |
| ________________________________| 6. SPIRES Record Definition (%R) |
| f2=*Choices f3=Done f| (No. 1-6 of 57) |
*---------------------------------| f3=Done f5=OK f9=Cancel Box |
*--------------------------------------*
Type: OK to continue forward. CANCEL BOX to cancel box.
DONE to leave this box.
YOUR RESPONSE:
f1=Help f4=Previous f5=OK f6=Send f7=Undo f8=Cancel
Since the first, base box may have a screen-id, it can be declared as a screen on which other events may happen. For example:
declare screen main <-- main screen on event trigger, in zone comp.id, proc ev.trigger.id enddeclare declare screen comp.id <-- 1st box on event choices, in zone comp.type, proc ev.choice.type enddeclare ++main perform prism screen main ... ... [code to generate the main background screen] ++ev.trigger.id perform prism screen comp.id ... ... [code to generate 1st box, in response to a trigger event] ++ev.choice.type perform prism choose ... ... [code to generate 2nd box, in response to choices event in 1st box]
A general recommendation is that you use nested boxes only to offer f2=*Choices within a trigger or resolution box (although other permutations are technically possible). The maximum number of nested events is 8.
Within one choice, trigger, or resolution protocol step, it is only possible to define one subarea (box) at a time. [See 12a.9.] Within that subarea, you could provide multiple "pages". For example, you might first prompt for a value and then (after the user issues an OK command) present a list of choices related to that value somehow. This would be accomplished with (at least) two PERFORM commands, but both steps should occur in the same subarea. In other words, it is undesirable to move the location of the box or change its size for the successive pages (steps) of the interaction. The only exception is a box that might shrink or expand vertically to accommodate a varying size list.
Follow the guidelines given earlier for navigation commands for the different types of boxes. [See 12a.6.2.] In addition, you should enable OK and PREVIOUS as paging commands within a multi-page box (that is, between the pages within the box). Don't, however, enable PREVIOUS on the first page of a box, since DONE and CANCEL BOX are the standard ways to go back to the main screen from the beginning of a box.
Boxes happen in response to "events" as described earlier. [See 12a.1.] The event might be the user pressing the f2=*Choices key (for a choice event/box) or entering a value in a trigger or button field (for a trigger box in a trigger or button event) or issuing a particular command (for a resolution box in an ON COMMAND event).
An event invokes a separate protocol processing step that does the work of generating the box. Events are defined in a DECLARE SCREEN section of the protocol supporting the screen. [See 12a.2.]
An event step executes between the output and input frames of PERFORM PRISM SCREEN processing. Though they are embedded in screen processing, it's appropriate to think of their logic as independent of the main screen flow. [See 12a.1.]
Since an entry form installed with automatic control generally would not have a supporting protocol, and because boxes require protocol code, for all intents and purposes, boxes are not possible in automatic entry forms.
Here is a summary checklist of the steps in coding a choice box:
Here is a summary checklist of the steps in coding a trigger box (the steps are very similar to those for choice boxes):
Here is a summary checklist of the steps in coding a resolution box:
For choice and trigger boxes, the ON EVENT... statement defines which protocol step is executed to generate the box in response to the f2=*Choices key or input into the trigger field or button. For resolution boxes, the ON COMMAND... statement names the protocol step. For example:
* form/incident
declare screen incident
on event choice in zone appl.id, proc lookup.apl
on command send, proc warning
enddeclare
:
++lookup.apl
<code to generate the choices box>
:
++warning
<code to generate the resolution box>
Your protocol step can be as short or as complex as required to support a given function. It has access to all PERFORM commands, although some, like those related to searching, would presumably make no sense in this context.
A protocol step for an event may perform many different tasks, but any interaction with the user should be via boxes, since events define a form of secondary processing within the screen. (In fact, you will get an error when your protocol is executed if in an event step you try to generate a screen image that is not contained in a subarea.)
Note that the ENDPROC option on PERFORM PRISM SCREEN is an alternative to the ON COMMAND statement to declare a protocol step to execute during a "command" event. However, ENDPROC is being phased out. [See 12a.2 for details about ENDPROC processing.]
The primary tools that Prism provides to generate boxes are:
If needed as an alternative to the pre-packaged tools listed above, you may use PERFORM PRISM SCREEN to invoke a format to present data in a box. This would require writing additional format frames, with dimensions customized to fit in your box. These frames would go in your input format (for a box on an entry form screen) or report format (for a box on a parm screen for a report) or display format (for a box on a parm screen at file-selection).
PERFORM PRISM SET SUBAREA defines the size and placement of a choice, trigger, or resolution box. It establishes a rectangular area within the main data area (or any current subarea) in which future screen interactions will take place for the remainder of the current processing step, or until a ...CLEAR SUBAREA or another ...SET SUBAREA command occurs.
Subareas are automatically cleared after leaving the event. But for tidiness' sake, your protocol step could include a PERFORM PRISM CLEAR SUBAREA command before RETURN.
PERFORM PRISM SET SUBAREA height BY width AT [RELATIVE | ABSOLUTE] row, col and PERFORM PRISM CLEAR SUBAREA
"Height" can be a positive integer, for a box of fixed height, or 0 for a box of variable height. "Width" is a positive integer indicating a fixed width for the box.
A variable height box is valid only for PERFORM PRISM CHOOSE, PERFORM PRISM PROMPT TEXT, and PERFORM PRISM PROMPT VALUE. By specifying variable height with PERFORM PRISM CHOOSE, Prism will use as much of the screen as is available for the list of choices; that is, a larger screen will accommodate a longer list automatically. By using variable height with PERFORM PRISM PROMPT TEXT and PERFORM PRISM PROMPT VALUE, you don't have to calculate how many lines are required to present your text or input field -- Prism will make the box tall enough automatically.
<height>x<width> is an acceptable synonym for <height> BY <width>.
Specify a row and column in which data inside your box should start. In the simplest case, "row" and "col" are positive integers indicating a fixed location.
For choice boxes, the row and column designations may be *, *+n, or *-n, indicating a position relative to the start of the field where the cursor is located (i.e. where the cursor is located when the f2=*Choices key is pressed).
In place of "row" you may use one of the terms UP, DOWN, or CENTER. And for "col" you may use LEFT, RIGHT, or CENTER. These designations will position the box in the available space, at the top, bottom, left, right, or center of the screen. For example, PERFORM PRISM SET SUBAREA 5x40 AT DOWN,RIGHT will place a box 5 rows tall by 40 columns wide in the lower right corner of the screen.
The term RELATIVE indicates that the coordinates are relative to the containing box when one subarea is created inside another. (RELATIVE is the default.) ABSOLUTE means that the coordinates are at fixed positions on the background screen, regardless of intervening boxes.
Here is another way of looking at the syntax of the AT <location> option for PERFORM PRISM SET SUBAREA:
PERFORM PRISM SET SUBAREA height BY width AT <location>
<location> = [RELATIVE | ABSOLUTE] <row>, <column>
<row> = positive integer for fixed row location
= *, *+n or *-n for row relative to cursor location
(choice boxes only)
= TOP, BOTTOM, CENTER to position box at the
top, bottom, or centered in the available
space
<column> = positive integer for fixed column location
= *, *+n or *-n for column relative to cursor
(choice boxes only)
= LEFT, RIGHT, CENTER to position box at the left,
right, or centered in the available space.
(UP or UPPER is a synonym for TOP, and DOWN is a synonym for BOTTOM.)
Here are some examples:
PERFORM PRISM SET SUBAREA 5x50 at 12,5 PERFORM PRISM SET SUBAREA 0 by 40 at *,*+5 PERFORM PRISM SET SUBAREA 10x35 at absolute center, center PERFORM PRISM SET SUBAREA 0 by 28 at relative 5, right
If your requested subarea dimensions, in combination with its placement on the parent screen (or box) would cause the box to fall off the edge of the screen in any direction, Prism will treat this as an error.
Or if you specify a subarea too narrow for the function keys needed in the box, Prism will treat this as an error. Prism does its best to abbreviate function key designations and squeeze the space between them, but there is a minimum space required for the function keys. This minimum varies, of course, depending on how many function keys are needed in the box. [See 12A.6.2 for recommended function key presentation.]
....v....1....v....2....v....3....v f3=Done f4=Prev f5=OK f9=Can minimum subarea width: 28 f3=Done f9=Can minimum subarea width: 14 f5=OK f9=Can minimum subarea width: 12 f5=OK minimum subarea width: 5 (text-only resolution box) f3=Done minimum subarea width: 7 (text-only trigger box)
Subareas are automatically surrounded by a ruled box. Your dimensions and location determine the size and the top-left corner (the logical row 1 and column 1) of the data area within the box. The ruling font box lies outside these dimensions and should be taken into account in determining where you want the box to occur. The upper and lower boundaries of the box are -1 row before and +1 row after the data. Because of a "field attribute character" which occupies a place on the screen between ruling and non-ruling data, the sides of the box are located -2 columns before and +2 columns after the data subarea. So any subarea must start on row 2 or higher, must end one row before the bottom of the screen, and may not extend into columns 1/2 nor 78/79.
PERFORM PRISM CHOOSE provides a pre-packaged way to present a list of items to choose from. The items typically represent possible values for an entry field, and are presented in a "choice box" via the f2=*Choices key. [See 12A.5.1.]
The items on the list can be derived from an array, or a search result or stack from a subfile. The list may allow a single choice or multiple ones; the user's choice is copied back into the entry field from which the f2=*Choices key was used.
PERFORM PRISM CHOOSE includes options to provide customized header text and prompts for the list, and Prism automatically takes care of presenting multiple pages of a long list. Prism also automatically handles error-checking (e.g. to edit whether a valid choice has been made). [See 12a.6.2 for additional details about paging in choice lists.]
It is the ON EVENT CHOICE... statement in a DECLARE SCREEN section of a protocol that enables the f2=*Choices function key on a screen. [See 12a.2.] Note that the only appropriate action for your application to take when the user presses f2=*Choices (according to current guidelines) is to present a box with a list of choices for an entry field. While PERFORM PRISM CHOOSE is certainly the easiest way to create this list, you may also write your own format and use PERFORM PRISM SCREEN to present the list, if you have requirements that are not met by the general tool.
Although the primary use of PERFORM PRISM CHOOSE is to present a choice box (and that is the focus of this description), the command may be used anywhere you need to present a list of choices. For example, you might code a trigger or button event in which part of your interaction with the user is to present a list (in a box).
PERFORM PRISM CHOOSE may also be used at the screen level to present a list that is not in a box (subarea), as long as this is done in your mainline screen processing code and not in an event.
When a choice list is generated on the screen, Prism defines "system" zones for each of the input fields associated with the list. There will be one input field for CHOOSE SINGLE and multiple input fields for CHOOSE MULTIPLE; the input fields are trigger fields. These zones have names prefixed with "$"; you may use the SPIRES command SHOW ZONES to see the names assigned to such zones. (While the choice list is displayed on the screen, type SPIRES to exit to SPIRES temporarily, then type SHOW ZONES to see the list of currently defined zones.)
One implication of this is that if you need to, you can set up trigger events off of these Prism-defined zones:
ON EVENT TRIGGER IN ZONE LIKE $CHOICE, PROC XYZ
PERFORM PRISM CHOOSE {SINGLE | MULTIPLE}
FROM {SUBFILE | RESULT | STACK | ARRAY}
OUTPUT = <source of list items>
INPUT = <source of values for field>
REPLACE [HORIZONTAL | VERTICAL]
BUILD [SEPARATOR='value']
TEXT = 'value'
PROMPT = 'value'
ID = screen-id
TITLE = 'screen title'
VERIFY [= 'text']
DEFAULT = 'n,n...'
REQUIRED
OK | OK = 'command'
SEND | SEND='command'
PREVIOUS | PREVIOUS = 'command'
CANCEL | CANCEL = 'command'
DONE | DONE = 'command'
YES | YES = 'command'
NO | NO = 'command'
OPTOK = 'text'
OPTSENd = 'text'
OPTPREvious = 'text'
OPTCANcel = 'text'
OPTDONe = 'text'
OPTYES = 'text'
OPTNO = 'text'
TIMELIMIT = <seconds>
The required options for PERFORM PRISM CHOOSE are SINGLE|MULTIPLE, FROM, and OUTPUT.
Here are a few examples of commands. Details about the options follow below.
perform prism choose single from subfile, output=xappl \
input=appl.id, replace \
prompt='Choose an application ID from the list below:' \
id = appl.id.box
perform prism choose single from array \
output=Instructor, input=Instructor, replace \
text='Pick an instructor from the list below' \
prompt='Choose an instructor here, or cancel this box:'
perform prism choose multiple from array \
output=TermTypes, input=TermTypes, build, replace \
text='Mark your terminal type(s) with an X:' \
prompt='Choose terminal type(s) you use here, or cancel \
to enter a terminal type not shown here.'
The SINGLE option generates a choice list that has only a single input field, associated with the PROMPT string (see below). The user may only choose one value from the list (by entering a number from the list).
The MULTIPLE option creates a list with input fields beside each item on the list; the user may choose multiple items by marking each choice with an X. (See the examples below, in the paragraphs describing the TEXT and PROMPT options.)
These three options define the contents of the items in the choice list.
The FROM option describes where the items on the list come from -- an array, a search result or stack, or all records from a subfile. To use FROM RESULT, STACK, or SUBFILE, your protocol code must establish a link to a secondary file (with PERFORM PRISM LINK) and assemble a search result (for example) from which the choice list should be generated. [See 16 to read about secondary files.]
If you specify FROM SUBFILE, then Prism presents all records in the secondary file in the choice list, via FOR SUBFILE. Note that the choice list is built in memory, so it is not prudent to use FROM SUBFILE against a large subfile. A lengthy choice list (say, more than 100) is probably unwieldy for the user anyway, but building a list of, say, more than 1000 is likely to cause memory difficulties for your application.
For FROM ARRAY, the OUTPUT option specifies an array name. For FROM RESULT, STACK, or SUBFILE, the OUTPUT option specifies an element name. The source named in the OUTPUT option provides the actual values to be shown in the choices list. Only one element may be named here. If you need to present multi-part items in the list, you might define a dynamic element in your protocol code and use that element name in the OUTPUT option. [See 12a.17 for an example.]
When the values for a choice list are coming from an array, Prism starts with the variable occurrence numbered 1 in the array, e.g. variablename::1 and not variablename::0.
The INPUT option defines an element name or array name whose values should be returned by PERFORM PRISM CHOOSE and optionally placed in the entry field on the main screen after a choice has been made. That is, $PARM and/or $FIELDVAL is set from values in the INPUT source. (See discussion of $PARM and $FIELDVAL below.)
INPUT and OUTPUT sources may be the same. Currently, list items are limited to one line in your box and are truncated if they are too long.
The INPUT option may be omitted, in which case Prism will return the number or numbers chosen, instead of values.
If it turns out that your FROM source ends up with only one item to choose from, Prism will bypass the choice box itself and just "choose" it automatically, placing a value in the entry field, unless you have coded a VERIFY option (see below).
Here is sample protocol code for the first choice box illustrated in an earlier section. [See 12A.5.1.] This example illustrates many of the commands and options described so far and shows how they all fit together.
The protocol links to a secondary file; all of the records in the subfile will be presented in the choice list (...FROM SUBFILE). A dynamic element (XAPPL) is defined as the OUTPUT source for the list items, although what is mapped back to the entry field when the user chooses is the value of the APPL.ID element (INPUT=APPL.ID). The REPLACE option is described next; it specifies that the user's choice should be placed in $FIELDVAL and mapped back into the field from which f2=*Choices was pressed, replacing whatever was there before. (In this case, it is an APPL.ID value that will go into the field.)
declare screen incident
on event choice in zone appl.id, proc lookup.apl
enddeclare
:
++lookup.apl
perform prism set subarea 0x60 at 8,10
perform prism link xsaqa.apl.lnk
define element xappl as @appl.id ', ' @appl.name
perform prism choose single from subfile \
output=xappl, input=appl.id, replace
define element xappl as $zap
perform prism unlink
perform prism clear subarea
return
The REPLACE option instructs Prism to take the user's choice and map it back to the original field when processing the f2=*Choices command. The INPUT option defines exactly which element or array is used to provide the values. See the section on $PARM and $FIELDVAL below for examples of cases where you might want to omit the REPLACE option. [See 12a.16 for an example of another way to control mapping of choices back to the main screen.]
For multiple-choice lists, the REPLACE option can be followed by either HORIZONTAL or VERTICAL, to describe how multiple choices should be mapped to multiple fields on the original screen. HORIZONTAL means that multiple choices are mapped to consecutive fields, starting with the initial field and tabbing right. HORIZONTAL is the default multi-value mapping if REPLACE is specified.
VERTICAL means that multiple choices are mapped back to fields below the initial field (for example a column of values).
Like HORIZONTAL and VERTICAL, the BUILD option is only applicable for multiple-choice lists. BUILD specifies that multiple choices should be concatenated into a single string, with the individual choices separated by a comma-space. You can also specify a separator other than a comma with the SEPARATOR option. This is useful when a multiple-choice box is intended to fill out a single field on the screen, or when you do not use the REPLACE option and instead wish to work with the value returned in $PARM for other purposes.
When a user presses the f2=*Choices key for a field, the $FIELDVAL variable contains any value currently in that field. In your protocol code, you might use $FIELDVAL to alter or control the list that is presented to the user. [See 12a.16 for an example.]
After PERFORM PRISM CHOOSE is done, the user's choice is placed into $PARM. In addition, if you have included the REPLACE option on PERFORM PRISM CHOOSE, then the user's choice is also placed into $FIELDVAL. When the user leaves the box and returns to the main screen, $FIELDVAL is placed into the input field from which the CHOICES command was issued. In other words, $FIELDVAL is always placed into the original field on the main screen. But the user's choice is only placed into $FIELDVAL if the REPLACE option is used on PERFORM PRISM CHOOSE.
A field's value will be replaced if $FIELDVAL has changed even if the user cancels out of a box (i.e. if your code issued a SET FIELDVAL command). This allows your application to always reset a field by resetting $FIELDVAL first in the event step.
Your application might, in some circumstances, need to omit the REPLACE option so that after the user's DONE or OK command is issued, your code can manipulate $PARM in some way and then SET FIELDVAL explicitly.
You may imbed cursor positioning control sequences in your SET FIELDVAL command, in order to fill in multiple fields or otherwise control where the cursor is positioned after the value is placed into an input field on the main screen. [See 12A.16 for examples.]
Another example of how you might use $PARM as set by PERFORM PRISM CHOOSE is if your choice list simply sets some parm that will be used in a subsequent process. For example, a choice event might first present a list asking the user whether he wants to see a "short menu" or "long menu". You'd use PERFORM PRISM CHOOSE without REPLACE and then capture the $PARM value to use in constructing the next list.
The TEXT option provides text to go at the top of the choice box. The PROMPT option supplies a prompt at the top of the list. The default prompt is "Choose one from the list below." or "Choose one or more from the list below." (for CHOOSE SINGLE and CHOOSE MULTIPLE, respectively).
These very simple examples illustrate how the TEXT and PROMPT values are used inside choice boxes.
*---------------------------------------* | _ <-- Choose one from the list below. | <-- default prompt text | 1. American Express | | 2. Master card | | 3. Visa | | f3=Done f9=Cancel Box | *---------------------------------------*
*---------------------------------------* | There are 13 items like PENS. | <-- TEXT | | | Enter an "X" next to items to order: | <-- PROMPT | _ Ball point pens | | _ Fountain pens | | _ Quill pens | |(nos. 1-3 of 13) | | f3=Done f5=OK f9=Cancel Box | *---------------------------------------*
In the TEXT option, you may use double slashes as a "line-feed" indicator. This simple formatting tool lets you force a line break or add blank lines. For example:
PERFORM PRISM CHOOSE ... TEXT = 'The following items were found \ in the catalog.// //***Prices current as of January 1***' ...
This command would produce a choice list with text formatted like this:
*------------------------------------------------* | The following items were found in the catalog. | | | | *** Prices current as of January 1*** | | | | _ <-- Choose one or more from the list below. | | _ Ball point pens ($0.29 ea) | | _ Fountain pens ($1.59 ea) | | _ Quill pens ($7.59 ea) | |(nos. 1-3 of 13) | | f3=Done f5=OK f9=Cancel Box | *------------------------------------------------*
You may supply a screen identifier, for use in the key of a context help for the screen image containing your choice list, or for use in a DECLARE SCREEN statement (to declare an event for the choice list screen). This is analogous to the screen-id for regular input screens (e.g. in PERFORM PRISM SCREEN commands).
If you are using PERFORM PRISM CHOOSE at the screen level (as opposed to using it in an event and presenting the choices in a box) then you should supply a screen title. This title appears in the second line of the screen (in the status area). The TITLE option is not required, but you are strongly encouraged to use it when coding a choice list at the screen level. When PERFORM PRISM CHOOSE is coded in an event, the TITLE option has no effect.
Normally when the choice list would only contain one item, Prism will bypass the screen prompt and assign the value to $PARM and/or $FIELDVAL directly. The VERIFY option will cause even a single item to be verified as the desired choice. Verification is via a YES/NO box; for example:
Normal choice: With VERIFY option: *---------------------------* *--------------------------------* | There are three names... | | Only one choice found: | | | | | | _ <-- Choose ... | | Andrew, Peter D | | 1. Andrews, P. C. | | | | 2. Andrews, Peter | | Is this the one you want? | | 3. Andrews, Peter D | | | | f3=Done f9=Can box | | f4=No f5=Yes | *---------------------------* *--------------------------------*
When optional "text" is supplied with the VERIFY option, it will replace the default text of "Only one choice found:", e.g.:
PERFORM PRISM CHOOSE SINGLE ... VERIFY='Only one instructor found:'
For the "text" of the VERIFY option, you may use double slashes as a "line-feed" indicator, as described above for the TEXT option.
When the DEFAULT option is used, the "nth" entry or entries will be pre-selected in the CHOOSE list. Specify one number for CHOOSE SINGLE (DEFAULT = n). Multiple numbers might be used for CHOOSE MULTIPLE (DEFAULT = 'n,n,...').
For CHOOSE SINGLE, the specified number will be prompted in the entry field and the corresponding choice will be highlighted. For CHOOSE MULTIPLE, each specified entry will be marked with an X and highlighted.
The REQUIRED option specifies that the user is required to make a choice from the list before proceeding (or must otherwise issue the CANCEL BOX command). If REQUIRED is coded and the user issues the DONE or OK command without making a choice, an error message is given.
The DONE, OK, PREVIOUS, SEND, CANCEL, YES, and NO options enable the named commands for the box (or screen) where PERFORM PRISM CHOOSE is used.
The recommended command presentation for boxes was described in an earlier section. [See 12a.6.2.]
Most typically, when PERFORM PRISM CHOOSE is used in a choice box (event), DONE and CANCEL BOX should be enabled. When a choice list is presented in the context of an ON COMMAND event, OK and CANCEL BOX should be enabled.
OK and PREVIOUS are supplied automatically by Prism when needed for paging through a list that doesn't fit on one page. Otherwise, function keys are enabled automatically by Prism only if your PERFORM PRISM CHOOSE command does not specify navigation commands.
You may control the wording of the Guided Mode options at the bottom of the screen with the OPTOK, OPTPREV, etc. options on PERFORM PRISM CHOOSE. These work the same as on PERFORM PRISM SCREEN. [See 12.1.3.]
This option allows a timeout interval to be associated with the screen read. "n" is an integer, from 1 to 6000, indicating seconds. This option would cause a session that has been idle for "n" seconds to invoke a timeout, cancelling the current process (input, file selection, etc.).
PERFORM PRISM PROMPT VALUE provides a pre-packaged way to build a simple screen to prompt for a single value. For all practical purposes, a PROMPT VALUE input screen is useful only within a box (although this is not a technical restriction). [See 12a.17.]
The value that the user enters in the input field on a PERFORM PRISM PROMPT VALUE screen is returned in the $PARM variable.
PERFORM PRISM PROMPT VALUE {OPTIONAL | REQUIRED}
LENGTH = <number>
DEFAULT = 'value'
TEXT = 'value'
PROMPT = 'value'
ID = screen-id
TITLE = 'screen title'
OK | OK = 'command'
SEND | SEND = 'command'
PREVIOUS | PREVIOUS = 'command'
CANCEL | CANCEL = 'command'
DONE | DONE = 'command'
YES | YES = 'command'
NO | NO = 'command'
OPTOK = 'text'
OPTSENd = 'text'
OPTPREvious = 'text'
OPTCANcel = 'text'
OPTDONe = 'text'
OPTYES = 'text'
OPTNO = 'text'
TIMELIMIT = <seconds>
The required options for PERFORM PRISM PROMPT VALUE are {OPTIONAL | REQUIRED}, LENGTH, and PROMPT.
The term OPTIONAL or REQUIRED determines whether the input field is optional or required.
The LENGTH option determines how long the input field is. If the LENGTH exceeds the width of the subarea (box) in which the input field appears, Prism will create a multi-line input area. The input area will grow to the length specified, up to the box's height. That is, if the length you specify won't fit in the size box you specified, Prism will simply truncate the input field, filling up the box. If the height of the box is coded "0" (e.g. PERFORM PRISM SET SUBAREA 0x50) then the box will grow to the bottom of the screen in order to accommodate the length specified for the input field in your PERFORM PRISM PROMPT VALUE command.
In addition, the input field will be padded out so that the last line of a multi-line input area extends all the way to the right hand side of the box, even if that makes the input area exceed your specified LENGTH.
You may prompt a default value in the input field with the DEFAULT option.
TEXT provides text to go at the top of the box. The PROMPT option supplies a prompt immediately above the input field. A blank line is supplied between the TEXT and PROMPT text.
Prism will put the PROMPT and the input field on the same line if they fit.
Here is a simple illustration of the screen layout for PERFORM PRISM PROMPT VALUE:
*---------------------------------* | General information here... | <-- TEXT | | <-- blank line | Instructions for input here... | <-- PROMPT | ____________________________ | <-- input field | f3=Done f9=Cancel Box | *---------------------------------*
In the TEXT option, you may use double slashes as a "line-feed" indicator. This simple formatting tool lets you force a line break or add blank lines. For example:
PERFORM PRISM PROMPT VALUE ... TEXT = 'You specified ID mail \ delivery.// //Enter your complete ID mail address below.' \ PROMPT = 'ID mail address:' ...
You may supply a screen identifier, for use in the key of a context help for the PROMPT VALUE screen image, or for use in a DECLARE SCREEN statement (to declare an event for the PROMPT VALUE screen). This is analogous to the screen-id for regular input screens (e.g. in PERFORM PRISM SCREEN commands).
If you are using PERFORM PRISM PROMPT VALUE at the screen level (as opposed to using it in an event and prompting for a value in a box) then you should supply a screen title. This title appears in the second line of the screen (in the status area). The TITLE option is not required, but you are strongly encouraged to use it when coding this command at the screen level. When PERFORM PRISM PROMPT VALUE is coded in an event, the TITLE option has no effect.
The DONE, OK, PREVIOUS, SEND, CANCEL, YES, and NO options enable the named commands for the box (or screen) where PERFORM PRISM PROMPT VALUE is used.
The recommended command presentation for boxes was described in an earlier section. [See 12a.6.2.]
You may control the wording of the Guided Mode options at the bottom of the screen with the OPTOK, OPTPREV, etc. options on PERFORM PRISM CHOOSE. These work the same as on PERFORM PRISM SCREEN. [See 12.1.3.]
This option allows a timeout interval to be associated with the screen read. "n" is an integer, from 1 to 6000, indicating seconds. This option would cause a session that has been idle for "n" seconds to invoke a timeout, cancelling the current process (input, file selection, etc.).
PERFORM PRISM PROMPT TEXT provides a pre-packaged way to present a simple text message to the user. For all practical purposes, a PROMPT TEXT input screen is useful only within a box (although this is not a technical restriction). [See 12a.17.]
PERFORM PRISM PROMPT TEXT 'text'
ID = screen-id
TITLE = 'screen title'
OK | OK = 'command'
SEND | SEND = 'command'
PREVIOUS | PREVIOUS = 'command'
CANCEL | CANCEL = 'command'
DONE | DONE = 'command'
YES | YES = 'command'
NO | NO = 'command'
OPTOK = 'text'
OPTSENd = 'text'
OPTPREvious = 'text'
OPTCANcel = 'text'
OPTDONe = 'text'
OPTYES = 'text'
OPTNO = 'text'
TIMELIMIT = <seconds>
The 'text' to be prompted may be up to 480 characters. The text wraps automatically within the box in which it is presented. You may use double slashes as a "line-feed" indicator. This simple formatting tool lets you force a line break or add blank lines. For example:
PERFORM PRISM PROMPT TEXT 'Warning: a 5% surcharge will be applied \ to this purchase.// //Do you want to continue this order?' \ YES, NO
You may supply a screen identifier with the ID option, for use in the key of a context help for the PROMPT TEXT screen image, or for use in a DECLARE SCREEN statement (to declare an event for the PROMPT TEXT screen). This is analogous to the screen-id for regular input screens (e.g. in PERFORM PRISM SCREEN commands).
If you are using PERFORM PRISM PROMPT TEXT at the screen level (as opposed to using it in an event and presenting the TEXT in a box) then you should supply a screen title. This title appears in the second line of the screen (in the status area). The TITLE option is not required, but you are strongly encouraged to use it when coding this command at the screen level. When PERFORM PRISM PROMPT TEXT is coded in an event, the TITLE option has no effect.
The DONE, OK, PREVIOUS, SEND, CANCEL, YES, and NO options enable the named commands for the box (or screen) where PERFORM PRISM PROMPT TEXT is used.
The recommended command presentation for boxes was described in an earlier section. [See 12a.6.2.]
The OPT... and TIMELIMIT options (which are all optional) work as described for PERFORM PRISM SCREEN. [See 12.1.3.]
The PERFORM PRISM SET ERROR command is used during event processing to do error code processing parallel to that available in the input frame of a screen. If an event detects an error, it can use PERFORM PRISM SET ERROR to update the screen with an error code much like the combination of SET UCODE and SET ERROR S in the format.
The syntax is:
PERFORM PRISM SET ERROR code AT row,column [WARN]
The maximum number of PERFORM PRISM SET ERROR commands allowed in one event step is 32.
This PERFORM will set status REPROMPT or WARN appropriately, though the protocol can later override this, say, to change REPROMPT to REPEAT, or to STOP if necessary. Errors should be processed at the end of the event to guarantee the desired STATUS values will be returned to Prism; otherwise the application must take care to SET STATUS explicitly before returning.
As with formats ERROR/ESTART processing, the first error indicated will establish the cursor position for reprompt, and the spaces occupied by the error codes will be reset to blank after each screen prompting in case other errors case a REPROMPT after these errors are fixed.
The PERFORM PRISM COPY command lets you read values from the screen, or place values on the screen, without the need for formats processing. This is a useful tool for simple reading and updating of screens by means of procedural code, such as in events (choice or trigger events, or ON COMMAND events).
By using PERFORM PRISM COPY, you can avoid having to code complex logic in a screen's input and output frames for different behavior depending on whether the image is being generated or read after, say, a trigger instead of an OK. For instance, an entry screen might show both the current code in an input field, with the code's expanded value displayed next to it. If f2=*Choices is used to change to a new code, the application could use PERFORM PRISM COPY VARIABLE...TO ZONE... to keep the screen in sync with the changed code.
The syntax is:
PERFORM PRISM COPY source TO destination DISPLAY='attribute(s)'
"source" can be: 'string'
VARIABLE variable-name
ZONE zone-name
"destination" can be: VARIABLE variable-name
ZONE zone-name
For example:
PERFORM PRISM COPY ZONE CITY TO VARIABLE NEWCITY PERFORM PRISM COPY 'Item status not available' TO ZONE STATUS
Zones are defined in your input format, using the $ZONEDEF function. [See 12a.4.]
The DISPLAY option can be used to change the display attributes of the "destination" zone as you copy a value into it. If you specify any display attribute, you must specify a complete "set" for the zone in question. That is, the attributes you specify in PERFORM PRISM COPY are not "additive" to the attributes already in effect for the zone -- they completely replace the existing attributes.
For a complete list of possible display attributes, EXPLAIN $SETAREA or see 4.5 in "SPIRES Device Services". The most common display attribute designations are:
colors: RED, BLUE, YELLOW, GREEN, CYAN, WHITE, PINK emphasis: HIDE, REVERSE, BRIGHT, BLINKING pre-defined combinations: REQUIRED, OPTIONAL, ERROR, WARNING, TITLE, TEXT, DATA other: PROTECT, UNPROTECT, UNDERLINE
Multiple display attributes may be specified, for example:
/PERFORM PRISM COPY #NEWVALUE TO ZONE STATUS \ DISPLAY='BRIGHT,PROTECT,PINK'
Note that you can, in effect, simply change display attributes (without changing any values on the screen) by copying a zone over itself:
PERFORM PRISM COPY ZONE ABC TO ZONE ABC \ DISPLAY='BRIGHT,PROTECT,PINK,BLINKING'
Note that PERFORM PRISM COPY applies to the main screen image being processed, even if the command happens in an event proc that is also generating a box on top of the background screen image. This means, in effect, that when you are coding a screen with a box on top, you can't use PERFORM PRISM COPY to copy data to or from the box -- it is a tool to manage the background screen. If you are coding nested boxes (a box generated on top of a box), then PERFORM PRISM COPY applies to the background box.
The next section describes how to use Device Services coding techniques (the $GETAREA, $SETAREA, and $PUTAREA functions) as an alternative to PERFORM PRISM COPY. [See 12a.14.1.]
PERFORM PRISM COPY addresses the area named in the $SCRNAREA variable. $SCRNAREA is a SPIRES variable that is managed by Prism, containing the name of the area that is currently active.
$SCRNAREA is null when an application runs offline (e.g. when a Prism task executes).
In some situations, if PERFORM PRISM COPY and zones do not meet your needs, you might need to use $GETAREA and $PUTAREA functions to read and write values on Prism screens directly. (Please contact the Prism consultants to discuss ideas for enhancing PERFORM PRISM COPY so that it can be more useful. The intent is to provide adequate functionality in the PERFORM so that you can avoid Device Services coding.)
$GETAREA, $PUTAREA, and $SETAREA are SPIRES Device Services functions that refer to areas. For Prism applications code, always use $SCRNAREA or $AREANAME as the area name. The value of $SCRNAREA is managed by Prism and contains the name of the area that is currently active; it is available in formats or protocols. $AREANAME is a SPIRES variable set for formats whenever a frame is executed in a device services area. [See 12a.3 for a picture illustrating $SCRNAREA/$AREANAME.]
$GETAREA lets you read a value from a particular position on a Prism screen. The syntax is:
$GETAREA(area,READ,row,column,length)
The "row,column,length" identifies the location and length of the information you wish to read. For example:
let Code = $GetArea($ScrnArea, READ, 5, 20, 3)
will read a 3-character value from the data portion of the screen starting on row 5 at column 20.
EXPLAIN $GETAREA if you need further details about this function.
Writing to a Prism screen is more complicated; it involves the $PUTAREA, $SETAREA, and $GETAREA functions. Below is an example; refer to the SPIRES Device Services manual for details.
First, you would probably assign the value that you want to write to the screen to a variable. In this example, assume the value is in #CodeName.
Here is the entire example, with explanations of the individual statements in the paragraphs following:
let Value = $InSetL(#CodeName, $TermPad, 30) eval $PutArea($ScrnArea, #Value, 4, 45) let Fieldnum = $GetArea($ScrnArea, ALOC, 4, 45) eval $SetArea($ScrnArea, #Fieldnum, DATA)
The $PUTAREA function writes the data value to the area. The syntax is:
$PUTAREA(area,string,row,column)
Note that you must "pad" the field into which you are writing data with blanks, in order for screen attributes to be assigned properly.
let Value = $InSetL(#CodeName, $TermPad, 30) eval $PutArea($ScrnArea, #Value, 4, 45)
In this sample statement, a field 30 characters long, at row 4 and column 45, is being filled in with the #CodeName value, padded with blanks (or more precisely, padded with the $TermPad character).
Note that "field" here means a Device Services field, and not a data entry field in the sense of input areas on a Prism entry screen. In Device Services, a "field" is a consecutive set of characters, all with identical characteristics (display attributes). So a Prism entry screen has input "fields" (the places where users type data) next to protected "fields" (text labels for the input areas, or the blank areas in between input areas).
Finally, use $SETAREA to set the appropriate display attributes for the field into which you are writing data. The syntax is:
$SETAREA(area,fieldnumber,string1,string2,...stringn)
The "fieldnumber" refers to the consecutive numbers that SPIRES assigns to each Device Services field in the area. You can use $GETAREA, with the ALOC option, to determine the appropriate field number:
let Fieldnum = $GetArea($ScrnArea, ALOC, 4, 45) eval $SetArea($ScrnArea, #Fieldnum, DATA)
It's important to look up the field number after you write data to the area with $PUTAREA, in case the writing operation creates a new "field".
DATA is a term representing a combination of PROTECTED, WHITE, BRIGHT display attributes. See 6.1.0 in SPIRES Device Services for a list of possible terms to use with $SETAREA (or EXPLAIN ATTRIBUTES).
The PERFORM PRISM RESET UNDO command is used during event processing to control the scope of the UNDO command. It makes the current CRT image the one that will be restored if the user issues the UNDO command.
This command is useful in situations where your protocol event step has done work that cannot be "un-done" simply by refreshing the screen image to its state before the event started.
The default is that the scope of UNDO does not change during an event, and you are encouraged not to reset UNDO unless necessary. That is, if the work that is done in an event is fully reflected on the parent screen and can be reversed, it is best not to alter the scope of UNDO -- to let the user revert to the original screen image if needed.
"PERFORM PRISM DISABLE (or ENABLE) pfkey" lets you disable or enable commands (and the corresponding function keys) on a parent screen during event processing. For example, you might first present a screen with both OK and SEND enabled. During an event proc (e.g. in a trigger event, or after presenting a choice box), you might determine that when the parent (base) screen is shown again, only SEND should be enabled.
PERFORM PRISM {DISABLE | ENABLE}
OK | OK = 'command'
SEND | SEND = 'command'
PREVIOUS | PREVIOUS = 'command'
CANCEL | CANCEL = 'command'
DONE | DONE = 'command'
YES | YES = 'command'
NO | NO = 'command'
OPTOK = 'text'
OPTSENd = 'text'
OPTPREvious = 'text'
OPTCANcel = 'text'
OPTDONe = 'text'
OPTYES = 'text'
OPTNO = 'text'
The 'command' clauses are protocol commands to be executed if or when the end-user issues the command, just as with PERFORM PRISM SCREEN. The OPT... options control wording of the guided mode options at the bottom of the screen. [See 12.1.3 for detailed explanations of these options.]
This section contains miscellaneous coding tips:
You can cause a choice of value for one field to map to several fields on the main entry screen. The effect for the user is that several fields get filled in automatically as a result of picking a value for one field.
The mechanism to do this is to imbed "tab symbols" into values for a field, as illustrated below. Currently, these tab symbols are available:
\f+ tab (move to next unprotected field) \f- back tab (move to previous unprotected field) \fu up (i.e. go to closest input area above current cursor location) \fd down (go to closest input area below current cursor location) \f= move to same unprotected field (no tab)
Say that the main entry screen has City and State fields:
City* __________________________ State: __ :
When the user presses the f2=*Choices key for the City field, he sees:
*---------------------------------------* | _ <-- Choose one from the list below. | | 1. Charlottesville | | 2. Chicago | | 3. San Francisco | | 4. Washington | *---------------------------------------*
After making a choice, the main screen looks like this:
City* Charlottesville___________ State: VA :
To accomplish this, you could define an array with values like this:
CityList::1 = 'Charlottesville' CityList::2 = 'Chicago' CityList::3 = 'San Francisco' CityList::4 = 'Washington' CityVal::1 = 'Charlottesville\f+VA' CityVal::2 = 'Chicago\f+IL' CityVal::3 = 'San Francisco\f+CA' CityVal::4 = 'Washington\f+DC'
Then, your protocol code would follow this pattern:
++choice.city
perform prism set subarea 0x40 at *,*+6
perform prism choose single from array \
output=CityList, input=CityVal, replace
perform prism clear subarea
return
You can SET PARM, either in a protocol command or in a formats Uproc, to control the position of the cursor. (You don't have to be working with events or boxes to use this technique.)
set parm 'Cursor=(1,1)' <-- specifying a row and column position set parm 'Cursor=(command)' <-- specifying the command line
If you SET FIELDVAL in a choice or trigger/button event, you can imbed cursor positioning control sequences in the value (the same codes listed in the first part of this section):
set fieldval 'San Francisco\f+CA\f-'
This example would place "San Francisco" in the first input field (the first field in the zone from which the event happened), tab to the next field and place "CA", then back tab (back to the "city" field).
The OUTPUT option on PERFORM PRISM CHOOSE can only name a single element from a subfile with which to construct the items in a choice list. But you can define a dynamic element that concatenates values from several elements and then use that dynamic element as the source for your list.
This example was shown earlier, but is repeated here as a coding example. [See 12A.10.]
declare screen incident
on event choice in zone appl.id, proc lookup.apl
enddeclare
:
++lookup.apl
perform prism set subarea 0x60 at 8,10
perform prism link xsaqa.apl.lnk
define element xappl as @appl.id ', ' @appl.name
perform prism choose single from subfile, \
output=xappl, input=appl.id, replace, done, cancel
define element xappl as @zap
perform prism unlink
perform prism clear subarea
return
In this code, the dynamic element XAPPL concatenates values from two subfile elements. XAPPL values are shown in the choice box (OUTPUT=XAPPL).
Note that each item in a list is only allotted one line, in the current implementation. If OUTPUT values are longer, they are truncated.
Here's a screen where you ask the user to enter a last name before using f2=*Choices:
Enter an Advisor ID. Or, if you only know a last name, enter the name and press f2=*Choices. Advisor* ____________________________________ :
Here's how the protocol code for this choice box might use the value entered in that advisor field.
++lookup.advisor
perform prism set subarea 0x65 at 5,8
If ~$FieldVal : begin
perform prism prompt value, required, ok, cancel \
text='Enter a name for lookup.', prompt='Name:'
- User's response to PROMPT VALUE screen goes in $Parm
endb
Else /Set Parm = '$FieldVal'
perform prism link advisors
/find name $Parm
if $zresult then jump zero
for result where status=c
stack all
endfor
sequence adv.name
/perform prism choose single from stack replace, \
output=adv.name, input=adv.name \
text='There are $Stack advisors like $parm.' \
prompt='Choose an advisor from the list below.' \
done, cancel
clear stack
clear result
perform prism unlink
perform prism clear subarea
return
Prism's tools for packaging the contents of a box -- PERFORM PRISM CHOOSE, PERFORM PRISM PROMPT TEXT, and PERFORM PRISM PROMPT VALUE -- have been described in this chapter in terms of using them with boxes. There is no technical restriction to prevent you from using these commands at a screen level instead of within a subarea, although practically speaking, PERFORM PRISM CHOOSE is really the only one of these commands fully-developed enough to make sense at a screen level.
Prism does edit to ensure that within an event, any command to generate a screen image (PERFORM PRISM SCREEN, CHOOSE, PROMPT TEXT, PROMPT VALUE) is used within a subarea (box). An exception is made for PERFORM PRISM SCREEN READ, which may be used in an event at the screen level. Outside of an event, these commands can be used at the screen level, without a defined subarea.
You might, for example, code a protocol to provide a parm screen whose contents are generated by PERFORM PRISM CHOOSE rather than a format. (You'd omit the PERFORM PRISM SET SUBAREA command in this case.)
When used outside of a subarea, the data generated by PERFORM PRISM PROMPT TEXT and PERFORM PRISM PROMPT VALUE are presented up at the top of the screen, using the full screen width. The only formatting control that you have for the text being prompted is the use of double slashes to signal line breaks. [See 12a.11, 12a.12.]
But you might find it helpful as a development tool to use PROMPT TEXT or PROMPT VALUE at a screen level as a placeholder for a parm screen, as you're coding prototypes for new parts of your application.
Most searches in Prism are handled automatically, without any intervention by your application. When an end-user types a search (e.g., FIND + search type + value), Prism passes the search request on to SPIRES. (In your profile, you have listed the SPIRES search term that corresponds to each Prism index.) SPIRES performs the search and passes the search result back to Prism. Your own code does not have to issue a FIND or equivalent command to support these standard searches.
For more specialized needs, Prism offers the following capabilities to more closely control searching processes in your application:
- You may add protocol processing steps to be executed after the user has supplied a search value for an index but before the search has been done in SPIRES. (For value-supplied indexes, the protocol step would execute after the index is chosen.) These protocol steps are associated with a particular Prism index, and are sometimes referred to as "index exits".
- "Pre-search" and "post-search" protocol steps may be supplied, to execute either before or after a search has completed in SPIRES. These steps apply to all indexes. You may define separate protocol steps for a zero result or a result greater than zero.
- You may add protocol steps to do "hidden" searches on behalf of the user. For example, you might want to do a search automatically when your file is first selected, or when a particular report or entry form is chosen. In this case, the user would not have to issue a FIND command, but would have a pre-assembled search result to work with.
- You may disable searching completely when a particular form or report is chosen.
- And finally, there are three special types of Prism indexes:
- Value-supplied: The user does not need to supply a search value.
- Stand-alone: The index may not be combined with other indexes.
- Qualifying: May only be used in combination with another index.
Some of these special features are implemented by simply answering questions in your profile. Others require you to write protocol code and install protocol steps in your profile.
There are several PERFORM PRISM commands that are of use in search-related protocol steps; these are explained in this chapter:
- PERFORM PRISM SET SEARCH -- lets you reset indexes or search values before the search is passed to SPIRES for execution. This command is of use for index exits (and only for index exits). Reminder: an index exit is a protocol step associated with a specific Prism index, to execute after a search command has been issued in Prism but before the search is done in SPIRES.
- PERFORM PRISM ASSIGN SEARCH -- assigns a stack or result gathered behind the scenes as the end-user's visible search result. This command is useful in post-search protocol steps, where you need to modify a completed search, or in other kinds of protocol steps where you want to establish a search result (that is, steps executed when your file is selected or when a report or entry form is chosen). It may help to think of this as an "ASSIGN RESULT" command, since it is used to create a search result on behalf of the user.
- PERFORM PRISM SEARCH -- asks Prism to perform an index search of your subfile. This command is virtually obsolete, and should not be used.
Here are a few examples of how "search steps" might be used.
A "hidden" search lets you pre-assemble a search result automatically on behalf of the user, either when he first selects your file, or when he chooses a report or entry form. (You could have a different hidden search at each of these points.)
To install a hidden search:
Here is a reference chart to figure out where to put the protocol Proc:
for a hidden search ... proc goes in ... install with ... ----------------------- ------------------ ------------------ at file selection FILE XSETUP PROFILE for a report REPORT/report-name XSETUP REPORT for an entry form FORM/form-name XSETUP FORM
In this type of protocol step, you normally issue SPIRES commands to gather the search result, and then include a PERFORM PRISM ASSIGN SEARCH command to post the search result in Prism for the user. Here is a very simple example:
* FILE ++first.search find status pending perform prism assign search from result, title='Pending orders' return
PERFORM PRISM ASSIGN SEARCH is described in more detail in a later section. [See 13.2.]
This example is for a hidden search at file selection, so it would be installed with XSETUP PROFILE. Here are the relevant questions:
Orders XSetup Profile 02/08/92 12:03
ORDERS: Profile, page 3
-------------------------------------------------------------------------
Enter 'Yes' to see screens to add, modify, or delete processing steps.
- when the subfile is selected or cleared: yes_
- when search is completed: No_
Enter 'Yes' if the protocol steps for this file are compiled: No_
Orders XSetup Profile 02/08/92 12:03
ORDERS: Select/Clear Steps, File Select
-------------------------------------------------------------------------
Please identify processing steps that Prism should execute. For TYPE,
enter "S" for a screen step, "P" for a protocol step. Title is required
for SCREEN steps since that title is used to label the screen.
Processing steps for when file is selected:
STEP# STEP ID TYPE TITLE/COMMENT Note: To
1 first.search____ p hidden search_____________ remove a
2 ________________ _ __________________________ processing
3 ________________ _ __________________________ step,
delete the
Processing step for when file is cleared: value under
STEP ID.
STEP# STEP_ID TYPE TITLE/COMMENT
CLEAR ________________ P _______________________________
You may want the result retrieved by a hidden search at report selection or form selection to be the only search result your end-users can apply to that form or report. In that case, you may disable searching (i.e., turn off the FIND command and related commands) when you install the form or report. To do this for an entry form, in XSETUP FORMS answer 'No' to the following question:
Enter 'Yes' to permit searching when this form is selected: __
(There is a similar question in XSETUP REPORTS.)
It is not possible to turn off searching at file-selection, so an end-user will always be able to modify or replace the hidden search you provide then.
This section discusses protocol steps that are associated with a particular index -- how they are installed in your profile, variables and PERFORM PRISM commands that you will likely need to use, and how control passes between Prism and your protocol step.
These protocol steps are sometimes referred to as "index exits" since they're associated with a particular index. Index exits typically transform a user's search value and pass the new search statement back to Prism for processing. The function of the PERFORM PRISM SET SEARCH command is to pass the search statement from your protocol back to Prism.
Protocol steps associated with a particular Prism index are
Here are the relevant questions:
Orders XSetup Index 02/08/92 12:22
ORDERS: Index
-------------------------------------------------------------------------
Enter the following information as it should appear on the FIND menu:
NAME DESCRIPTION for this index Sample Search Value
________ _________________________________ _____________________
:
:
Enter 'Yes' to declare ... special features for this index: yes_
Orders XSetup Index 02/08/92 12:22
ORDERS: Index STATUS
-------------------------------------------------------------------------
1 <-- Indicate how this index is used by choosing one category
1. Regular search type
2. Stand-alone search type
3. Qualifying search type
If this index has a processing step, enter its name: _________________
The search type (index) currently being processed is stored in the $SRCHTYPE variable. The user's search value for that index is in $SRCHVAL.
The $LASTCMD variable contains the command immediately applicable to the search value being processed (i.e., FIND, AND, NOT, OR).
Here is an example of a common use for index exits. Assume the Prism application has a DATE index that is installed as a qualifying index. There is no corresponding SPIRES index, but a protocol step following the pattern below is installed for the DATE index in Prism. In the DATE index exit, ALSO processing is done against the current search result.
This index exit uses stored result techniques to convert the modified search into an object that can be referenced with the SET SEARCH command.
++DATE.SEARCH
; --------------------------------------------------------------------
; Index for date qualification. There isn't a SPIRES index available,
; so we use ALSO processing. The index is designated for
; qualification-only in the profile, so this exit will only be
; called for AND and AND NOTs.
; -------------------------------------------------------------------
/also date.written $srchval
if $no : - some recovery, using SET STATUS STOP...
if $SRCHSTAT = 4 : let newSearch = '@ZRESULT.RSTATUS'
else if $ZRESULT : let newSearch = '@ZRESULT.RSTATUS'
else begin
let counter = counter + 1
/store TEMP RESULT.DATE.#counter replace
let newSearch = '@TRESULT.DATE.' || #counter
backup ; restore the result we started with
endb
/perform prism set search #newSearch
return
The protocol step for an index is always invoked after the end-user has typed in the search value. If the end-user is prompted for a search value and simply presses the Return key to bypass the prompt, your protocol step for that search type will be bypassed.
The protocol step is invoked once for each search value being processed. For example, if the user types FIND STATUS OLD OR NEW and you have a search step for the STATUS index, the protocol step will happen first for $SRCHTYPE STATUS and $SRCHVAL OLD and then again for $SRCHTYPE STATUS and SRCHVAL NEW. This lets your protocol step work on each search value independently.
These diagrams illustrate how control passes between your protocol and SPIRES/Prism.
User SPIRES search Prism presents
types ----------------------->- is executed ------------>-- search result
simple | /|\ | /|\
search, e.g. | | | |
FIND STATUS OLD | | | |
| | | |
\|/ | \|/ |
protocol step for post-search
STATUS index step
($SRCHTYPE = STATUS)
($SRCHVAL = OLD)
($LASTCMD = FIND)
User SPIRES search Prism presents
types ----------------------->----------- is executed --->-- search result
compound | /|\ | /|\ |
search, e.g. | | | | |
FIND STATUS OLD | | | | |
AND AUTHOR JONES | | | | (post-search
\|/ | \|/ | step)
protocol step for protocol step for
STATUS index AUTHOR index
($SRCHTYPE = STATUS) ($SRCHTYPE = AUTHOR)
($SRCHVAL = OLD) ($SRCHVAL = JONES)
($LASTCMD = FIND) ($LASTCMD = AND)
User SPIRES search Prism presents
types ----------------------->----------- is executed --->-- search result
compound | /|\ | /|\ |
search, e.g. | | | | |
FIND STATUS OLD | | | | |
OR ARCHIVED | | | | (post-search
\|/ | \|/ | step)
protocol step for protocol step for
STATUS index STATUS index (2nd time)
($SRCHTYPE = STATUS) ($SRCHTYPE = STATUS)
($SRCHVAL = OLD) ($SRCHVAL = ARCHIVED)
($LASTCMD = FIND) ($LASTCMD = OR)
There are several ways in which Prism's searching environment differs from that of SPIRES:
In addition to those searching interface features, there are some differences in how Prism interprets searches or manipulates them before passing the search commands on to SPIRES. (Remember that the SET STRACE command lets you see how a search in your application is being sent to SPIRES.) [See 7.4.2.]
Prism sometimes adds an = sign to ensure that a string is treated as a search value and not an index. One reason for this this to avoid situations where a SPIRES index exists but not a Prism index, and there's a match between a search value and the SPIRES index name. Example:
find name smith or jones
passed to SPIRES as: find name smith or = jones
Prism adds parentheses to group together multiple search values for an index in situations like this:
find dept classics and name smith or jones
passed to SPIRES as: find dept classics and (name smith or = jones)
In SPIRES, the logical operators would be interpreted left to right, producing a different result than the Prism form of the search.
When you install a Prism index, one of your options is:
Enter 'Yes' to treat search values as phrases: No_
If you answer "yes" Prism will interpret a string of words after an index name as one search value. The string will be enclosed in quotes when the search is passed to SPIRES. For example:
find status a or b
passed to SPIRES as: find status "a or b"
(if "phrase processing" is enabled)
find title war and peace
passed to SPIRES as find title "war and peace"
(if "phrase processing" is enabled)
There are two situations where you might want this interpretation of search values. One is where an index is a text-oriented "phrase" index and search values might include words AND, OR, and NOT that should be treated as part of the search value rather than as a logical operator (as in the TITLE example above).
Another reason to use "phrase processing" is to control how a protocol step for the index is invoked when a search value includes logical operators. If the search value is treated as a phrase and placed in quotes by Prism, your protocol step will be invoked only once. If the search value is not quoted and a logical operator is present, the protocol step would be invoked once for each search value. For example:
find status "a or b" (phrase processing enabled) invokes your protocol step once, with $SrchVal of "a or b" find status a or = b (no phrase processing) invokes your protocol step twice, first with $SrchVal of "a" and then with $SrchVal of "b" and $LastCmd of "or"
The PERFORM PRISM ASSIGN SEARCH command notifies Prism that the current RESULT or STACK should be treated as the end-user's search result. The result or stack can be obtained through non-index processing (e.g., Global FOR or the ALSO command) or by a FIND command.
If used in a report exit, this command only affects the search population for DISPLAY REPORT or a PRINT of the report, not the population for DISPLAY.
The syntax is:
PERFORM PRISM ASSIGN SEARCH [FROM RESULT | FROM STACK] TITLE='title'
Here is a simple example -- for a value-supplied search type -- where Global FOR is used to retrieve all records for the current year. Then the assembled stack is assigned as the end-user's search result. If the search type is called THIS.YEAR, the status line will read "Find THIS.YEAR" when the result is posted.
++this.year for subfile /set scan prefix #thisyear stack all end='-' perform prism assign search from stack
In this example -- for a hidden search when a report is selected -- a standard FIND command is used and the result is assigned as the Prism result. The status line will have the label "Find Pending orders".
++report.search find status pending perform prism assign search from result, title='Pending orders'
Under current SPIRES restrictions, if the search result is from a stack, the index must be installed to stand alone -- it cannot be used in combination with other indexes. [See 13.4.1 for more about stand-alone search types.] To get around this limitation, after creating a stack, use the GENERATE RESULT command in your protocol step and then PERFORM PRISM ASSIGN SEARCH FROM RESULT.
The one exception to the stand-alone rule is a stack created out of a search result by the SEQUENCE command. The SEQUENCE stack is combinable with other search types because it is backed up by a "real" search result, whereas most stacks in SPIRES consist of key values only. However, the effect of sequencing would be lost.
Warning: do not mix PERFORM PRISM SEARCH and PERFORM PRISM ASSIGN SEARCH commands within protocol processing for a single search type. Since both of these commands tell Prism to post a particular search result for the user, use one or the other. In fact, PERFORM PRISM SEARCH is virtually obsolete and any use of the command at all is discouraged.
PERFORM PRISM SET SEARCH lets you reset an end-user's index or search value, perhaps based on tests in your procedural code. This command does not actually do the search -- it simply transforms the search values and passes them back to Prism (which passes the new search request to SPIRES). In this sense, it's like $REPARSE in SPIRES.
Index exits -- protocol steps associated with a particular index -- typically manipulate the user's search statement and then use PERFORM PRISM SET SEARCH to pass the new search statement to Prism for processing. [See 13.2 for more about index exits, including an example for ALSO processing.]
The syntax is:
PERFORM PRISM SET SEARCH search-argument
The "search-argument" consists of a valid SPIRES index and a search value (or a variable standing for a search value). It may also be a stored result name. The maximum length of "search-argument" is 253 characters.
In the example below, a user's NAME search is transformed to an OR search using two indexes (NAME and NEWNAME).
++search.name /perform prism set search name $SRCHVAL or newname $SRCHVAL
In the next example, a protocol step determines whether to proceed with a simple index built from QYY or to switch to the global QYY qualifier, depending on the command being processed. (When AND is used, the qualifier is much more efficient.)
++search.qyy if $match($LASTCMD,FIND,OR) then return /perform prism set search qual.qyy $SRCHVAL return
PERFORM PRISM SEARCH is virtually obsolete, and its use is discouraged. Note the limitations described at the end of this section. See the explanations of PERFORM PRISM SET SEARCH and PERFORM PRISM ASSIGN SEARCH for alternatives.
PERFORM PRISM SEARCH causes a search to be done in SPIRES and the result posted in Prism. The search could either establish a new result or modify an existing result.
One way to think of this command is that it's like doing a combination of a standard FIND in your protocol and then PERFORM PRISM ASSIGN SEARCH FROM RESULT.
The syntax is:
PERFORM PRISM SEARCH search-argument
The search-argument consists of a valid SPIRES search term and a search value (or a variable standing for a search value, such as $SRCHVAL or $ACCT). Do not include a leading FIND, AND, NOT, or OR on your "search-argument". Prism adds the FIND or the appropriate Boolean operator (whatever was typed by the user).
In this example, the user's search is modified so that he sees only salaries in his own department.
++salary /perform prism search salary $SRCHVAL and dept #userdept
If a search is interrupted (by a system error, ATTN/BREAK, or an end-user error caused by improper search values), control returns to Prism, not to the processing step. Prism then either reports the condition to the end-user, or reprompts the end-user for a new value, depending on how the interruption occurred.
Assuming no error or interruption occurs, then Prism returns control to the protocol step after performing the search.
A search type that does a PERFORM PRISM SEARCH in a protocol exit can only be used in a non-compound search, or when it is one of a set of indexes picked from the search type menu. (Multiple indexes picked from the menu are treated as iterative, not compound searches.) If an end-user does a compound search that includes a search type that does PERFORM PRISM SEARCH in a protocol step, he will get an error message indicating that this is an invalid use of the search type. (The user is referred to HELP COMPLEX SEARCH in Prism for an explanation.)
Note: In earlier versions of Prism, whenever a search step was coded, you were required to process the search in the protocol step (with PERFORM PRISM SEARCH or PERFORM PRISM ASSIGN SEARCH). Now, you may use a protocol step that does work other than processing the search (e.g., setting a flag, changing a search value with PERFORM PRISM SET SEARCH). Then, Prism will complete processing of the search, just as under automatic control. One benefit of this approach is that when Prism processes the search (rather than your PERFORM PRISM SEARCH command) you avoid the restriction described in the paragraph above.
The PERFORM PRISM GET LOCAL command is obsolete as of the 7/92 Prism release. Its purpose was to access a search value for a secondary search type when multiple secondary search types were defined for an index. Secondary search types are no longer supported in Prism.
As mentioned at the beginning of this chapter, it is possible to install protocol steps to execute either before a search, or after a search has completed in SPIRES. These steps are not associated with a particular Prism search type, but instead will be done before or after any search. You may define separate post-search protocol steps for a zero and a non-zero search result.
Pre-search and post-search protocol steps are coded in your FILE protocol.
Although a pre-search protocol step would run before every search, it is expected that applications would only allow this step to execute before the first FIND of an application session. Your protocol code should set a condition and prevent the protocol code from executing except for the first FIND.
Pre-search and post-search steps are installed in XSETUP PROFILE. Here are the relevant questions:
Orders XSetup Profile 02/08/92 14:12
ORDERS: Profile, page 3
-------------------------------------------------------------------------
Enter 'Yes' to see screens to add, modify, or delete processing steps.
- when the subfile is selected or cleared: No_
- before every search No_
- when search is completed: yes_
Enter 'Yes' if the protocol steps for this file are compiled: No_
Orders XSetup Profile 02/08/92 14:13
ORDERS: Result Steps
-------------------------------------------------------------------------
Please identify processing steps that Prism should execute.
Processing step to be executed for RESULT = 0
STEP# STEP ID TYPE COMMENT Note: To
1 ________________ P __________________________ remove a
processing
Processing step to be executed for RESULT > 0 step,
STEP# STEP ID TYPE COMMENT delete the
1 ________________ P __________________________ value under
STEP ID.
Some of the indexes described here appear in special categories on the FIND menu because there are restrictions on their use.
Prism indexes can be divided into the following categories:
Here is an example of a FIND menu, showing how different kinds of search types are labeled:
Orders Search 07/26/90 11:28 -------------------------------------------------------------------------- Choose a type of search by typing the name or number for each type of information you have, e.g. ACCOUNT or 1 TYPE OF SEARCH DESCRIPTION EXAMPLE 1. ACCOUNT Account number 424-35 2. TTYPE Transaction type order 3. MYDEPT Current records for your dept -- The following may not be combined with other indexes. 4. ORDCOUNT Accounts with outstanding orders 3 The following may only be used to qualify an existing search. 5. ORDSTATUS Order status (O, F, or A) O
MYDEPT is a value-supplied search type, as indicated by the absence of a sample search value on the FIND menu. To use it, you simply type FIND MYDEPT, without supplying a search value, since the application supplies the search value behind the scenes. [See 2.4 for more about value-supplied search types.]
ORDCOUNT is a stand-alone search type, and STATUS is a qualifying search type, as indicated by the headings on the FIND menu.
As mentioned earlier, you may specify that a search type may not be combined with other search types, i.e. that it must "stand alone". Stand-alone search types appear in a separate section of the FIND menu. [See 13.4.]
Why would you install a non-combinable search type? The main reason is that the search type retrieves a stack instead of a normal search result. (A group of records accessed by key through Global FOR sequential processing is one example of a stack.) SPIRES does not allow stacks and search results to be combined into a single entity, so a stack-retrieving search type must be separated from the standard result-retrieving search types. (The only exception: a stack created from a normal search result with the SEQUENCE command may be combined with other search results, though the effect of sequencing will be lost.)
Stand-alone search types almost always use protocol steps.
A stand-alone search type is installed with XSETUP INDEXES (or ADD PROFILE for a new application) in much the same way as a regular search type. To designate it as stand-alone, answer 'yes' to this question:
Enter 'Yes' to declare or modify special features for this index: Yes
and on the screen that follows, choose "Stand-alone":
2_ <-- Indicate how this index is used by choosing one category
1. Regular search type
2. Stand-alone search type
3. Qualifying search type
Secondary search types are no longer supported in Prism (as of July 1992).
A qualifying search type never initiates a Prism search, but instead is used to qualify or refine a search result that has already been retrieved. A qualifying search type is not tied to any particular index -- it can be used to qualify the search result retrieved by any primary search type (except a "stand-alone") in the file.
Qualifying search types appear in a separately labeled section of the FIND menu. [See 13.4.] Prism ensures that a qualifying search type cannot start a new search (after FIND) or expand an existing one (with OR) but instead is used only to restrict an existing search result.
A qualifying search type might equate to SPIRES global qualifiers, although this is not a requirement. Or you might use non-index processing, such as ALSO, in a qualifying search type. (A regular SPIRES index could be installed as a qualifying search type, too.)
A qualifying search type is installed much like a primary search type. To designate it as such, answer 'yes' to this question:
Enter 'Yes' to declare or modify special features for this index: Yes
and on the screen that follows, choose "Qualifying":
3_ <-- Indicate how this index is used by choosing one category
1. Regular search type
2. Stand-alone search type
3. Qualifying search type
This optional chapter discusses the MOD OPTIONS form in Prism Profile, whose purpose is to let you customize some of the generic option messages accompanying your application in Prism (e.g., at the bottom of the screen in Guided Mode). In a few cases, using this form to change option text (such as explanations of OK and SEND) will also affect the message line in Command Mode.
Customizing options text may help direct your end-users to important features of your application that the standard option text might cause them to overlook.
MOD OPTIONS can be useful whenever a particular task or activity can be stated in narrowly-focussed terms. For example, suppose your application contains a single entry form that always accomplishes the task of adding an address to a file. Then instead of the standard option text for the ENTRY command, which mentions data but doesn't specify what kind of data, you might want to customize your option text to specify that the data always involves addresses:
Instead of this....
Type: ENTRY to enter or change data.
You might want this:
Type: ENTRY to enter or update addresses.
Likewise, if your application contained a single report, whose purpose was to create mailing labels you might customize the options text describing the REPORT command.
You might change this...
Type: REPORT to produce a report.
to this:
Type: REPORT to produce mailing labels.
Changing option text in MOD OPTIONS affects not only the standard interface in Guided Mode, but also affects the complete listing of options and descriptions that end-users see online by typing the command OPTIONS (alias SHOW OPTIONS).
Note that you cannot modify the Prism commands themselves, only their descriptions. As a system-wide standard, the command names must stay the same for all Prism applications, so that end-users who need to use more than one application don't need to memorize additional commands and variants ad infinitum.
Also note that with MOD OPTIONS you can customize some of the data entry option text that appears during data entry (e.g., the text describing the OK command), and this text can be specific to a particular entry form -- but it cannot be tied to a particular screen within the entry form. Thus, if you have a four-page entry form with a slightly different task on each screen, your text describing the "OK" option would have to apply to all of the pages after the first one. It couldn't focus on a particular screen. If you use custom control of data entry, your PERFORM PRISM SCREEN commands may include parameters to control the options text on a screen-by-screen basis. [See 12.1.3.]
Here is a list of the different option text messages that MOD OPTIONS lets you customize. The different messages are grouped together according to whether the message would appear:
In the series of paired lines below, the top line shows the standard Prism message; the bottom line shows by way of periods how much space you have to customize a message:
1. OPTION TEXT AFTER FILE-SELECTION:
Type: ENTRY to enter or change data.
Type: ENTRY to ............................
Type: REPORT to produce a report.
Type: REPORT to ............................
2. OPTION TEXT AFTER FORM-SELECTION:
Type: CREATE to add a new record.
Type: CREATE to ............................
Type: GET number, to update information.
Type: GET number, to .......................
Type: REVIEW to see last transaction.
Type: REVIEW to ............................
3. OPTION TEXT DURING DATA ENTRY. This text can be made
specific to each entry form in your application.*
Type: OK below to continue to next page.
Type: OK below to ......................
Type: SEND to complete this transaction.
Type: SEND to ..........................
Type: PREVIOUS to return to a prior page.
Type: PREVIOUS to ......................
Type: CANCEL to cancel transaction.
Type: CANCEL to ......................
*Text for the HELP command and the
UNDO command cannot be modified.
4. OPTION TEXT AFTER REPORT SELECTION. This text can be
made specific to each report in your application.
Type: PRINT to print/mail/save report.
Type: PRINT to ............................
Type: DISPLAY REPORT to see report online.
Type: DISPLAY REPORT to ............................
The periods in the charts above indicate the maximum length of the customized option text. The "Type: <command> to " part of the text cannot be modified. Prism automatically supplies the period at the end of each customized option.
PERFORM PRISM SERVICE SUFIN GETAUTH is a tool to create an authorized view of the currently selected file, by setting a search modifier based on the user's "read" authority for University fund accounts.
PERFORM PRISM SERVICE SUFIN GETAUTH (version)
AUTHFILE = DEMO | REAL
SYSTEMID = 'system'
USERID = 'account or ID'
ACCTINDEX = 'index name'
DEPTINDEX = 'index name'
SEARCHMOD = 'mod'
where:
version Version of service you wish to execute
AuthFile Which Authority File to use?
SystemId Which 'system' are we in? e.g. EXPENSE
UserId Whom do we want to set the search mod for?
AcctIndex Name of the index for account search
DeptIndex Name of the index for (sub)department search
SearchMod Additional search to be performed
SUFIN GETAUTH performs a search, stores a temporary result, and sets a search modifier to AND or AND NOT that stored result, depending on the user's authority. Upon successful completion of the call, $STATUS is set to 'OK', 'NOAUTHORITY', or 'NORESULT'.
ALL SALARY ENDROUTE SPOPROJ EQINV STORES EXPENSE SUFFUNDS FORMS XPOPROJ JOURNALS ZUFACCTS PAYROLL ZUFFUNDS READ ZUFJNLS REQS
The $STATUS variable is set to 'NORESULT' if authority was found for the SYSTEMID/USERID pair, but no records were found in the caller's subfile to match that authority. NORESULT indicates that there are no records in the currently selected file that this user is authorized to see. In this case, no search modifier is set.
A special case of $STATUS = 'OK' and no search modifier set can occur if the user has no restrictions for the current system.
If a SYSTEMID/USERID pairing results in no authority being found, then no search modifier is set and $STATUS = 'NOAUTHORITY'.
Normally, a Prism application installed with ADD PROFILE appears on the SELECT menu in Prism to at least one person (according to the access rules that you specify).
Secondary files, on the other hand, do not appear on the SELECT menu but instead are accessible behind the scenes only. For instance, your primary Prism application might need to link to a second file in order to look up and retrieve information from the second file. Secondary files do not need the components normally installed for Prism applications (displays, helps, etc.)
Primary File Secondary File -------------------------------- ----------------------------- Visible on Prism menu -- Invisible to users -- a primary file is a secondary file is only accessible through SELECT accessible to authorized command to all authorized accounts and files via accounts PERFORM PRISM LINK Needs indexes, help records, Doesn't need visible a display format, etc. features such as helps Installed through ADD PROFILE Installed through ADD LINK Modified via MOD PROFILE Modified via MOD PROFILE
Though you can sometimes use SPIRES path processing commands in a protocol step to access other files, installing a secondary file lets you control access to it more securely -- you can use the PROGRAM = PRISM statement (as described below) to guarantee that other applications can link to your file only in Prism, and only through the PERFORM PRISM LINK command.
Just as you did for your primary file, add a SUBFILE-NAME in the form "Prism <file-id>", where "file-id" is that of the secondary file. Also add ACCOUNTS and PROGRAM statements as shown below.
E.g., for a secondary file with a file-id of LINKDEV:
SUBFILE-NAME = PRISM LINKDEV;
:
ACCOUNTS = PUBLIC;
PROGRAM = PRISM; <----------to enforce access
via Prism linking only
If you are using File Definer to create your SPIRES file, the input line defining the Prism view of the file might look like this:
SUBFILE Prism Linkdev/ ACCOUNTS Public/ PROGRAM Prism
Because security for access to the secondary file is best determined in Prism Profile, your SPIRES subfile section should almost certainly use ACCOUNTS = PUBLIC. The PROGRAM = PRISM statement ensures that this subfile view is available only in Prism and not in SPIRES.
There is one situation where you would need to install a "normal" application component for a secondary file. A routing application may link to a secondary file in order to route a form. If this is the case, and if the routing application supports "modification-during-examination" then the secondary file will need to have an entry form installed for use as the "approval entry form". [See the Routing Applications manual for complete explanations.]
For this reason, the XSETUP FORMS command is allowed for a secondary file.
The first page of ADD LINK asks questions familiar from ADD PROFILE, concerning the application's name and the person(s) responsible for it:
_____________________________________________________________________________ Prism Profile Entry Form: ADD LINK 10/15/87 11:14 Profile, page 1 ----------------------------------------------------------------------------- Enter the file's internal Prism identifying code (e.g. PUBEVENT). File-ID: ________________ Enter the SPIRES file-name for this subfile (e.g. GQ.DOC.PUBLIC.EVENTS). SPIRES file-name: ______________________ Enter the name and phone number of the person responsible for this application: __________________________________________________________ Enter the electronic mail account to which Prism communications will be mailed: gg.uuu____________________________________________ Indicate accounts, groups or access lists to maintain profile records: gg.uuu...................................................................... _____________________________________________________________________________
The second page of ADD LINK is slightly tricky: here you give access to your file to specific Prism developers (including anyone who can select these developers' files) and to specific Prism applications:
_____________________________________________________________________________ Prism Profile Entry Form: ADD LINK 10/15/87 11:16 <fileid>: Profile, page 2 -----------------------------------------------------------------------------
Indicate owner accounts of applications that may access this file. gg.uuu...................................................................... ............................................................................ ............................................................................ ............................................................................ ............................................................................ ............................................................................ ............................................................................ ............................................................................
Indicate Prism File-Ids that may access this file: ................ ................ ................ ................ ................ ................ ................ ................ ................ ................ ................ ................ ................ ................ ................ ................ ................ ................ ................ ................ ................ ................ ................ ................ _____________________________________________________________________________
It's important to note that this page widens access to your secondary file, rather than restricting it. People given access by account can link even if you don't also give their applications access by name.
Once the secondary file is installed, any account or application authorized through ADD LINK can link to it using the PERFORM PRISM LINK and PERFORM PRISM UNLINK commands in a protocol. [See 12.1.4 for a full description of PERFORM PRISM LINK.]
PERFORM PRISM LINK file-id [FORMAT format-name]
|
file-id of file named in ADD LINK,
e.g. "Linkdev"
PERFORM PRISM UNLINK
If you need later to modify the description of your secondary file, you can use XSETUP PROFILE, just as you would for a primary file. [See 8.]
If you decide later to remove your secondary file, you can use REM PROFILE, just as for a primary file. [See 8.6.] Remember to notify the people linking to your file, since their applications may stop working when you remove your secondary file.
The variables listed below are useful for communicating information from your application to Prism or vice-versa. Functions they support include:
- Conditional returns from your code ($STATUS)
- WARN-level reprompts during input ($STATUS)
- Passing commands back to Prism for execution ($NEXTCMD)
- Accessing status information from Prism ($SCRNSTAT, etc.)
All the variables listed are of type STRING and can be used either in formats (by way of a UPROC) or in protocols. Except for $DESTINATION ($DEST), the variable names cannot be abbreviated.
You can set the value for some of these variables yourself. Values for the other variables are set internally, but can be read by your code.
Variables You Can Set Variables Set by Prism
$MSGLINE [255] $DESTINATION [16] $PRISMID [16]
$NEXTCMD [255] $DESTVAL [64] $RECID [240]
$FIELDVAL [255] $EVENTZONE [16] $REPTNAME [16]
$STATUS [16] $FORMNAME [16] $SCRNSTAT [16]
$CGINAME [16] $LASTCMD [24] $SRCHTYPE [16]
$PARM * $MAINCMD [24] $SRCHVAL [255]
$UNIVEMAIL [64] $PROXYEMAIL [64] +
$UNIVID [32] $PROXYID [16] +
$UNIVNAME [64] $PROXYNAME [64] +
$UNIVPHONE [36] $PROXYPHONE [36] +
The maximum size of these variables is shown in brackets. Note that several of these variables may be used by non-Prism applications, such as the "suspires" web interface application.
(Maximum Length 1 Character)
The $DEBUG flag-type variable is set to true when DEBUG is in effect for you in Prism. Thus its value is true when both of the following conditions are true: 1) you have issued the SET DEBUG command (or another debugging command such as SET FTRACE that implicitly performs a SET DEBUG command); and 2) an application is selected to which you have authorized access as a developer.
$DEBUG can be very useful when you want your application to behave slightly differently in debugging mode -- for instance, when you want to save certain values while debugging that you wouldn't save during an ordinary session. [See 7 for more information on debugging tools in Prism.]
$DEBUG is also the name of a control word for help records, which has somewhat different uses. [See 6.3.12.]
($DEST: Maximum Length 16 characters; $DESTVAL: 64 characters)
$DEST and $DESTVAL indicate the output destination that the end-user requested when filling out Prism's PRINT screen. $DEST will contain a word indicating a "generic" destination, while $DESTVAL will contain the specific output destination, e.g. a specific printer name.
When a user completes the PRINT screen, $PARM is also assigned values reflecting the options chosen for the destination. For example, when $DEST is 'PRINTER' and $DESTVAL is a specific printer name, the $PARM variable contains the printing options entered by the user.
These variables will be essential if you dispatch report output yourself instead of having Prism dispatch the output. [See 10.4 for a description of dispatching output yourself.]
Note that a $DEST value of SCREEN, described separately below, is useful even for Prism-dispatched reports -- it lets you distinguish the online Prism environment from other output "destinations" such as the printed page.
Values of $DEST and $DESTVAL and $PARM may be:
$DEST $DESTVAL $PARM examples
--------- ---------------------- ---------------------------------
PRINTER FORSYTHE DEST=FORSYTHE,COPIES=2,FORMS=3HOL
PRINTER DTRLW DEST=DTRLW,LANDSCAPE
ATTACHED [null] TITLE='Summary Report'
EMAIL GQ.JPR GQ.JPR, TITLE='Errors in Prismdoc'
SPIRES@SLACVM SPIRES@SLACVM
FILE WYL.GQ.LTM.DATA TEMP WYL.GQ.LTM.DATA TEMP
PRISM#DATA ACC GQ.PUB PRISM#DATA ACC GQ.PUB
PRISM#DATA PRISM#DATA REPLACE
ACTIVE ACTIVE CLEAR
$DESTINATION is set to SCREEN when Prism is negotiating an online display. This value can be useful when you want a report to behave one way during an online DISPLAY, and another slightly different way in offline printing. For instance, you might use ruling font characters in the online display, but remove them from the printed output where their appearance would be inappropriate.
(Maximum Length 16 characters)
When a choice, trigger, or button "event" occurs, $EVENTZONE contains the name of the zone that triggered the event.
One situation where you might find it necessary to test $EVENTZONE is if you are using Prism's stem-matching capabilities for zone names, to accommodate "multiply-occurring zones". [See 12A.4A for an example of this technique.]
(Maximum Length 255 characters)
When the f2=*Choices key is pressed or data is entered into a trigger field, $FIELDVAL contains the value that was present in the field.
For f2=*Choices, it contains the value in the field where the cursor was positioned. If the cursor was not in an input field, the value is taken from the first unprotected field within the active zone following the cursor position.
During a choice event, if the REPLACE option was included on your PERFORM PRISM CHOOSE command, then the user's choice is placed into $FIELDVAL. The INPUT option on PERFORM PRISM CHOOSE defines which element or array is used for the values going into $FIELDVAL. $FIELDVAL is then used to place a value into the field on the main screen from which the CHOICES command was issued. [See 12A.10.]
You may SET FIELDVAL yourself to control what value is carried back to the main screen. The user's choice from PERFORM PRISM CHOOSE is also placed in $PARM. You might choose to manipulate $PARM and then SET FIELDVAL near the end of the protocol for your choice event.
For trigger events, you may SET FIELDVAL " " explicitly, in order to reset the trigger field to blank when the user returns to the main screen after a trigger box. Or you may set FIELDVAL to any other value appropriate for the trigger field at the conclusion of the trigger event.
You may imbed cursor positioning control sequences in your SET FIELDVAL command to place values in multiple fields or otherwise control where the cursor is positioned as a value is placed. [See 12A.15 for examples.]
(Maximum Length 16 characters)
This variable names the currently selected entry form. Its value is null outside of data entry.
The variables $LASTCMD and $MAINCMD contain the commands the end-user has last issued. They contain the command verb only, not the complete command string (with options).
$LASTCMD contains the latest command issued by the end-user. It is reset every time the end-user is prompted and has issued a command to Prism.
$MAINCMD is not reset every time the end-user issues a command. Instead, $MAINCMD "remembers" the last command that initiated a multi-part end-user request such as doing an entry transaction. The following commands are currently included in $MAINCMD since they can lead to menus or input screens:
SELECT, ENTRY, REPORT, FIND, AND, NOT, OR, DISPLAY, SORT, SETUP, GET, CREATE, PRINT, DISPLAY REPORT, REVIEW
Note that $LASTCMD is valuable in distinguishing relatively local command actions, such as OK vs. PREVIOUS, while $MAINCMD can be used to distinguish the larger process in effect, such as CREATE vs. GET. (Both $MAINCMD and $LASTCMD would contain the same value at the start of a larger process.)
The value in $MAINCMD and $LASTCMD will be a full command verb, in upper case. For DISPLAY REPORT, the value will be DISPLAY REPORT. Where Prism allows command alternatives, the implied command will be stored in $LASTCMD. For example:
Command is equivalent to $LASTCMD ------- ---------------- -------- n DISPLAY n DISPLAY FULL DISPLAY FULL DISPLAY BRIEF DISPLAY BRIEF DISPLAY OPTIONS SHOW OPTIONS SHOW DUMP IN ACTIVE SHOW SHOW EXPLAIN HELP HELP AND NOT NOT NOT
$LASTCMD and the RETURN or ENTER key interact differently in different situations. When an end-user has configured his RETURN key to mean OK (with SETUP PRISM) and is paging forward through entry screens or parameter-input screens, the RETURN key is essentially an alternate form of the OK command, so the value of $LASTCMD is OK. Anywhere else, however, a user's pressing RETURN/ENTER will place no value into $LASTCMD, i.e., $LASTCMD will be a null string.
In a simple search, $LASTCMD and $MAINCMD both are set to "FIND". In a compound search or an iterative search, $LASTCMD will reflect the Boolean operator for the search value currently being processed. In general, in protocol steps related to searching, it is most useful to test for $LASTCMD if you need to take action based on the kind of search operation being done.
find status archived
$MAINCMD = FIND
$LASTCMD = FIND
find status archived and date 1992
$MAINCMD = FIND
$LASTCMD = FIND while STATUS ARCHIVED is processed
$LASTCMD = AND while DATE 1992 is processed
and approver biddle
$MAINCMD = AND
$LASTCMD = AND
(Maximum Length 255 characters)
The $MSGLINE variable lets applications establish a message to be written in the reverse video message area. $MSGLINE covers special situations that Prism cannot foresee, for which the general Prism messages might be insufficient. In situations where the $STATUS variable must be set to STOP, you might want to provide a special message to end-users through $MSGLINE.
After SET STATUS 'STOP' the value for $MSGLINE is displayed in a box on the screen, along with a generic Prism message indicating that a command was not processed. [See 9.2.5.] Otherwise, it replaces the normal message in the message line of Prism's display.
When $MSGLINE is displayed on the message line, there is room for 78 characters; when it is used after SET STATUS 'STOP', up to 256 characters may be displayed.
After SET STATUS 'SYSERROR' the value for $MSGLINE is disregarded.
(Maximum Length 255 characters)
Use the $NEXTCMD variable to pass a command or command chain to Prism for processing. Note that the command or command chain in $NEXTCMD will only be processed at the successful completion of the current "command cycle". (A "command cycle" is, generally speaking, any process initiated by a command that involves multiple interactions with the end-user before the command;s intended function can be completed. Any command that invokes menus, parm screens or input screens begins a command cycle.)
For instance, you might pass a DISPLAY command for Prism to issue at the end of an entry form "command cycle", but you would not pass a command such as GET or SEND, because those commands would disrupt the entry "command cycle".
(Maximum length 32,000 characters; maximum 256 characters when set by SET PARM Uproc during format execution)
Besides its uses in SPIRES, the $PARM variable is used in a variety of ways by Prism: in print processing; when a "secondary" search type is used; in choices events (boxes); with PERFORM PRISM PROMPT VALUE; during ID/PIN prompting; and for cursor positioning.
$PARM is reset by certain commands, such as SET FORMAT and SELECT. Take care to save off its value before issuing a command that might change that value.
When a user fills in the Prism PRINT screen, $PARM, $DEST, and $DESTVAL are assigned values reflecting the options chosen on that screen. If you decide to dispatch report output yourself in a protocol step, you will need to determine the values of these variables in order to construct the appropriate command for dispatching the report output. [See 17.2 for a description of $DEST and $DESTVAL.]
Some possible values for $PARM in association with $DEST are shown below:
$DEST $DESTVAL $PARM examples
--------- ---------------------- ---------------------------------
PRINTER FORSYTHE DEST=FORSYTHE,COPIES=2,FORMS=3HOL
PRINTER DTRLW DEST=DTRLW,LANDSCAPE
ATTACHED [null] TITLE='Summary Report'
EMAIL GQ.JPR GQ.JPR, TITLE='Errors in Prismdoc'
SPIRES@SLACVM SPIRES@SLACVM
FILE WYL.GQ.LTM.DATA TEMP WYL.GQ.LTM.DATA TEMP
PRISM#DATA ACC GQ.PUB PRISM#DATA ACC GQ.PUB
PRISM#DATA PRISM#DATA REPLACE
ACTIVE ACTIVE CLEAR
When the user makes a choice from a choice box, the chosen value is placed into $PARM (and also in $FIELDVAL if the REPLACE option was used on PERFORM PRISM CHOOSE). The INPUT option on PERFORM PRISM CHOOSE defines which element or array is used for the values going into $PARM and $FIELDVAL. [See 12a.10, 17.2B.]
When you use PERFORM PRISM PROMPT VALUE, the value that the user enters on the resulting screen is saved in $PARM. [See 12a.11.]
In a protocol or a format, you may SET PARM to control cursor positioning:
set parm 'Cursor=(1,1)' <-- specifying a row and column position set parm 'Cursor=(command)' <-- specifying the command line
[See 12a.17.]
After a successful PERFORM PRISM LOOKUP NAME or PERFORM PRISM PROMPT NAME command, $PARM will contain a University ID and name, concatenated with a slash. Typically, the ID portion of $PARM would be extracted for use in a subsequent PERFORM PRISM PROMPT PIN command. [See 25.3.2 for details and examples.]
(Maximum Length 16 characters)
The $PRISMID variable holds the fileid ("Prismid"), from 1 to 16 characters, of the Prism file that the user has currently selected. Note that if one Prism application calls another one (for instance, with PERFORM PRISM LINK) the value of $PRISMID still reflects the calling application, which is what the user sees as the selected file.
These variables contain the ID, name, phone number, and email address of the person or work group for whom the current user is acting, if ID/PIN prompting has happened and the user has filled in the "Acting for" field to specify that he is acting as a "proxy".
Details about identifying users by ID and PIN and proxy identification are in a later chapter. [See 25, 25.6.]
(Maximum Length 240 characters)
The $RECID variable holds the value of the key of the current record as known to Prism. For instance, after a command such as PERFORM PRISM OPEN, RECORD = '123' the value of $RECID would be 123.
Single record displays, the REVIEW command, and entry transactions are among activities that set (or reset) $RECID.
Note that $RECID is in some ways similar to the SPIRES variable $KEY, but you should use $RECID, not $KEY, to keep track of the key of your record in Prism. (This is because the value of $KEY might be reset within a transaction in your file -- e.g., if an end-user requested help.)
Note that the $RECID variable can have only a single value at a given time on each path that you have made known to Prism. (To make a path known to Prism, use the PERFORM PRISM LINK command -- do not use SPIRES path processing commands.) [See 12.1.4.] For example, if during data entry your code opens more than one record, $RECID is reset each time a new record is open, and represents the latest opened record.
++OPEN.TWO PERFORM PRISM OPEN, RECORD = 'A12345' (1) : PERFORM PRISM OPEN, RECORD = 'A99999' (2)
After command (1), $RECID is A12345. After command (2), $RECID is reset to A99999 and the earlier value is lost unless you saved it in the meantime in your own variable.
$RECID is set specifically for each path that your code opens in Prism using PERFORM PRISM LINK -- for example, if your application links to a "secondary file" and opens a record in that file, $RECID will be set to the newly opened record in the secondary file. When you UNLINK from that secondary file, the value of $RECID reverts to the most recently opened record in your primary file.
(Maximum Length 16 characters)
The $DISNUM variable holds the number of the current record as known to Prism. Multiple record displays are among the activities that set $DISNUM.
Note that $DISNUM is in some ways similar to the SPIRES variable $RECNO, but $DISNUM is only modified by PRISM PERFORM or Folio processing. Outside of Prism/Folio, $DISNUM may be used for your own purposes.
(Maximum Length 16 characters)
This variable names the currently selected report. Its value is null outside of Report Activity.
(Maximum Length 16 characters)
Prism sets this variable as the status of the current input screen. Sometimes the value of $SCRNSTAT may be set in response to a value you have earlier given to $STATUS (e.g., SET STATUS = 'WARN' might lead to a $SCRNSTAT value of WARN) but you never set $SCRNSTAT yourself. Here are the possible values:
(Maximum length: 16 characters)
The $SRCHTYPE variable contains the name of the search type (index) being processed. For example, if the current search is FIND STATUS SENIOR, then $SRCHTYPE contains the value "STATUS".
(Maximum length: 255 characters)
The variable $SRCHVAL is used by Prism to store the value that the end-user of your application has entered for a primary search type during the current Prism search. For instance, if the current search is FIND STATUS SENIOR, then $SRCHVAL contains the value "SENIOR".
In a protocol processing step for that search type, your protocol code can access $SRCHVAL to see what value the end-user has supplied, or can issue a customized search behind the scenes, using the value of $SRCHVAL in a PERFORM PRISM command, e.g.:
/PERFORM PRISM SEARCH STATUS = $SRCHVAL AND YEAR = #CURYEAR
[See 13 for more examples.]
The $PARM variable operates somewhat similarly to $SRCHVAL during searching, but stores a value that was input for a secondary search type.
For the sake of consistency with earlier versions of Prism, the $ASK variable is set to the same value as $SRCHVAL; however, since the value of $ASK is frequently reset, you should definitely rely on $SRCHVAL, not on $ASK, to determine a current search value.
(Maximum Length 16 Characters)
The $STATUS variable tells Prism to alter normal processing of the current command sequence in your application's format or protocol. ($STATUS is cleared when your format or protocol is first invoked.) Many of these $STATUS values indicate a condition other than a normal, successful end to processing. Here are possible values for $STATUS:
Within an event, if your application sets $STATUS to STOP or SYSERROR or if an unexpected error occurs (such as a PERFORM PRISM syntax error), the main transaction (not just the event) will be terminated. Choice events are an exception, however. If an error occurs in a choice event, even if you set $STATUS to STOP or SYSERROR, the event will stop but the main transaction will not stop. Prism gives a message "Error processing CHOICES command" in this case.
When you set STATUS, make sure it is the last thing you do before returning. [See 11.3.2 for setting status during data entry, 9.2.5 for setting status from within a protocol.]
You SET STATUS to one of these values in order to redisplay a Prism screen. What is the difference between these four $STATUS values? Here is some summary information to help explain the differences.
REPROMPT
- Reprompts the screen.
- Makes the message line display bright and yellow.
- Turns on the ?ERROR help context and positions the cursor at EROW/ECOL.
- A default message about errors is provided: "Errors found; type HELP <error code> below for more information"
- Remembers changed-field information.
- Does not reset the scope of UNDO.
REDISPLAY
- Reprompts the screen like REPROMPT but does not turn on error condition (so does not do any of the other things listed above)
REPEAT
- Goes through the .OUT frame again.
- Re-initializes changed-field information.
- No default message; ?ERROR help context is not set.
- Cursor is placed at position 1,1 (so it goes to the first field on the screen).
- Does not reset the scope of UNDO.
RESTART
- Exactly the same as REPEAT, except that it resets the scope of UNDO.
Refer to the chart explaining Prism screen processing for further information about how these $STATUS values are used. [See 12a.1.]
The $STATUS variable is also set by the PERFORM PRISM LOOKUP NAME command:
Details about PERFORM PRISM LOOKUP NAME are in a later chapter. [See 25.3.2.]
And after a PERFORM PRISM LOOKUP PROXY command, $STATUS will have one of these values:
These variables contain the ID, name, phone number, and email address of the current user, if he has gone through an ID/PIN prompt to identify himself.
This group of variables is also set when a temporary employee identifies himself by giving his name and confirmation code.
Details about identifying users by ID and PIN are in a later chapter. [See 25.]
The following is a summary of the minimum set of help records needed for Prism applications. "R" means that the record is required. To see this chart online in SPIRES, EXPLAIN HELP RECORDS, CHECKLIST.
[See 6 for general information about help records, 10.7 to read about helps for reports, 9.1.1 to read about helps for entry forms and screens.]
?WELCOME Welcome screen for your file (R)
<file-name> FILE Description of your file (R)
<indexterm> INDEX Help for each index (R)
<display-name> DISPLAY Help for each display (R)
?DISPLAY/<display-name> Context help for displays
?INTRO/REPORT/<report-name> Intro screen for report (R)
<report-name> REPORT General information on the report (R)
?REPORT/<report-name> Context help for report
?INTRO/FORM/<form-name> Intro screen for entry form (R)
<form-name> FORM General information on the form (R)
?INPUT/FORM/<form-name>/<step-id> Context help for each input screen
(*) in a form (strongly recommended)
?ERROR Single record explaining all
error codes for all input screens (R)
?INPUT/FILE/<step-id> Context help for input screens
(*) associated with file selection
?INPUT/REPORT/<report-name>/<step-id> Context help for input screens
(*) associated with the named report
(*) "Step-id" is the identifier of the screen, also known as "screen-id". It is the value used as follows in the protocol code generating the screens. This applies both to regular screens and to boxes overlaid on top of screens.
PERFORM PRISM SCREEN screen-id ID=id (if ID is present, use that for
your helps, otherwise screen-id)
PERFORM PRISM CHOOSE ID=screen-id
PERFORM PRISM PROMPT TEXT ID=screen-id
PERFORM PRISM PROMPT VALUE ID=screen-id
For an entry form installed with "automatic control", step-id is the value you enter in XSETUP FORMS to identify the "screen step" -- i.e. the name of the format frame called by Prism to generate the screen.
Protocol code to support Prism applications is stored inside Procs within protocols in the PRISM PROTO subfile in SPIRES.
The protocol's key is listed on the left; some possible uses of the protocol code are listed on the right.
Key Example Possible Uses
___ _______ _____________
* FILE * FILE Hidden search;
search steps
(protocol steps for
an index);
other tasks related
to file-selection or
file-exit.
* REPORT/<report-name> * REPORT/LABELS Hidden search;
statistics; other
tasks to support
reporting.
* FORM/<form-name> * FORM/MOD PROFILE Hidden search;
statistics; custom
data entry; other
tasks to support
data entry.
(Note: <report-name> and <form-name> are 12 characters maximum.)
[See 9 for more information on protocol processing steps.]
This appendix discusses command logging in Prism, and in particular discusses the following topics:
Checking the log for your application provides the following important benefits, among others:
- It provides the SPIRES error numbers for any errors that occur while your application is being used.
- It can help you measure the efficiency of your application -- e.g., the amount of CPU consumed in a typical use of a report or entry form.
The entries below suggest some ways you can measure your application's use of system resources. (By the way, although log entries include date and time, we've deleted that information below, in order to emphasize other parts of the log. Also, the figures shown below are fictitious.)
GG.USE*1P ... TESTFILE....../CS1 SEL: Test Orders (Contact: GG.ACE, ...
... CPU=0.2000,I/O=5,Min=1.00)
GG.USE*1P ... TESTFILE....../CE1 CMD: F6=CREATE
GG.USE*1P ... TESTFILE....../CE4 CMD: (Screen SCREEN1) F5=OK
GG.USE*1P ... TESTFILE....../CE1 CMD: (Screen SCREEN2) F6=SEND
GG.USE*1P ... TESTFILE....../CE1 SEN: Form=ORDERS,Cmd=CREATE, ...
... CPU=0.5144,I/O=32,Min=1.72,Scrn=2/2,Add=1,Upd=0,Rem=0
GG.USE*1P ... TESTFILE....../CE1 CMD: END
GG.USE*1P ... TESTFILE....../CS1 CLR: CPU=1.4384,Min=17.74, ...
... I/O=110 (TESTFILE)
GG.USE*1P ... TESTFILE....../CS1 DIS: BRIEF Cmds: 12 Records: 145
GG.USE*1P ... TESTFILE....../CS1 DIS: FULL Cmds: 6 Records: 8
GG.USE*1P ... TESTFILE....../CS1 END: CPU=1.5487,Min=18.19,I/O=130
Note the three letter code appearing in roughly the middle of every entry, SEL, CLR, SEN, DIS, etc.:
- A "SEL" log entry is generated every time someone selects your application, so counting these entries tells you the total number of times your file was selected within a given period.
- A "CLR" log entry is generated every time somebody either de-selects
("clears") your file or uses the PAUSE command to interrupt their Prism session
while selecting your file. Since Prism initializes the count for each CLR entry, you can
use it to determine how your application is using system resources. Adding up the
"CLR" entries in a day's log gives you a day's totals in resource use.
- A "SEN" log entry is generated after every successful data entry transaction (every "SEND") in your application. This entry provides important resource measurements for a particular entry form.
- A "DIS" entry is created after the "CLR" entry for each display used in the file during that session. The entries tell how many times the display was requested and how many records were processed using the display.
Errors in the log are marked by the tag "ERR:" as below. (For a fuller explanation of these tags, see further below.) Errors indicating that a basic task or command has failed are marked by a leading hyphen in front of the message that the end-user would see online:
TESTCATG/E1 ERR: Error in updating record 18-0-01: S260, E0, 16
TESTCATG/E1 ERR: -Transaction canceled by system error: S260, E0, 16
| |
(Message that the (SPIRES error
end-user sees) message number)
GO.BLI*2T 10/19/86 10:36:34 TESTCATG......../CS1 SEA: St=0,Res=22, FIND ... | | | | | | | (A) (B) (C) (D) (E) (F) (G)
(A) -- account (including number for multiple logon account after asterisk)
(B) -- version (P=Production, T=Test, N=Preprod, O=Old)
(C) -- date
(D) -- time
(E) -- file-id of selected file (padded with periods if necessary to make up the 16-character maximum)
(F) -- represents mode (G = Guided, C = Command), activity (S = Search or none, R = Report, E = Entry), and path (0 = no file selected, 1 = primary file, 2 through 9 = secondary file)
(G) -- the different entries in (G) are described in the next few pages.
The WEL and SES log entries together indicate the start of a Prism session. The SES entry contains identifiers such as the Milten internal session tag, the WYLBUR/TESTWYL indicator, front-end port identifiers and Internet address ID. If the user has started a session in which he has identified himself by University ID, his name and ID ($UnivName and $UnivID) are included in the WEL entry. Otherwise the name associated with the logged-on account is shown.
Tells what command the user issued. The command is preceded by "Fn=" if a function key was used to issue the command. The log entry will indicate if the user was "timed out" before the command was completed. If the command was automatically supplied by Prism, the word "Supplied" appears as part of the entry. For instance, if you asked for an automatic GET to be issued after a search result of one record.
CMD: (Supplied) GET 1
Similar to CMD above, except that the user is viewing a menu (e.g., for form-selection or report-selection).
Records the screen that the user visited.
Shows the message given when a command syntax error occurs.
The end-user has issued the BEGIN command to begin a brand new Prism session. The CPU, elapsed time, and I/O shown are cumulative from the initial Welcome to Prism. Elapsed time is labeled with either "Min= " or "Sec= '.
The user is ending his or her Prism session via the END command or one of its synonyms. The CPU, elapsed time, and I/O shown are cumulative from the initial Welcome to Prism.
The user has issued the PAUSE command. Statistics are recorded here in case the user does not return to Prism. The CPU, elapsed times, and I/O shown are cumulative from the initial Welcome to Prism.
The end-user has issued the SELECT command and successfully selected a file. The log displays the file's name, as it appears on the Select menu, as well as the contact account of the person responsible for the application.
The end-user has either de-selected your application or issued the PAUSE command. In either case, the statistics shown for CPU, elapsed time, and I/O are cumulative from the point when the user first saw the Welcome to Prism screen.
After a CLR log entry, one or more DIS entries are generated to give information about the displays used during the session. The entry includes the display name and a count of how many times the display was requested and how many records were processed using the display.
After the end-user performs any search, including one with a zero result, "St" above will display the value for $SRCHSTAT, normally a zero. "Res" will display the current result count. For more information on the SPIRES variable $SRCHSTAT (not to be confused with $SRCHVAL), see the document "SPIRES Protocols".
Indicates successful selection of named form. The statistics apply to setting the entry form only (plus processing initial parm screens), not using the entry form.
Indicates successful selection of named report. The statistics apply to setting the report only (plus processing initial parm screens), not using the report.
Indicates a DISPLAY REPORT command, and shows the number of records processed as well as CPU and elapsed time. The "report type" will be either "Developer report" or "Personal report". For personal reports, the log entry will also indicate whether the report was processed via direct record access, a display set, or a SPISORT set.
After any system error. The message depends on the error and matches the error message shown to the user within Prism. The final four numbers are values of the SPIRES system variables $SNUM, $PSNUM, $ENUM, and $MNUM. ($PSNUM only appears when it has a value.) For instance:
...: S280 (PS198), E0, 0
(This example shows how useful $PSNUM can be: the explanation for S280 tells you to check the previous diagnostic for more information -- and that diagnostic is available through $PSNUM.)
A HEL log entry is generated for any successful or unsuccessful HELP command issued by a user. The "context" gives information about what the user was doing at the time of the HELP command. For an unsuccessful HELP command, the log entry reads "No help for <term>".
These entries occur when a SEND or CANCEL command is issued for an entry transaction. Both include the following information:
The value of "Cmd" will be either CREATE or GET. In addition, "Scrn" records how many screens were involved and how often they were seen (the two numbers would be equal if there were no reprompts). "Add", "Upd" and "Rem" tell how many actual add, update, and/or remove requests were performed in SPIRES during the transaction.
These entries mark respectively the add, update or remove of a record in SPIRES.
Indicates the user is sorting the search result using the fields listed. (In parentheses the log lists the SPIRES elements corresponding to the fields.)
The SET log entry records resources used in a SETUP transaction. "object-type" indicates what type of SETUP was done: SEARCH, SORT, REPORT, TASK, FIELD, PRISM. The UPD entry shows the key of the definition record (e.g., the Personal Report definition) that was updated (not applicable for SETUP SORT or SETUP PRISM).
The XST log entry records resources used in an XSETUP transaction. "object-type" indicates what type of XSETUP was done: PROFILE, FORMS, REPORTS, etc. The UPD entry shows the key of the record (e.g., the Prism Profile) that was updated.
Indicates a PRINT (or MAIL or SAVE) request from the Prism PRINT screen. "What" is either "REPORT", a display-name or a help record. (The log will go on to name the report or display but not the help record.) WHEN values correspond to the print options screen: 1=now, 2=overnight, 3=non-peak.
The log entries for SEL, BEG, END, PAU, CLR, SEA, SEN, SOR, PRI, MAI, and SAV include an indication of the CPU time, I/O, and elapsed time used for the commands. The elapsed time portion of the entry is labeled either "Min= " or "Sec= " depending on the unit of measurement used.
The PERFORM PRISM LOG command causes an additional entry to be written to the Prism log for your application, besides the normal entries logging your end-users' sessions. It can help you preserve more complete information and/or error diagnostics on Prism transactions than standard logging provides.
You do not need to write special log entries for most Prism transactions. PERFORM PRISM LOG is for special cases -- it might be useful, for instance, in a Prism application performing a behind-the-scenes transaction in a SPIRES file that is not installed in Prism.
The syntax for PERFORM PRISM LOG is:
PERFORM PRISM LOG, {MESSAGE='text' | ERROR='text'}
The MESSAGE (or MSG) option causes Prism to write the text you specify into the log. For instance, after a successfully added record behind the scenes:
/PERFORM PRISM LOG, MESSAGE='$Key added to Audit subfile' The result in the log would look as follows if the key were 1734B: ... MSG: 1734B added to Audit subfile
The ERROR option causes the specified text to be written to the log, but in addition Prism appends the current values of the SPIRES variables $SNUM, $ENUM, and $MNUM to the log entry. For instance:
/PERFORM PRISM LOG, ERROR='Error adding record #Newkey to Statistics file' The result in the log would look roughly as follows: ... ERR: Error adding record 1557 to Statistics file; S413, E0, 0
Prism treats error entries created with PERFORM PRISM LOG the same way that it treats error entries that it logs on its own -- for instance, they cause an error notification to be sent to the application's contact account.
Prism system installation is phased to ensure that all new features have been thoroughly tested before they are made available to production applications. The Prism change control procedures closely parallel those used for installing changes in SPIRES.
The point of the change control procedures is to protect your application from unexpected changes in the way Prism operates; and to provide a clear-cut method for you to test new Prism features without jeopardizing your production application.
The Prism interface will always operate in several different "versions". The thoroughly tested "Production" version is changed only for emergency bug fixes, during the period between new Prism releases. Other versions, such as "Test", may be used to test how new Prism features will affect your application.
Here are the versions of Prism, listed in order from the newest and least tested to the oldest system.
Each of these versions are described further in the upcoming paragraphs.
The PRISM command takes you to the production version of Prism. To access other versions, add the version to the PRISM command, in parentheses:
Command> prism(test)
The "version" can be PRODUCTION, TEST, PREPRODUCTION, or OLD, and all these values can be shortened to a single character except PREPRODUCTION, which requires 3 characters.
Here is detailed information about each version. Once again, the versions are listed in order from the most recent to the oldest.
The Development version is where Prism changes are first introduced for internal testing by SDC staff.
In function Prism(D) corresponds to the the GQ.TES system in SPIRES and, in fact, runs in GQ.TES SPIRES so that problems at both the SPIRES level and the Prism level can be investigated. Unlike later versions of Prism, Development is not separately "linked". (A "linked" program runs in an unchanging copy of SPIRES, whereas GQ.TES is updated and enhanced daily.) This could conceivably lead to memory management problems for long sessions that select different files. Development is rebuilt as often there are new changes ready for others to see, so it could conceivably change on a daily basis, as we install enhancements.
The Test version is built as often as needed (in some cases as often as once a week) from the Development version described above. It will be a separately linked processor, running in a stable version of SPIRES -- usually production SPIRES, but occasionally GG.TES SPIRES when new SPIRES features are needed. The Test version of Prism should always be stable enough for applications developers to use for their own testing, or to take advantage of bug fixes and new features. The Test version should not be used for production applications or in critical situations. Thus Prism end-users should never be directed to use PRISM(T) for their work.
As with the GG.TES version of SPIRES, you should exercise this system as much as you can in order to make sure the version is stable before it is shifted to Pre-production and Production.
At least one week (and usually two weeks) before any new release of a production version of Prism, the existing, problem-free Test system is frozen and made available in a Preproduction version. Like the GQ.PRD version of SPIRES created before a new SPIRES release, Preproduction Prism should be used for critical applications testing prior to a new Prism. After the testing period, which usually lasts two weeks, the Preproduction version becomes the new Production version of Prism and the previous Production version is stored elsewhere as a backup system, as described further below.
Note that the Preproduction version is only available during the period just before a new Production Prism, unlike the other versions listed here, which are available on an ongoing basis.
At the same time that the Preproduction version of Prism is installed, a notice will be sent out to anyone responsible for a critical application. (A "critical" application is any application that members of the Stanford community depend upon to get their work done.) It's important that developers responsible for critical applications test any new Prism features thoroughly before this version of Prism becomes Production. In fact, every Prism developer is urged to test this version as thoroughly as possible, within its short window of availability.
The Production version of Prism is simply the Preproduction version upgraded to Production status after the critical application testing period. Since it will have passed through all the stages of testing described above, it should be extremely stable -- so this is the version in which production Prism applications should run. All the same people who received notice of a new Preproduction system will likewise receive notice of the new Production version.
Despite rigorous testing, in rare cases a problem may escape detection before it has entered the Production version. Emergency fixes will be dealt with as they arise, and in extreme cases will be applied directly to the Production version; less critical fixes will be moved rapidly through the development/test/production cycle. Anyone on the preceding notifications list would also be notified of emergency changes.
Each time a new Production version is released, the previous Production version is renamed, and made available as the OLD version of Prism. You may never need the Old version at all, but in special situations it can be used to diagnose the history of a problem with a Production application; it can also serve as a backup system if something goes wrong with the current Production Prism. As the previous Production Prism migrates to become the Old version, the previous Old version will be discarded.
ADD PROFILE prompts you for the category or categories appropriate for your Prism application, and MOD PROFILE lets you change these categories if you want. Below are the categories currently in use at Stanford, along with brief descriptions. Your application will appear on the SELECT menu under the category or categories you name. You may list your file in several categories, if appropriate.
FINANCIAL Files relating to finance and accounting STUDENT/ACADEMIC Student and academic records PERSONNEL Personnel information FACILITIES Physical facilities MAIL/COMMUNICATION Mail and communications ONLINE FORMS Applications that create and route forms MISCELLANEOUS Files not fitting in the other categories APPLICATION DEV. Files to help Prism application developers
These explanations are available within Prism Profile as well, when you type HELP CATEGORIES.
An additional category, CLASS APPLICATIONS, includes applications sponsored by the CLASS program (Cooperative for Linked Administrative Systems at Stanford). You must contact Data and Technology Resources staff to have an application designated as a CLASS application.
This chapter covers several topics related to identifying users of your application and looking up and validating names:
- An overview of how University IDs and PINs are used in online systems. [See 25.1.]
- A simple technique to create a standard identification screen (with PERFORM PRISM PROMPT NAME PIN). [See 25.3.1.]
- How to identify users if you create a custom identification screen (with PERFORM PRISM LOOKUP NAME and PERFORM PRISM PROMPT PIN). [See 25.3.2, 25.3.3.]
- Specific coding recommendations and sample protocol code for applications using PERFORM PRISM LOOKUP NAME, including ways to ensure that your user identification protocol steps will work reliably when executed as part of a Prism task. [See 25.4.]
- How to look up information associated with a University ID, using system variables such as $UNIVID or $UNIVNAME or using the $LOOKSYS function to look in the University ID file. [See 25.5.]
- Proxy identification and work groups (applicable to forms routing applications). [See 25.6.]
- Temporary IDs -- how they differ from regular IDs and what your application needs to know about them. [See 25.7.]
- What to know about users who enter Prism without having a Forsythe computer account. [See 25.8.]
People affiliated with Stanford are assigned 8-character Stanford ID numbers. These numbers are printed on staff and student ID cards. As the need arises, a person may also be assigned a PIN (Personal Identification Number). Authorized staff in Human Resources and the Data Center inform people (staff and faculty) of their initial PIN assignment and advise the recipients to choose a new PIN known only to themselves before the ID and PIN is used for the first time. Anyone can change their PIN by using the MOD PIN entry form in the Personal Profile file in Prism.
PINs for students are assigned by the Registrar's Office. Students use ID/PIN identification in Axess, which is a student information system available through Folio. Students (and others) may use the SET PIN command in Folio in order to change their PIN.
University ID numbers, while unique to an individual, are not considered private numbers. PINs are, by University policy, supposed to be confidential and known only to the ID holder. See Administrative Guide Memos #36 and #64. (PINs are encrypted and stored separately from the University ID database.) The combination of an ID and its associated PIN constitutes a secure and authorized identification of a person. In the context of a Prism transaction involving University forms, when a person identifies himself by ID and PIN, this constitutes an "electronic signature".
Here are some examples of how IDs and PINs are used in computer systems at Stanford.
In Prism, IDs and PINs were first used in applications whose purpose is to create transactions based on University forms and requiring signature approval (purchase requisitions, journal entries, personnel actions, etc.). "Forms routing" applications make use of a Prism facility for creating a routing list for an electronic form transaction and routing it for electronic signature.
[The specialized tools for building routing applications are described in a separate manual called How to Install a Routing Application in Prism.]
Forms routing applications usually require ID/PIN identification of the originator (creator) of a form transaction.
When names are entered on the routing list for a forms transaction, Prism verifies that each name matches a University ID in the database, and also that the ID has a PIN. If necessary, "name resolution" occurs -- that is, if several names associated with University IDs can be construed to match the name given by the form originator, he must choose the right one. [See 25.2 for details of the name matching process.] Prism stores the routing list as a list of IDs. Your application can look at the routing list and check an authority file or do other data integrity checks to make sure that the form is routed to the right person.
People approving forms transactions must give their ID and PIN in order to affix their electronic signature to the transaction. Forms approval is done in the Forms Action file in Prism.
Your application may wish to look up names either to identify the current user, or to verify that a name entered by the current user as a data element in the transaction is for a valid Stanford affiliate.
There are a couple of variations:
- You can prompt the user for his name or University ID and then his PIN. This securely identifies the current user of your application.
- You can look up a name to see if it can be matched with a currently active ID, without prompting for PIN. This is appropriate when you're asking a user for a name not his own that needs to be validated. Or if you don't want to require people to have a PIN to use your application, you could prompt for the user's own name, validate it, but skip the PIN prompt.
Note that if you skip the PIN prompt, there is nothing to prevent someone from typing the name of any Stanford affiliate and claiming to be that person.
- You can specify certain segments of the University ID database for the name lookup -- IDs that have PINs (and are thus eligible to have forms routed to them), temporary IDs, or IDs for work groups. [See 25.7 for an explanation of temporary IDs, 25.6 for information about work groups, 25.8.]
You may control access to components of your application (indexes, reports, entry forms, displays, reporting fields) by means of University IDs, if you wish. And you may use IDs to control who can select your file in Prism. [See 4.1.2a.] This is an alternative to using Spires accounts (which may change over time for any given individual) to control access.
To do this, you must create a SPIRES access list containing University IDs. [See 4.] or [EXPLAIN ACCESS LISTS, FOR SUBFILE SELECTION.] Then, in the places in Prism Profile where you are asked for accounts or access lists, you may name this ID-based access list. In order for this to work, you must identify the user of your application by University ID (that is, $UNIVID must be set).
This section explains how Prism does name matching when it looks up names in University ID file. This applies to identification processes that you might build into your Prism application with commands such as PERFORM PRISM PROMPT NAME or PERFORM PRISM LOOKUP NAME. It also applies to name lookups on the routing screen, and name lookups during identification processes in EMS (when forms are signed via EMS).
Prism's name matching is based on the normal SPIRES personal name algorithm, with a few variations. The flexibility that SPIRES' name matching offers (which was originally designed for bibliographic information retrieval applications) is in retrieving names that MIGHT be the one you are looking for. The method for accomplishing this is that forenames in search values are compared to forenames in the index. They are counted as a match if they match through the length of the shorter string. The surnames have to match exactly, unless explicit truncation via # is allowed. (EXPLAIN PERSONAL NAME for more details.)
For example:
you enter matches on
--------- ----------
philip roth philip roth
philip g roth
g philip roth
p m roth
timothy p roth
phil george roth
philippa ann roth
Prism introduces the concept of "weak match" and "strong match" of names.
A strong match is either:
- An exact match between the search value and the index value (for forenames)
- Search value is a substring of the index value (for forenames)
For example, GREG SMITH is a strong match to GREG SMITH and GREGORY SMITH.
A weak match is counted when:
- The index value is a substring of the search value (GREG to G, PAULA to PAUL)
For example, GREG SMITH is a weak match to G SMITH, PETER G SMITH, etc. PAULA is a weak match to PAUL and P. GREGORY is a weak match to GREG and G.
There are two behaviors involving weak and strong matches:
a) Single weak match verification (introduced around December 1990)
When Prism finds only a single "weak match" to the name entered, it presents a box asking you to verify that the name found is the one intended. For example:
Enter your Name or University ID: jimmie_sinclair____________
*--------------------------------------------------------------------*
| JIMMIE SINCLAIR was not found in the directory of University IDs. |
| The following is a close match: |
| |
| Sinclair, J L (Lynne Sinclair, Data Center) |
| |
| Is this the one you want? |
| |
| f4=No f5=Yes |
*--------------------------------------------------------------------*
b) Single strong match takes precedence (introduced June 1993)
The problem that this tries to solve is a situation where there is an exact match between a search value and an index value, but also one or more weak matches. In this case, Prism presented a name resolution menu that to the casual observer doesn't make much sense. For example:
*--------------------------------------------------------------------* | There are 2 names like BOB PHILLIPS. | | | | _ <-- Choose a name by entering a number from the list below. | | 1. Phillips, Robert W (Bob Phillips, Data Center) | | 2. Phillips, Susan B (Networking/Communication Sys) | | f5=OK f9=Cancel Box | *--------------------------------------------------------------------*
The new behavior added in June 1993 is that if there is a single strong match, plus one or more weak matches, the strong match will take precedence and no name resolution menu will be presented. In the example above, if "Bob Phillips" is entered, it will match exactly on name #1 above and you will not get that menu.
Here are some other examples of name resolution menus that will no longer be presented under this new rule.
There are 3 names like ANNE HARRINGTON.
1. Harrington, Barbara A
2. Harrington, Frances A (Anne Harrington, Business Info Sys
3. Harrington, Melissa Ann (Student)
now: ANNE HARRINGTON matches exactly with #2
....................................................................
There are 2 names like PAULA SCHARTZ.
1. Schwartz, Edward Paul (Student)
2. Schwartz, Paula M (ps, Business Info Sys Applications)
now: PAULA is weak match to PAUL; the strong match to PAULA is used.
In summary, name resolution menus are presented in these cases:
- there are multiple strong matches (with or without weak matches)
- there are multiple weak matches
but name resolution menus are not presented if:
- there is a single strong match and single/multiple weak match(es)
- there is a single weak match (but you get "weak match verification" box)
If multiple forenames are in the search value, there must be multiple names in the index value, in the same order, in order to match at all. (This is parallel to the SPIRES name searching rules.) Each forename is evaluated separately to determine whether there is a strong or weak match. Any strong match in the forenames will cause the name as a whole to be considered a strong match.
Some examples of cases where you do still get name resolution menus:
There are 3 names like ANN HARRINGTON.
1. Harrington, Barbara A
2. Harrington, Frances A (Anne Harrington, Business Info Sys
3. Harrington, Melissa Ann (Student)
(ANN is a strong match to both ANN and ANNE.)
....................................................................
There are 3 names like GREG SMITH.
1. Smith, Gregory M (Greg Smith, Data Center)
2. Smith, Gregory Robert
3. Smith, Peter G (Psychology)
(GREG is strong match to both GREGORYs, even though there's
an exact match in #1.)
....................................................................
There are 4 names like B PHILLIPS.
1. Phillips, Barbara Yvonne
2. Phillips, Cindy Belle
3. Phillips, Robert W (Bob Phillips, Data Center)
4. Phillips, Susan B (Networking/Communication Sys)
(B is a stong match to BARBARA, BELLE, BOB, and B.)
To identify a person securely, your application prompts the user to enter his name or Stanford ID number and then to enter his PIN (Personal Identification Number). When a name is entered, your application instructs Prism to search the database of University IDs. If multiple names are found that match the name given by the user, he is prompted to choose the right name. When the PIN is entered, Prism verifies that the PIN typed by the user matches the encrypted PIN stored for that ID.
The following PERFORM PRISM commands help you determine a person's University ID and to prompt for and validate a PIN:
- PERFORM PRISM PROMPT NAME, PIN: This command creates a standard screen prompting for a name and PIN, without your having to write a SPIRES format. You may also omit the PIN prompt from the standard identification screen, if it is sufficient for your application to look up a name in the University ID file.
- PERFORM PRISM LOOKUP NAME: This command looks up a name in the University ID database. Options on the command let you include name resolution in the process or determine what types of IDs are looked up (for example, all active IDs or just IDs that have been assigned PINs).
- PERFORM PRISM PROMPT PIN: This command prompts for the user's PIN, once an ID lookup has been successful.
- PERFORM PRISM LOOKUP PROXY: Used in forms routing applications, this command lets you determine whether one person has been authorized to sign forms or take action on behalf of another. [See 25.6 for an explanation.]
There are two methods to do this user identification:
- The simplest is to use PERFORM PRISM PROMPT NAME, PIN to invoke the standard identification screen, either when your file is first selected, or perhaps when a report or entry form is chosen.
- Alternatively, you can create your own screen, on which you ask for the user's name. Then your protocol code can use PERFORM PRISM LOOKUP NAME to match the name with a valid ID, and then PERFORM PRISM PROMPT PIN to prompt for the PIN.
Here is an example of the identification process. These two screens are generated by the PERFORM PRISM PROMPT NAME, PIN command:
NSI Gr.Appl 10/17/91 16:41
Personal Identification
---------------------------------------------------------------------------
Enter your Name or University ID:
Lindsey_Clayton__________________
Type: OK to continue file selection. CANCEL to cancel file selection.
UNDO to discard changes to page.
YOUR RESPONSE:
f1=Help f5=OK f7=Undo f8=Cancel
Prism prompts a name in the entry field, based on either the WYLBUR account name or if present, the current value of $UNIVNAME.
After an OK command, the PIN prompt occurs in a box overlaid on top of the main screen:
NSI Gr.Appl 10/17/91 16:41
Personal Identification
---------------------------------------------------------------------------
Enter your Name or University ID:
Lindsey_Clayton__________________
*---------------------------------------------------------------*
| (Lindsey Clayton) Enter your PIN: ********* |
*---------------------------------------------------------------*
-Enter your PIN above, then type OK below to continue
Type OK below to validate your PIN.
Type CANCEL to cancel file selection.
YOUR RESPONSE:
f1=Help f5=OK f8=Cancel
This simple protocol will provide this identification screen at the time your file is selected:
* FILE declare noparms ++identify perform prism prompt name, pin tempok return
The DECLARE NOPARMS statement tells Prism that there are no variables to be stored for use in Prism tasks. (Without a DECLARE statement of some form, the SETUP TASK command could not be used in the application.) [See 10.8.]
The TEMPOK option allows people with temporary IDs to identify themselves. [See 25.7.]
The only other step required is to specify in XSETUP PROFILE that you have a processing step at file-select time:
Enter 'Yes' to see screens to add, modify, or delete processing steps. - when the subfile is selected or cleared: Yes
Then, enter the step id (corresponding to the proc label in the protocol):
Processing steps for when file is selected:
STEP# STEP ID TYPE TITLE/COMMENT
1 IDENTIFY_ P Identification______
2 ________ _ ____________________
3 ________ _ ____________________
(To install this identification parm screen when a report or entry form is selected, put the PERFORM PRISM command in a REPORT/report-name or FORM/form-name protocol and install the processing step in XSETUP REPORT or XSETUP FORM.)
You can use PERFORM PRISM PROMPT NAME without the PIN prompt (i.e. without the PIN option on the command) in order to invoke the standard identification screen for the purposes of looking up the name in the University ID file only. In this case, Prism will look up the name and prompt the user if multiple matches are found, but no PIN prompt will follow. The only way the user can proceed from this screen is to enter or choose a name found in the University ID file.
Note that this interaction without the PIN prompt does not securely identify the user, since all that's needed to get past the screen is to know the name of someone in Stanford's University ID file.
PERFORM PRISM PROMPT NAME [PIN]
[PROXY]
[PREVIOUS = 'command']
[ID = screen-id]
[TITLE = 'screen title']
[TEMPOK]
[TEXT = 'text']
[SEARCH = 'population, population, ...']
When PERFORM PRISM PROMPT NAME, PIN is successful, Prism sets the variable $UNIVID to the University ID of the currently logged-on user, where you can access it if needed. The user's full name, phone number, and electronic mail address are returned in the variables $UNIVNAME, $UNIVPHONE, and $UNIVEMAIL, respectively.
If the PIN prompt is not used, none of the identification variables $UNIVID, $UNIVNAME, $UNIVPHONE, $UNIVEMAIL are set, cleared, or changed.
The $PARM variable will contain the University ID and name, concatenated with a slash, as below:
01234567/John Smith T0000123/Mary Brown (a temporary ID) STORES/University Stores (a work group)
The $STATUS variable may contain the following values if the name entered is not unique or not found in the University ID file.
$STATUS value Explanation
------------- ------------------------------------------
'NOTFOUND' The name or ID entered was not found
in the directory.
'MULTIPLE' The value was not unique (and name
resolution did not occur). This would
happen if the user issues the CANCEL BOX
command from the name-resolution box
without making a selection.
If the PROXY option (and the PIN option) is used, then the $PROXYID variable is set to the University ID of the person for whom the logged-on user is acting, and $PROXYNAME, $PROXYPHONE, and $PROXYEMAIL contain the person's name, phone number, and email address. [See 25.6 for more about proxy identification.]
You may need to create your own parm screen on which you prompt for a person's name and also for other information needed for your application. In this case, you can write format frames as usual for the parm screen and then use the PERFORM PRISM LOOKUP NAME and PERFORM PRISM PROMPT PIN commands in the protocol associated with that parm screen.
PERFORM PRISM LOOKUP NAME looks up an input string that you provide (either a name or an ID) and verifies that the value is found in the University ID directory.
Details of the syntax are below. See also the later section that has a few examples of protocol code for user identification and name lookups. [See 25.4.]
PERFORM PRISM LOOKUP NAME = 'input string'
[RESOLVE]
[SEARCH = 'population, population, ...']
[TEMPOK]
[UNIVID]
[PROXYID]
[GROUPS]
The value to be looked up must be either a name or a University ID.
Although RESOLVE is optional, it's recommended that you include it. RESOLVE tells Prism that if multiple matches are found in the University ID directory for the input string, the user should be prompted to select a specific name from a menu of choices.
If you use RESOLVE, it's also recommended that you use the UNIVID option (see explanation below).
By default (i.e. if you omit the SEARCH option) Prism searches all active IDs that have PINs (excluding temporary IDs).
Instead, you may specify explicit segments of the University ID population that should be searched. Possible populations are:
Note that name lookups from the routing screen happen within the SIGNERS population. Name lookups from the standard identification screen generated by PERFORM PRISM PROMPT NAME, PIN happen within the PINS population (unless the SEARCH option is used to specify otherwise).
The SEARCH=TEMPS option was implemented for Prism's own use in allowing access to Prism services by temporary employees, and it's unlikely that you would need to use the SEARCH=TEMPS option in your own application code.
Temporary employees are instructed to type "temp" as their name when identifying themselves on Prism screens. In your LOOKUP NAME command, if "temp" is the string being looked up, Prism intercepts the lookup and branches to a routine that prompts additional input fields to identify a person with a temporary ID.
The TEMPOK option is a "switch" that instructs Prism to take this special action when the name "temp" is encountered in a LOOKUP NAME command. Your code doesn't have to do anything special -- it just has to tell Prism that it's ok to do so. In the absence of a TEMPOK option, the string "temp" in your LOOKUP will produce a message telling the user that the file is not available for temporary employees.
This switch was implemented so that an application can explicitly allow or disallow access by temporary employees. The intent is that temps should be excluded only rarely, but the switch is a safeguard in case your application is not prepared to deal with the form of IDs assigned to temporary employees (IDs that begin with a "T" instead of being all numeric).
The GROUPS option (PERFORM PRISM LOOKUP NAME ... GROUPS) tells Prism to search among work group names as well as the default ID population (or the ID population you specify with the SEARCH option). [See 25.6 for a definition of a work group.] The GROUPS option is used in routing applications, in particular when you want to provide an "Acting for" field on your identification screen, for the user to indicate that he is working on behalf of another person or as part of a work group.
Here is a graphic representation of the different populations of the University ID file that you may search with PERFORM PRISM LOOKUP NAME:
normal, active IDs
------------------------------ ---------- ---------------
| ACTIVES | | | | inactive IDs |
| (all active IDs) | | TEMPS | | |
| | | (active) | | |
| ------------------------ | | | ---------------
| | PINS | | ----------
| | (IDs with PINs) | |
| | | |
| | ------------------ | | ---------------
| | | SIGNERS | | | | GROUPS |
| | | (enabled for | | | | (work groups) |
| | | routing) | | | ---------------
| | ------------------ | |
| | | | GROUPS option simply
| ------------------------ | adds "work groups"
------------------------------ to whatever
population is
being searched
TEMPS have IDs that start with "T".
Although inactive IDs are not searchable with LOOKUP NAME,
you may still use $LOOKSYS for those IDs to retrieve the
associated name, etc.
The UNIVID option causes name resolution to be bypassed if the current value of $UNIVNAME matches exactly the input string being passed in the NAME parm of the PERFORM PRISM LOOKUP NAME command being executed. If you use the RESOLVE option, it's recommended that you also use UNIVID.
UNIVID is useful when you are using LOOKUP NAME to identify the current user, but is not appropriate when you are using it to look up names otherwise (e.g. to validate a name listed by the current user when you ask for a supervisor's or approver's name).
The UNIVID option makes your LOOKUP NAME command a little smarter, in that it eliminates unnecessary name resolution screens during the second and subsequent times that a person identifies himself in a Prism session. When a person first identifies himself, $UNIVID, $UNIVNAME, etc. are set, and those variables retain their values even if the user moves to a different file. On the second identification, it is highly likely that the name the user types will match the $UNIVNAME value set earlier, and that it is safe to assume it is the same person identifying himself. Name resolution menus are bypassed, and you can proceed to prompt for the PIN. (You still should prompt for a PIN, by policy, even if you make these assumptions about how the user's name and $UNIVNAME compare.)
One thing that helps this work smoothly is if you prompt a value in your "Name" field on your identification screen, when possible. The first time identification happens, you can prompt a name from the user's WYLBUR account name. The next times, when $UNIVNAME is set, you can prompt the $UNIVNAME value. If you do this, the user can simply issue the OK command to proceed, without having to type a name.
If you prompt the WYLBUR account name, be sure to parse the value to omit extraneous strings like phone numbers. Later in this chapter, in the sample protocol code, there is some code that you can use to accomplish this. [See 25.4.]
Note that Prism uses these techniques -- bypassing name resolution the second time around, and prompting $UNIVNAME or the WYLBUR account name -- when you use PERFORM PRISM PROMPT NAME (the standard identification screen). In this sense, the UNIVID option makes LOOKUP NAME behave like PROMPT NAME.
Another reason to use the UNIVID option is to make your protocol code work reliably when it is executed in the batch, as part of a Prism task definition. Name resolution screens cannot happen in a task, since screen prompts don't happen when your protocol runs in the batch. [See 10.8 for more about protocol code used in tasks.]
PROXYID is similar to UNIVID, except it applies to name lookups for "proxy" identification. [See 25.6.]
The PROXYID option causes name resolution to be bypassed if the current value of $PROXYNAME matches exactly the input string being passed in the NAME parm of the PERFORM PRISM LOOKUP NAME command being executed. As for UNIVID, it's recommended that if you use the RESOLVE option during a name lookup for proxy identification, you should use the PROXYID option too.
After PERFORM PRISM LOOKUP NAME, the $STATUS variable is set to null if a name was found successfully. There are two ways this can happen: if the lookup finds a single match in the directory; or, if multiple names were found and the user chose a single name during name resolution. (Name resolution occurs if you included the RESOLVE option on PERFORM PRISM LOOKUP NAME.)
In both cases, the $PARM variable contains the University ID and name, concatenated with a slash, as below:
01234567/John Smith T0000123/Mary Brown (a temporary ID) STORES/University Stores (a work group)
If the command fails, $STATUS can tell you why:
$STATUS value Explanation
------------- -----------------------------------
'NOTFOUND' The name or ID in the input string
was not found in the directory
'MULTIPLE' The value was not unique (and name
resolution did not occur)
A $STATUS value of MULTIPLE occurs in two situations. The first case is when the PERFORM PRISM LOOKUP NAME command does not include a RESOLVE option and the input string is not unique. The second situation is when the user issues the CANCEL BOX command from the name-resolution box without making a selection.
Note that PERFORM PRISM LOOKUP NAME does not set the $UNIVID or $PROXYID variable. $UNIVID (and associated variables) is not set until a successful PIN prompt occurs.
After prompting the current user for his name or University ID and looking it up with PERFORM PRISM LOOKUP NAME, use PERFORM PRISM PROMPT PIN to prompt him for his PIN.
PERFORM PRISM PROMPT PIN [UNIVID=n] [PREVIOUS='command']
Immediately before the PIN prompt, Prism clears any previously set $UNIVID or $PROXYID (and associated variables like $UNIVNAME). Then, if the PIN prompt is successful, $UNIVID is set to the University ID of the currently logged-on user. The user's full name, phone number, and electronic mail address are returned in the variables $UNIVNAME, $UNIVPHONE, and $UNIVEMAIL, respectively.
Note that if you are doing proxy identification, you should prompt for the PIN before doing the PERFORM PRISM LOOKUP PROXY. Procedurally, the reasoning for this is that you should identify the user before displaying possibly confidential information such as who can sign for whom. Technically, the reason is that although PERFORM PRISM LOOKUP PROXY sets $PROXYID $PROXYNAME, $PROXYPHONE, and $PROXYEMAIL, if you subsequently prompt for a PIN, the $PROXY variables will be cleared by Prism. [See 25.6 for more about proxy identification.]
During PIN prompting, Prism protects any unprotected field on your screen and uses the lower part of the data area of the screen for the PIN prompt. The end-user has four chances to enter the valid PIN; after three invalid attempts, Prism issues a warning, and after a fourth invalid attempt terminates the Prism session. There's also an automatic timeout after two minutes of inactivity during PIN prompting.
These examples illustrate how to use PERFORM PRISM LOOKUP NAME and PERFORM PRISM PROMPT PIN (along with PERFORM PRISM SCREEN and a format) to identify users of your application on an identification screen of your own design.
Remember that if you can use Prism's standard identification screen, generated by PERFORM PRISM PROMPT NAME, PIN, your protocol can be much simpler. [See 25.3.1.]
This is a fairly simple identification protocol. Its features are:
- A value is prompted for the user in the name field on the identification screen.
- Name resolution is supported, and the DECLARE PARMS statement and the UNIVID option on the LOOKUP will let the protocol work in Prism tasks.
- The application allows access by temporary IDs (the TEMPOK option).
- It uses the same MN and NN error codes and messages as Prism's identification routines.
* FILE
DECLARE PRELOAD
VGROUP orv.ab.cde.identify
DECLARE PARMS USERID
DECLARE SCREEN IDENTIFY
on command OK, proc Lookup.Name
++Get.Name
; This proc determines a value to be prompted in the name field
; on the identification screen.
; Prism uses $UserName similarly in its own identification routines.
; The #UserName value will be prompted on the screen in the "Name"
; field by the format.
if $UnivName then let UserName = $UnivName
else begin
let Temp = $CHANGE($UserName,' -',':')
let UserName = $SQU($BREAK(#Temp,'(:;1234567890'))
if $XSTR(#UserName,KEEP,LAST,1) = '/' \
then let UserName = $SQU($XSTR(#UserName,DROP,LAST,1))
endb
++Identify
PERFORM PRISM SCREEN IDENTIFY TITLE='Identification' OK
; The format reads the value in the name field and puts it
; in the #UserName variable.
; When the OK command is issued, the Lookup.Name proc will be
; executed.
++PIN
/PERFORM PRISM PROMPT PIN UNIVID=#UserId PREVIOUS='Jump IDENTIFY'
Return
++Lookup.Name
; This proc is executed during an ON COMMAND OK event.
/PERFORM PRISM LOOKUP NAME="#UserName" RESOLVE UNIVID TEMPOK
if $STATUS = 'NOTFOUND' then begin
PERFORM PRISM SET ERROR 'NN' AT 6,1
/set MsgLine = 'NN: The name #UserName does not have an active \
ID and PIN'
set STATUS = 'REPROMPT'
endb
else if $STATUS = 'MULTIPLE' then begin
PERFORM PRISM SET ERROR 'MN' AT 6,1
/set MsgLine = 'MN: Multiple names like #UserName found; \
please use a more complete name'
set STATUS = 'REPROMPT'
endb
else begin
Let UserId = $BREAK($PARM,'/')
Let UserName = $RSUB($PARM,'/')
perform prism copy variable UserName to zone UserName
endb
return
Error handling in this example is done in the protocol with the PERFORM PRISM SET ERROR command, for the cases where PERFORM PRISM LOOKUP NAME returns a $STATUS of NOTFOUND or MULTIPLE. [See 12a.13.] Alternatively, the format could set the appropriate error codes and reprompt the screen.
This protocol also uses PERFORM PRISM COPY to refresh the value in the name field with the official name found by the lookup. This requires a zone definition in the format (see sample below). [See 12a.3, 12a.14.]
Here is a simple format frame that will work with this protocol; use it as a pattern for your code.
FRAME-ID = IDENTIFY.OUT;
DIRECTION = OUTPUT;
FRAME-DIM = 13,79;
USAGE = NAMED, DISPLAY;
LABEL = PROMPT.NAME;
TSTART = 6,4;
TITLE = 'Enter your Name or University ID:';
VALUE = #UserName;
LENGTH = 32;
START = 6,38;
DISPLAY = WHITE,BRIGHT,UNDERLINE;
UPROC = eval $ZoneDef($AreaName, UserName, 6, 38, 1, 32);
PUTDATA;
:
[other label groups for the rest of the screen]
:
FRAME-ID = IDENTIFY.IN;
DIRECTION = INOUT;
FRAME-DIM = 13,79;
USAGE = NAMED, MERGE;
LABEL = PROMPT.NAME;
ESTART = 6,1;
LENGTH = 32;
START = 6,38;
GETDATA;
UPROC = if $ULen = 0 then begin;
UPROC = " set UCode = 'RQ'";
UPROC = " set error = 'S'";
UPROC = endb;
UPROC = else let UserName = $UVal;
LABEL;
UPROC = if $GProcErr then begin;
UPROC = " set status = 'REPROMPT'";
UPROC = " abort quiet";
UPROC = endb;
UPROC = else if $WProcErr and ($GNChanged or $ScrnStat ~= 'WARN')
then begin;
UPROC = " set status = 'WARN'";
UPROC = " abort quiet";
UPROC = endb;
:
[other label groups for the rest of the screen]
:
FORMAT-NAME = ...
ALLOCATE = ...
:
FRAME-NAME = IDENTIFY.IN;
FRAME-TYPE = XEQ;
UPROC = SET PADCHAR = $TERMPAD;
UPROC = SET EDISPLAY = 'ERROR';
UPROC = SET ELENGTH = 2;
FRAME-NAME = IDENTIFY.OUT;
FRAME-TYPE = XEQ;
UPROC = SET PADCHAR = $TERMPAD;
UPROC = SET TDISPLAY = 'PINK, PROTECT';
UPROC = SET AUTOTAB;
The second example is an extension of the first one. This example is for an identification screen that prompts for proxy identification as well as for the current user's name. That is, it has an "Acting for" field as well as a "Name" field. It uses two LOOKUP NAME commands to verify the two names, and a LOOKUP PROXY command to verify that a proper proxy relationship exists between the two.
* FILE
DECLARE PARMS USERID, ACTINGID
DECLARE SCREEN IDENTIFY
on command OK, proc Lookup.Name
DECLARE PRELOAD
VGROUP orv.ab.cde.identify
++Get.Name
; This proc determines a value to be prompted in the name field
; on the identification screen.
; Prism uses $UserName similarly in its own identification routines.
; The #UserName value will be prompted on the screen in the "Name"
; field by the format.
if $UnivName then let UserName = $UnivName
else begin
let Temp = $CHANGE($UserName,' -',':')
let UserName = $SQU($BREAK(#Temp,'(:;1234567890'))
if $XSTR(#UserName,KEEP,LAST,1) = '/' \
then let UserName = $SQU($XSTR(#UserName,DROP,LAST,1))
endb
++Identify
PERFORM PRISM SCREEN IDENTIFY TITLE='Identification' OK
; The format reads the value in the name field and puts it
; in the #UserName variable. The value in "Acting for" is
; put in the #ActingFor variable.
; When the OK command is issued, the Lookup.Name proc will be
; executed.
++PIN
/PERFORM PRISM PROMPT PIN UNIVID=#UserId PREVIOUS='Jump IDENTIFY'
++Check.Proxy
; Both names have been looked up and validated. This proc
; does the LOOKUP PROXY.
if #ActingFor then begin
/PERFORM PRISM LOOKUP PROXY #UserId FOR #ActingId \
FORM='RTDEMO/FUND REQUEST'
if $STATUS = 'NOPROXY' then begin
/set Msgline 'You are not delegated to act for #ActingFor'
jump IDENTIFY
endb
endb
Return
++Lookup.Name
; This proc is executed during an ON COMMAND OK event.
/PERFORM PRISM LOOKUP NAME="#UserName" RESOLVE UNIVID TEMPOK
if $STATUS = 'NOTFOUND' then begin
PERFORM PRISM SET ERROR 'NN' AT 6,1
/set MsgLine = 'NN: The name #UserName does not have an active \
ID and PIN'
set STATUS = 'REPROMPT'
endb
else if $STATUS = 'MULTIPLE' then begin
PERFORM PRISM SET ERROR 'MN' AT 6,1
/set MsgLine = 'MN: Multiple names like #UserName found; \
please use a more complete name'
set STATUS = 'REPROMPT'
endb
else begin
Let UserId = $BREAK($PARM,'/')
Let UserName = $RSUB($PARM,'/')
perform prism copy variable UserName to zone UserName
endb
if #ActingFor then begin
; If the user has entered a value in the "Acting for" field, then
; the #ActingFor variable will have a value and the following
; will execute
; Now look up the "Acting for" name.
/PERFORM PRISM LOOKUP NAME="#ActingFor" GROUPS RESOLVE PROXYID
if $STATUS = 'NOTFOUND' then begin
PERFORM PRISM SET ERROR 'NN' AT 8,1
/set MsgLine = 'NN: The name #ActingFor does not have an active \
ID and PIN'
set STATUS = 'REPROMPT'
endb
else if $STATUS = 'MULTIPLE' then begin
PERFORM PRISM SET ERROR 'MN' AT 8,1
/set MsgLine = 'MN: Multiple names like #ActingFor found; \
please use a more complete name'
set STATUS = 'REPROMPT'
endb
else begin
Let ActingId = $BREAK($PARM,'/')
Let ActingFor = $RSUB($PARM,'/')
perform prism copy variable ActingFor to zone ActingFor
endb
endb
return
If you store IDs in your database, store them as strings, not as integers. While many IDs are numeric, IDs for temporary employees start with "T" and IDs for work groups may be alphanumeric.
You do not need to do any re-validation of IDs that Prism returns to you; you should rely on Prism and SPIRES to ensure the integrity of the IDs.
Remember that your identification screens are parm screens that need a DECLARE PARMS or DECLARE NOPARMS statement in order to make the SETUP TASK command available in your application. [See 10.8 for more information about this.]
When a user identifies himself by giving a valid PIN, $UNIVID and its associated variables are set. These variables apply to the currently-identified user.
This SPIRES variable holds the University ID of an end-user after prompting for University ID and PIN has been successful.
After successful prompting of University ID and PIN, $UNIVNAME contains the name (in firstname-lastname order, e.g., "John Smith") corresponding to the $UNIVID that has been established. The name comes from the "signs-as" element in the directory, if one exists -- if not, the "official" name is used.
The electronic mail address (as recorded in Personal Profile) for the holder of the current $UNIVID
The phone number of the holder of the current $UNIVID.
If the user indicated that he is "Acting for" another person or for a work group, then $PROXYID contains the University ID of the person or work group for whom the current user is acting. IDs for work groups may be up to 16 characters long.
The standard identification screen generated by PERFORM PRISM PROMPT NAME has an "Acting for" field if the PROXY option is used on the PERFORM command. When you have your own custom identification screen, $PROXYID is set after a successful PIN prompt and a successful PERFORM PRISM LOOKUP PROXY command.
If $PROXYID is set, then $PROXYNAME holds the name associated with the proxy ID.
The electronic mail address for the holder of the current $PROXYID.
The phone number of the holder of the current $PROXYID.
If your application stores University IDs as data elements for a transaction, you may wish to look up the current name, phone number, etc. for that ID for use later in displays or input screens. The $LOOKSYS function and system proc let you lookup into the University ID directory for the following information. $LOOKSYS is also used in routing applications to look up information about routed forms, such as the routing status or the list of approvers.
For more details about these elements, or if you have other lookup needs, contact a Prism/SPIRES consultant in the Data Center.
Here is the syntax of $LOOKSYS as a function:
$LOOKSYS(filecode,record-key,elem-name)
and as a system proc:
$LOOKSYS(filecode,elem-name,err)
The "filecode" is always UNIVID when looking up University ID information. The "record-key" is the ID you're looking up.
For example, to look up the name associated with ID 09999798:
++GetName Let Name = $LOOKSYS(UNIVID,09999798,USE.NAME)
This section is applicable to identification screens in routing applications. For additional information about work groups and proxy identification, see the "Routing Applications" manual.
Prism's forms routing system allows one person to sign or act for another person, if the proper authorization exists. Prism's Personal Profile file lets one person "delegate" permission to another person to sign or take action on his behalf (the DELEGATE entry form). The "delegatee" is said to be the "proxy" for the "delegator".
Mary Smith says ... <-- the delegator
John Doe can act for me <-- the delegatee (the proxy)
On your identification screens, you may wish to let the person not only identify who he is, but also to say who he is acting for. Your application must then look up both names and also verify that the "delegation" has been recorded in the Personal Profile file.
In addition, for transactions involving expenditure of funds, signature authorization is recorded in the SUFIN Authority file. Your application would presumably include SUFIN Authority checks at some point in the transaction in this case.
In addition, Prism lets system administrators define "work groups". A work group is a defined group of people who are all equally empowered to take action on a form.
On identification screens, the "Acting for" field is where a person says that he is acting as a proxy for someone else, or that he is acting as a representative of a work group.
If you use the standard identification screen produced by PERFORM PRISM PROMPT NAME, you can include the PROXY option to create an "Acting for" field and to cause Prism to check the two names to see that the proper relationship exists. (Note that Prism does not check SUFIN Authority; your application is responsible for that check, if applicable.)
NSI Gr.Appl 10/17/91 16:41
Personal Identification
---------------------------------------------------------------------------
Enter your Name or University ID:
Lindsey_Clayton__________________
Acting for: ________________________________
Type: OK to continue file selection. CANCEL to cancel file selection.
UNDO to discard changes to page.
YOUR RESPONSE:
f1=Help f5=OK f7=Undo f8=Cancel
If you have created a custom identification screen, include an "Acting for" field, use PERFORM PRISM LOOKUP NAME to look up both IDs, prompt for the PIN, and then use the PERFORM PRISM LOOKUP PROXY command to check for a valid proxy relationship.
The protocol examples in an earlier section illustrated the use of this command in context. [See 25.4.] Here is the formal syntax of PERFORM PRISM LOOKUP PROXY.
PERFORM PRISM LOOKUP PROXY id1 FOR id2 [FORM = file-id/form-name]
The FORM option is required in virtually all cases, although technically it is optional. There are instances when Prism's general routing code uses the command without a FORM option, but applications would generally always be looking up delegation for their specific form.
After PERFORM PRISM LOOKUP PROXY, the $STATUS variable will be either null (a valid proxy relationship exists) or NOPROXY (id1 is not authorized to act for id2). If a valid proxy relationship exists, the $PROXYID, $PROXYNAME, $PROXYPHONE, and $PROXYEMAIL variables will be set.
Note that you should prompt for the PIN for the current user before the LOOKUP PROXY command, because Prism clears any existing $UNIVID and $PROXYID setting immediately prior to the PIN prompt.
A distinct identification process has been devised for use by temporary employees who need to work in Prism applications that prompt for ID and PIN. This applies to people hired from temporary agencies like Adia (not to official University employees hired for a fixed term and paid through payroll).
A department administrator can register the temporary employee by using the TEMP ACCESS entry form in Prism's Personal Profile file. The registration form asks for deparmental affiliation, name, email address for mail related to Prism forms, an expiration date for the registration, and a "confirmation code". This confirmation code is requested when the temporary employee identifies himself, as a minimal level of validation. The code is not confidential -- the supervisor and employee both know it.
Temporary employees are instructed to enter the word "temp" when asked for their name on identification screens. If the application has enabled access by temporary employees, Prism recognizes the string "temp" and branches to a routine that prompts additional input fields to identify the temporary employee:
Faculty/Staff Directory 10/22/91 09:02
----------------------------------------------------------------------------
Enter your Name or University ID:
temp_____________________________
Acting for: ________________________________
Type: OK to continue file selection. CANCEL to cancel file selection.
UNDO to discard changes to page.
YOUR RESPONSE:
f1=Help f5=OK f7=Undo f8=Cancel
Faculty/Staff Directory 10/22/91 09:02
----------------------------------------------------------------------------
*------------------------------------------------------------------------*
| By typing TEMP, you have indicated that you are working as a temporary |
| employee at Stanford, and have been registered for on-line work by |
| your supervisor. To continue your work in this file, enter your name |
| and, when requested, the confirmation code your supervisor gave you. |
| |
| Enter your name: _________________________________ |
| |
| |
| |
| f5=OK f9=Cancel Box |
*------------------------------------------------------------------------*
Type: OK to continue file selection. CANCEL to cancel file selection.
UNDO to discard changes to page.
YOUR RESPONSE:
f1=Help f5=OK f7=Undo f8=Cancel
Faculty/Staff Directory 10/22/91 09:02
----------------------------------------------------------------------------
*------------------------------------------------------------------------*
| By typing TEMP, you have indicated that you are working as a temporary |
| employee at Stanford, and have been registered for on-line work by |
| your supervisor. To continue your work in this file, enter your name |
| and, when requested, the confirmation code your supervisor gave you. |
| |
| Enter your name: Maryann_Doe______________________ |
| |
| Enter your confirmation code: ( ************ ) |
| |
| f4=Previous f5=OK f9=Cancel Box |
*------------------------------------------------------------------------*
Type: OK to continue file selection. UNDO to discard changes to page.
PREVIOUS to return to prior page. CANCEL to cancel file selection.
YOUR RESPONSE:
f1=Help f5=OK f7=Undo f8=Cancel
It is the TEMPOK option on either the PERFORM PRISM PROMPT NAME or PERFORM PRISM LOOKUP NAME command that allows temps to identify themselves in your application as illustrated here. In the absence of TEMPOK, if "temp" is encountered, Prism gives a message indicating that the file does not allow access by temporary employees. [See 25.3.1, 25.3.2.]
When temps are registered, they are assigned IDs that begin with "T". When Prism looks up a temp's name, it looks only in the set of IDs for temporary employees. When the name and confirmation code are validated, $UNIVID and associated variables are set, just as in the identification process for regular Stanford affiliates.
If you store IDs in transaction records, you can use $LOOKSYS to look up the associated name, department, etc. just as for regular IDs, even if the temp's registration has expired.
If a temporary employee works for several different departments or at different periods, separate registrations would be created. So any single person hired as a temp might have several temporary IDs assigned. Transactions created under the different IDs are not linked in any way.
People with temporary IDs can originate forms in routing applications, but they cannot be entered on routing lists. Prism edits the routing list to ensure this. Temps also cannot approve a form while creating it; the "Approve" field next to the originator's name is disabled for temps.
In late 1991 a new facility was added to allow people to use Prism without having a Forsythe computer account. The purpose was to accommodate people needing to do Prism work on a very occasional, infrequent basis, who otherwise would not need a Forsythe account. For example, it might be used by a research assistant who occasionally needs to create a purchase requisition or a faculty member who would like to change his Faculty/Staff Directory entry. This method of access is not intended as a substitute for having a Forsythe account, but simply to open up access to Forsythe services to a wider community, where appropriate.
The term being used for this way of using Prism is "general access to Prism" -- this term is used in a few places in system messages and help screens.
The way it works is that a person may connect to Forsythe, and then type "prism" at the "Account?" prompt. The person is then prompted for his name or University ID and his PIN.
A person entering Prism this way is identified by University ID, and the $UNIVID variable (and its associated variables) are set.
The Prism session runs on account HQ.PRM (a multiple logon account). Prism sets the account name for that session to the name in the $UNIVNAME variable. So this name would appear in SUGGEST messages or log entries or error reports originating from this session.
When a person uses Prism this way, all public files are available, of course. However, some Prism commands are not available: SETUP REPORT, SETUP SEARCH, SETUP TASK, TASK, PAUSE, LOCK. These users are not allowed to create Personal Reports, Personal Searches, or tasks because Prism currently stores those definitions under WYLBUR account. (If Prism makes a transition to storing them under University ID instead of WYLBUR account, then those commands could be made available under general access.)
On the PRINT screen, HQ.PRM sessions are forbidden to print to Forsythe or to save files on Forsythe. They can download to a micro file, however. One minor consideration to keep in mind is that if your public application offers reports that generate output directly to Forsythe (e.g. a report to make mailing labels) these users might not know how to find the output.
Some "public" reports, entry forms, or even whole applications, may make little sense when used via general access to Prism, e.g. Screen Definer. However, currently the only way to exclude general access users is to check specifically for HQ.PRM sessions and take special action (such as blocking selection of a report or entry form).