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