******************************************************************
* *
* 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