INDEX
*  Prism Applications: Coding and Installing Files in Prism
+  Recent Changes in Prism
1  Introduction
2  Modifying Your SPIRES File Definition
2.1  Adding a Subfile Section
2.2  Modifying your Index Definitions
2.3  Standards and Guidelines for Prism Indexes
2.4  Value-Supplied Indexes (Optional)
3  Writing a Display Format for Prism
3.1  General Characteristics of Your Display Format
3.2  The BRIEF Display
3.3  The FULL Display
3.4  Additional Displays Besides BRIEF and FULL (Optional)
3.5  Installing Displays
3.6  Processing Steps at File Selection (Optional)
4  Installing Your Prism Application
4.1  ADD PROFILE: (Adding Your Basic File Profile)
4.1.1  1st Screen of ADD PROFILE
4.1.2  2nd Screen of ADD PROFILE
4.1.2a  ADD PROFILE Screen for Controlling Access
4.1.3  3rd Screen of ADD PROFILE: Sorting
4.1.4  4th Screen of ADD PROFILE
4.1.5  ADD PROFILE Screens for Installing Indexes
4.1.6  ADD PROFILE Screens for Declaring Processing Steps
4.2  A Note on Maximum Profile Size
4.3  After Creating Your File Profile
5  Installing Fields for Sorting and Personal Reporting
5.1  Introduction to Fields
5.2  Field-Info for Reporting Fields
5.3  Defining Filters for Reporting Fields
5.4  Installing Sorting and Personal Reporting Fields: XSETUP FIELDS
5.5  Removing Fields
6  Adding Basic Help Records
6.1  Overview of Prism's Help System
6.2  How to Create and Install Help Records
6.2.1  Formatting Your Help Records
6.2.2  Details About XSETUP HELP
6.2.3  Deriving a New Help Record from an Existing One
6.2.4  Using the PRISM HELP Subfile Instead of XSETUP HELP
6.3  Control Words in Prism Help Records
6.3.1  $ALIAS Control Word
6.3.2  $BOX Control Word
6.3.3  $LINE Control Word
6.3.4  $ELEMINFO and $INDEXINFO Control Words
6.3.5  $CATEGORY Control Word
6.3.6  $BIND and $XBIND Control Words
6.3.7  $COMMENT and $SUBJECT Control Words
6.3.8  $XFILE Control Word
6.3.9  $FRAME Control Word
6.3.10  $CONTEXT Control Word
6.3.11  $HEADER Control Word
6.3.12  Other Control Words for Prism Help
6.3.13  Summary of Control Words for Help Records
6.3.14  Prism Help
6.3.14.1  Prism Help, from the User's Perspective
6.3.14.2  (The New Help System in Prism: A Guide for Help Writers)
6.3.14.3  (Prism Help, from the User's Perspective)
6.3.14.4  (Revising Help for Existing Applications)
6.3.14.5  (Putting Help Records into HELP TOPIC Menu Categories)
6.3.14.6  (Prism's New Help System -- DRAFT)
6.4  Details About Required Help Records
6.4.1  Welcome Screen (Required)
6.4.2  Help Record to Describe the File (Required)
6.4.3  Help Record for Each Index (Required)
6.4.4  Help Record for Each Display (Required)
6.5  The XHELP Command
6.6  A Note on Help Enhancements Made in Summer 1988
6.7  Other Required Helps
6.8  PERFORM PRISM HELP
7  Testing and Debugging Your Application
7.1  Enabling Debugging Mechanisms: SET DEBUG
7.2  Interrupting Protocol Execution: SET STOP
7.3  Echoing Protocol Commands: SET ECHO
7.4  Commands to Trace Code Execution
7.4.1  General Prism Tracing: SET TRACE
7.4.2  Tracing Search Processing: SET STRACE
7.4.3  Tracing Format Execution: SET FTRACE
7.4.4  Tracing Protocol Execution: SET XTRACE
7.4.5  Sending Tracing to a Trace Log: SET TLOG
7.4.6  Tracing Processing Rules: SET PTRACE
7.4.7  Granting Debugging Privileges: GRANT PRIVILEGES
7.5  Exiting to SPIRES Temporarily: the SPIRES Command
7.6  Other SPIRES Commands for Application Maintainers
7.7  SET LOG Command Eliminated
7.8  Message Levels
7.9  Getting Copies of Screens
7.10  Debugging Personal Reports, Personal Searches, and Tasks
7.11  Summary of Prism Debugging Commands
8  Modifying Your Application
8.1  Modifying General Profile Information: XSETUP PROFILE
8.2  Modifying Other Application Components with XSETUP
8.2.1  Adding or Modifying Indexes: XSETUP INDEXES
8.3  Looking at Descriptions of Your Application Components
8.4  Modifying File Access: MOD ACCESS Entry Form
8.5  Disabling a Prism Application
8.5.1  Disabling an Entry Form or Report Temporarily
8.6  Removing a Prism Application: REM PROFILE
9  Adding Processing Steps (Optional)
9.1  Screen Processing Steps
9.1.1  Help Records for Screen Processing Steps
9.2  Protocol Processing Steps
9.2.1  Adding Protocols to PRISM PROTO
9.2.2  Preloading Code for Efficiency
9.2.3  Compiling Prism Protocols for Efficiency
9.2.4  Procs in Prism Protocols
9.2.5  Error Tracking in Prism Protocols
9.2.6  Accessing Other Files: Links and Paths
9.2.7  Cautions on Protocol Code
9.3  Declaring Processing Steps
10  Pre-Defined Reports in Prism
10.1  Creating a Report using the SPIRES Formats Language
10.2  Processing Steps in Reporting (Optional)
10.3  Generating Report Output (Optional)
10.4  Dispatching Report Output
10.5  Creating Reports with $REPORT
10.6  Installing and Modifying Reports: XSETUP REPORTS
10.7  Help Records for Reports
10.8  Enabling the SETUP TASK Command in Your Application
11  Entry Forms in Prism
11.1  Automatic Control of Data Entry
11.2  Creating an Entry Form with Screen Definer
11.3  Creating or Modifying Entry Forms with SPIRES Formats
11.3.1  Record Redisplay After Input
11.3.2  Error Handling in Entry Forms
11.3.2a  Defining Error Codes for Entry Forms
11.3.3  Enabling Word Wrap in Text Entry Fields
11.3.4  Coding an Entry Form for Record Removal
11.4  Controlling Data Entry With Processing Steps
11.4.1  Other Uses for Processing Steps
11.5  Installing and Modifying Entry Forms: XSETUP FORMS
11.6  Help Records for Entry Forms
12  Custom Control of Data Entry
12.1  PERFORM PRISM Commands for Custom Control of Data Entry
12.1.1  PERFORM PRISM OPEN and PERFORM PRISM CLOSE Commands
12.1.2  PERFORM PRISM ASSIGN CURRENT Command
12.1.3  PERFORM PRISM SCREEN Command
12.1.4  PERFORM PRISM LINK / PERFORM PRISM UNLINK
12.1.5  PERFORM PRISM REMOVE
12.1.6  PERFORM PRISM GENERATE OVERLAY
12.1.7  PERFORM PRISM OUTPUT and PERFORM PRISM INPUT
12.1.8  PERFORM PRISM PAUSE
12.1.9  PAUSE in PRISM
12.2  Cautions on Multi-Record Transactions
12.3  A Note on Routing Applications in Prism
12a  Extensions to Normal Screen Processing: Events and Boxes
12a.1  Explanation of Prism Screen Processing
12a.2  Declaring Events in Your Protocol
12a.3  Defining Zones on an Entry Screen ($ZONEDEF)
12a.4  Trigger Fields and Buttons
12a.4a  Coding Technique for "Multiply-Occurring Zones"
12a.5  Boxes
12a.5.1  Examples of Boxes
12a.6  Standards and Guidelines for Boxes
12a.6.1  How to Label Choice Fields, Trigger Fields, and Buttons
12a.6.2  Function Keys and Navigation Commands
12a.6.3  Guidelines for Use of Boxes
12a.7  How to Code Boxes
12a.8  Protocol Code to Generate Boxes
12a.9  PERFORM PRISM SET SUBAREA (and ... CLEAR SUBAREA)
12a.10  PERFORM PRISM CHOOSE
12a.11  PERFORM PRISM PROMPT VALUE
12a.12  PERFORM PRISM PROMPT TEXT
12a.13  PERFORM PRISM SET ERROR
12a.14  PERFORM PRISM COPY
12a.14.1  Using $GETAREA and $PUTAREA Instead of PERFORM PRISM COPY
12a.15  PERFORM PRISM RESET UNDO
12a.16  PERFORM PRISM DISABLE (or ENABLE) pfkey
12a.17  Tips and Tricks for Boxes and Events
13  Protocol Steps for Searching and Other Special Search Features
13.1  How to Create a Hidden Search
13.2  Protocol Steps for an Index: Coding Techniques
13.2.1  Search Processing Details
13.2.2  PERFORM PRISM ASSIGN SEARCH
13.2.3  PERFORM PRISM SET SEARCH
13.2.4  PERFORM PRISM SEARCH (Use of This Command is Discouraged)
13.2.5  PERFORM PRISM GET LOCAL (obsolete)
13.3  Pre-Search and Post-Search Protocol Steps
13.4  Special Kinds of Prism Indexes
13.4.1  Stand-Alone Search Types
13.4.2  Secondary Search Types (obsolete)
13.4.3  Qualifying Search Types
14  Modifying Option Text
15  PERFORM PRISM SERVICE SUFIN GETAUTH
16  Secondary Files for Linking
16.1  Installing a Secondary File: ADD LINK Entry Form
16.2  Using a Secondary File
17  Appendix: Variables in Prism
17.1  $DEBUG
17.2  $DESTINATION (alias $DEST), $DESTVAL
17.2a  $EVENTZONE
17.2b  $FIELDVAL
17.3  $FORMNAME
17.4  $LASTCMD and $MAINCMD
17.5  $MSGLINE
17.6  $NEXTCMD
17.6a  [This section is not applicable to Stanford application developers]
17.7  $PARM
17.8  $PRISMID
17.9  $PROXYID, $PROXYNAME, $PROXYPHONE, $PROXYEMAIL
17.10  $RECID
17.10a  $DISNUM
17.11  $REPTNAME
17.12  $SCRNSTAT
17.13  $SRCHTYPE
17.14  $SRCHVAL
17.15  $STATUS
17.16  $UNIVID, $UNIVNAME, $UNIVPHONE, $UNIVEMAIL
18  Appendix: Checklist of PERFORM PRISM Commands
19  Appendix: Restrictions on Protocol Code
20  Appendix: Checklist of Help Records
21  Appendix: Checklist of Protocol Names
22  Appendix: The Prism Log
22.1  Explanation of Log Entries
22.2  Writing Commands to the Log
23  Appendix: Change Control Procedures
23.1  The Different Versions of Prism
24  Appendix: Categories of Files in Prism
25  Appendix: University IDs, PINs, Electronic Signatures
25.1  How Are IDs and PINs Used in Stanford Computer Systems?
25.2  Name Matching Details
25.3  Techniques for Identifying Your Current Application User Securely
25.3.1  Using the PERFORM PRISM PROMPT NAME Screen
25.3.2  Custom Identification Screens
25.3.3  Asking for the PIN: PERFORM PRISM PROMPT PIN
25.4  Sample Protocol Code for Identifying Users
25.5  Looking Up Information Associated with a University ID
25.6  Proxy Identification and Work Groups
25.7  Temporary IDs: Application Considerations
25.8  General Access to Prism: Application Considerations

*  Prism Applications: Coding and Installing Files in Prism

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

+  Recent Changes in Prism

This document matches the version of Prism released to production on August 13, 1994.

For developers

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).]

8/94 system

The following features for end-users were added to Prism 8/13/94.

For end-users

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

1  Introduction

Who this document is for

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.

The Purpose of Prism

Prism for end-users...

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.

...and for developers

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.

Prism's Basic Design

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.

Basic Requirements of a Prism File

Searching and display

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:

Requirements for Reporting and Data Entry

Report and entry

If your Prism application will support reporting or data entry as well as searching, you'll need to take these additional steps:

Installation

Installing your file

"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".

Prism Profile application

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.

Customizing Prism Applications with Processing Steps

Processing steps

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.

Note on Routing Applications

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.

SPIRES Background Needed for Prism Applications

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.

Obtaining documents

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.

2  Modifying Your SPIRES File Definition

First step: modifications in SPIRES

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".

2.1  Adding a Subfile Section

Subfile changes

Add to your file definition a subfile section in this form:

File-id (or Prism-id)

Prism file-id

"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.)

File Definer

If you are creating your file definition using File Definer, the following line has the same effect as the statements shown above:

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.

File-id vs. file name

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.

File-id in SELECT commands

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.

Limiting Access to Your File

ACCOUNTS statement

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.

"File not available" message

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.]

PROGRAM statement

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.

Other Features of the New Subfile Section

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:

SUBFILE statements

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.

Setting formats

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.

SELECT commands

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.]

2.2  Modifying your Index Definitions

Using SPIRES indexes in Prism

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.

Note on terminology

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".

Limiting access to indexes

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.

Index modifications

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.

Immediate Indexing

Benefits

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.

Possible drawbacks

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.

2.3  Standards and Guidelines for Prism Indexes

Names up to 8 characters

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.

Standard names

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.

Number of indexes

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.

2.4  Value-Supplied Indexes (Optional)

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.

Example

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.

How to Code a Value-Supplied Index

$REPARSE

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.)

Protocol step

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.

Turning Off Prompting for a Value-Supplied Search

Installation

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:

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.]

3  Writing a Display Format for Prism

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".

3.1  General Characteristics of Your Display Format

Format name

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:

(*) Technical note: USAGE = NAMED

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.]

The Dimensions of Your Prism Display Format

FRAME-DIM

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.

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.

[See B.3.3 in "SPIRES Formats" for details about the FRAME-DIM statement.]

Screen sizes

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.

3.2  The BRIEF Display

BRIEF display

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.

Sample BRIEF Displays

Sample displays

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.)
 __________________________________________________________

Sample code outline

Here is a partial outline of formats code for a BRIEF frame:

$RECNO in your format

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:

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).

Blank lines in BRIEF

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.

Header for BRIEF Display

XEQ frame called BRIEF.HDR

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:

[See D.2 in "SPIRES Formats" for details about XEQ frames.]

3.3  The FULL Display

FULL display

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

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.]

$RECNO not needed

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.

Blank lines

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.

Starting each FULL on a new screen

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:

(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.]

Headers for FULL display

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:

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.

Header on first page of FULL

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.

Handling Overflow of a Multi-Screen Record (Optional)

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.

Controlling break-points of displays

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.)

HOLDATA

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:

FLUSHDATA

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:

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.)

3.4  Additional Displays Besides BRIEF and FULL (Optional)

Uses for additional displays

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.]

Additional Displays as "Reports"

Printing format

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.

Coding Additional Displays

BRIEF or FULL style displays

Like your primary displays, your additional displays fall into two basic categories: BRIEF-style and FULL-style.

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.

Add DATA frames to your format

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:

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.)

Headers for extra displays

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.]

Installing Additional Displays

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.)

Announcing Additional Displays

Publicizing extra displays

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.]

3.5  Installing Displays

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

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

 __________________________________________________________________________

Details

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:
  _________________________________________________________________________
  _________________________________________________________________________
  _________________________________________________________________________
 ___________________________________________________________________________

3.6  Processing Steps at File Selection (Optional)

Processing steps

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).

Uses for steps

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.

For More Information on Processing Steps...

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.

4  Installing Your Prism Application

Installing your file

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.

What is a File Profile?

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.

File profile vs. file definition

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.

How to Install a File Profile

The Prism Profile 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.

Maintaining and Enhancing Your Application

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.]

Giving Access to 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.

Access lists

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.

What is an Access List?

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.

Example

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:

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 Containing University IDs

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:

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.

Setting $UNIVID

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.]

Extend Access Slowly...

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.]

4.1  ADD PROFILE: (Adding Your Basic File Profile)

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.

Accessing ADD PROFILE

To invoke the ADD PROFILE form and begin installing your basic file profile record, type these commands after entering Prism:

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.

4.1.1  1st Screen of ADD PROFILE

 ____________________________________________________________________________
 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.
 ____________________________________________________________________________

4.1.2  2nd Screen of ADD PROFILE

 ____________________________________________________________________________
 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_
 _____________________________________________________________________________

4.1.2a  ADD PROFILE Screen for Controlling Access

Depending on your answer to this question:

you will next see one of the following screens.

If "no"

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 "yes"

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.]

4.1.3  3rd Screen of ADD PROFILE: Sorting

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.

 ____________________________________________________________________________

Hidden sequencing by SPIRES elements

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.

Alternative method

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:

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.

Upper limit for automatic sequencing

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.

4.1.4  4th Screen of ADD PROFILE

 ____________________________________________________________________________
 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_
 ____________________________________________________________________________

4.1.5  ADD PROFILE Screens for Installing Indexes

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.

How Your Text is Used in Prism

FIND menu

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:
 _____________________________________________________________________________

Special features

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

Special Features for an Index

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
 _____________________________________________________________________________

4.1.6  ADD PROFILE Screens for Declaring Processing Steps

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

 _____________________________________________________________________________

Steps at file selection

Step when file is cleared

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.

Declaring conditions (optional)

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.

Result steps (optional)

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

 _____________________________________________________________________________

Processing steps for search results:

4.2  A Note on Maximum Profile Size

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:

EXPLAIN $RECINFO for more about this function.

4.3  After Creating Your File Profile

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.

Testing

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.

Adding application components

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.]

5  Installing Fields for Sorting and Personal Reporting

Uses for fields

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.

Fields are Recommended for Most Applications

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.

PRISM DEFINITIONS

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.

Alternate file-id

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).

5.1  Introduction to Fields

What is a Field?

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.

How Fields Are Different From Elements

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.

How to Install Fields

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.

Maximum allowed

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).

Installing a Field That Corresponds to a Single Element

Simplest field

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.

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:

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.

Mapping Fields To Multiple Elements

Multiple elements

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:

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:

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:

(For details on dynamic elements and the DEFINE ELEMENT command, see the manual "SPIRES Technical Notes".)

Other Uses for Dynamic Element Processing

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).

Virtual Elements Instead of Multi-Element Fields

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":

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".

5.2  Field-Info for Reporting Fields

Reporting fields

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.

Field-info

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.

Using SPIRES Elem-Info for Your Prism Field-Info

Elem-info

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.

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.

Basing Your Field-Info on Elem-Info

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.

Cautions on Elem-Info

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.

Edit Masks

Edit masks

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.

A Note on Vertical Reports

Vertical reports

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.)

Handling Long Field Values in Horizontal Reports

Truncate

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.]

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.

Indent

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:

5.3  Defining Filters for Reporting Fields

Filtering option in SETUP REPORT

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.

When Are Filters Useful?

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.

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.

Which fields should have filters?

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.]

How Filters Are Presented in SETUP REPORT

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).

Filter descriptions

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.]

How Prism Compiles the List of Filters to Present to the User

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.

How a User Specifies Filtering Criteria

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.

    ___________________________________________________________

Two filter choices

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.

Filter by search value

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.

Filter by specific value

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.

5.4  Installing Sorting and Personal Reporting Fields: XSETUP FIELDS

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.

...or MOD FIELDS

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.

Installing a new field

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______________________________________________________________________
 ____________________________________________________________________________
 ____________________________________________________________________________

Features

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:

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.

Fieldinfo screen

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.)

Details about Field-Info Options

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)

Specifying a filter

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:

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.]

Technical Notes About Filters

Truncated values

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:

Word processing

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:

This would have the intended effect for LOCATION values such as "Stanford Blood Bank" or "Bank of America".

Multiple SET FILTER commands

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:

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:

and also:

5.5  Removing Fields

Fields may be in use by application users

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!)

The CHECK FIELDS Report in Prism Profile

CHECK FIELDS report

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.

Effect of removing fields in use

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.)

6  Adding Basic Help Records

6.1  Overview of Prism's Help System

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.

General Prism help

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.

File-specific help

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.

Importance of help

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.

Helps You Must Create

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.]

HELP LIST report in Prism Profile

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

Report of unsuccessful HELP commands

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.

Helps Provided by Prism

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.

Other recommended helps

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.

Context Help and Term Help

Context help

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.)

File-specific contexts

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.

6.2  How to Create and Install Help Records

XSETUP HELP

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
  ___________________________________________________________________________

Work on helps in your active file

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:

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.

Help records are stored in PRISM HELP subfile

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.]

6.2.1  Formatting Your Help Records

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).

Use Page Wylbur

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.

18 lines per screen

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.

$Page control word

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.]

6.2.2  Details About XSETUP HELP

Who can use XSETUP HELP?

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.

Which help records may be maintained?

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.]

Specifying a help term in XSETUP HELP

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]
  _________________________________________________________________________

IDs and aliases in help records

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".

6.2.3  Deriving a New Help Record from an Existing One

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:

If you answer "yes" the new help will be added, leaving the original help record unchanged.

6.2.4  Using the PRISM HELP Subfile Instead of XSETUP HELP

PRISM HELP subfile

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.

Tasks available in SPIRES only

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.

Selecting PRISM HELP

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.

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.

Alternate form of SELECT

As a shortcut, to bypass the "File-ID" prompt, you can include the file-id in your SELECT command:

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.

Indexes

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:

Use SPIRES Commands to Maintain 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.

File-ids

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.

Maintaining Helps for Several Applications in One Session

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:

If you have specified two file-ids, you must work with full and complete help keys, including the file-id, e.g.

Include file-id

When typing a new help in your active file, include the file-id and colon in the first line with the help key:

Global FOR

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:

Batch input of many help records at once

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.

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.

PRISM HELP MAINT

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.

Deriving Your Help Records from Other Records

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.

Simulating the Prism Appearance of Help Records

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.

The BOX display

For example:

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.

6.3  Control Words in Prism Help Records

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.

6.3.1  $ALIAS Control Word

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.

HELP menus

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.

Choosing which term is an alias

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.]

6.3.2  $BOX Control Word

$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.

The BOX display in SPIRES

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:

6.3.3  $LINE Control Word

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:

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.

The BOX display in SPIRES

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:

6.3.4  $ELEMINFO and $INDEXINFO Control Words

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.

6.3.5  $CATEGORY Control Word

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:

HELP TOPICS

Possible categories

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:

One help record may appear in several categories, if applicable. Separate multiple categories by commas: $CATEGORY DISPLAY, REPORTING.

Keys and aliases

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:

$TOPICS obsolete

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.

6.3.6  $BIND and $XBIND Control Words

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:

Here, the ST FIELD help record is bound to the MICRO ORDERS entry form.

Technical notes

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.

6.3.7  $COMMENT and $SUBJECT Control Words

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:

6.3.8  $XFILE Control Word

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.

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.

Alternate Technique for Sharing Helps

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.)

6.3.9  $FRAME Control Word

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.

Debugging

To trace execution of your help format frame, use the debugging command SET FTRACE HELP ftrace-options. [See 7.4.3.]

6.3.10  $CONTEXT Control Word

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.

6.3.11  $HEADER Control Word

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.

6.3.12  Other Control Words for Prism Help

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.]

6.3.13  Summary of Control Words for Help Records


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

6.3.14  Prism Help

6.3.14.1  Prism Help, from the User's Perspective

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.

6.3.14.2  (The New Help System in Prism: A Guide for Help Writers)

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.

The changes, in brief

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.

A single path through help

New, pre-defined help records

Local and global help processing

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

Prism will keep better track of user's context

New HELP TOPICS menu

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.

6.3.14.3  (Prism Help, from the User's Perspective)

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.

6.3.14.4  (Revising Help for Existing Applications)

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.

6.3.14.5  (Putting Help Records into HELP TOPIC Menu Categories)

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

6.3.14.6  (Prism's New Help System -- DRAFT)

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.

How the changes will affect users

f0~=Options

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.

Help screens look slightly different

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.

Stem matching is done word by word

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.

New, pre-defined help records

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:

Prism looks for local help first, then global help

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.

How help writers can take advantage of these new features

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.

Developing new context help records

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.

Context help for indexes

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."

Putting help records into categories for HELP TOPICS

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:

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:

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.

Binding help records to an input screen, display or report

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:

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.

Adding subjects to help records for your own retrieval

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:

where "keywords" is any word or words to be used by you for searching purposes in the PRISM HELP subfile.

For example,

Eliminating the ?TOPICS record

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.

Eliminating aliases you no longer need

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.

Future changes to Prism's help system

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.

6.4  Details About Required Help Records

Required helps

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.

Keys of Required Helps for Search-Only Application

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).

6.4.1  Welcome Screen (Required)

?WELCOME

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:

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.

Screen in place of ?WELCOME

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.]

6.4.2  Help Record to Describe the File (Required)

<file-name> FILE

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

$CATEGORY OTHER

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.)

6.4.3  Help Record for Each Index (Required)

<indexterm> INDEX

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.

$CATEGORY SEARCHING

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:

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.

6.4.4  Help Record for Each Display (Required)

<display-name> DISPLAY

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.

$CATEGORY DISPLAY

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.]

Context for help displays

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.

Helps for brief and full

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).

6.5  The XHELP Command

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.

6.6  A Note on Help Enhancements Made in Summer 1988

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.

6.7  Other Required Helps

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.]

6.8  PERFORM PRISM HELP

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.

7  Testing and Debugging Your Application

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:

Notification of system errors

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.

UTIL GETDUMP

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.]

Disabling a file to fix bugs

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.]

7.1  Enabling Debugging Mechanisms: SET DEBUG

Error messages display

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.

DEBUG pauses

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.

Only applies to your files

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.]

$DEBUG variable

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.)

SHOW DEBUG command

Use the SHOW DEBUG command in Prism if you need a reminder of the debugging and tracing options you have enabled.

Additional helps available in DEBUG mode

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.

Turning off debugging

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.]

Explaining Messages -- Evaluating Variables and Expressions

EXPLAIN and SHOW EVAL

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.

7.2  Interrupting Protocol Execution: SET STOP

SET STOP

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:

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.

7.3  Echoing Protocol Commands: SET ECHO

SET ECHO

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.

Compiled protocols don't echo

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.]

SET NOCOMPXEQ to switch to uncompiled

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

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.]

7.4  Commands to Trace Code Execution

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.

7.4.1  General Prism Tracing: SET TRACE

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.

Included in TLOG

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.]

CLEAR TRACE

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.)

7.4.2  Tracing Search Processing: SET STRACE

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)

Included in TLOG

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.]

CLEAR STRACE

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.)

7.4.3  Tracing Format Execution: SET FTRACE

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.

Options on SET FTRACE

In Prism, you can use the same FTRACE options as in SPIRES, to control precisely what type of tracing information you see:

Which Prism formats are traced

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.

What tracing is in effect?

The SPIRES command SHOW FTRACE tells you which of the FTRACE options are currently in effect. (Type SPIRES first, then SHOW FTRACE.)

Specifying frame and variable lists

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.

Included in TLOG

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.]

Turning off tracing

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".

7.4.4  Tracing Protocol Execution: SET XTRACE

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.

Options on SET XTRACE

In Prism, you can use the same XTRACE options as in SPIRES, to control precisely what type of tracing information you see:

What tracing is in effect?

The SPIRES command SHOW XTRACE tells you which of the XTRACE options are currently in effect. (Type SPIRES, then SHOW XTRACE.)

Specifying protocol and variable lists

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.

Included in TLOG

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.]

Turning off tracing

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.

7.4.5  Sending Tracing to a Trace Log: SET TLOG

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.

7.4.6  Tracing Processing Rules: SET PTRACE

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.

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.

What tracing is in effect?

The SPIRES command SHOW PTRACE tells you which of the FTRACE options are currently in effect. (Type SPIRES first, then SHOW PTRACE.)

Included in TLOG

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.]

Turning off tracing

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).

7.4.7  Granting Debugging Privileges: GRANT PRIVILEGES

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:

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.

Details

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.

7.5  Exiting to SPIRES Temporarily: the SPIRES Command

"SPIRES" command

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.

7.6  Other SPIRES Commands for Application Maintainers

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

SPIRES Commands for Monitoring Memory Usage

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.

UTIL PRISMCPU

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.

Seeing Your Variables From Within Prism: SHOW VARIABLES

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

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

Seeing Which Version of Prism You Are In

SHOW VERSION

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".)

UTIL PRISMVER

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.

Seeing Your Most Recent Commands

SHOW LOG 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.

SHOW HISTORY command

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.

7.7  SET LOG Command Eliminated

The SET LOG and CLEAR LOG commands were eliminated from Prism with the May 1990 version of Prism.

7.8  Message Levels

Message levels in protocols

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.]

7.9  Getting Copies of Screens

DUMP SCREEN

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.

7.10  Debugging Personal Reports, Personal Searches, and Tasks

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

Updating definition records

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.

7.11  Summary of Prism Debugging Commands

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.

8  Modifying Your Application

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.

Choosing Between Prism Profile and XSETUP

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.

Benefits of XSETUP

 - 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.]

Tasks not available in XSETUP

There are some application maintenance tasks that are not available in XSETUP and must be done in Prism Profile:

The XSETUP menu

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

 _________________________________________________________________________

Prism Profile entry forms

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.

What's in this chapter

The rest of this chapter covers the following topics:

8.1  Modifying General Profile Information: XSETUP PROFILE

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.

Adding vs. modifying a profile

There are a few differences between ADD PROFILE and XSETUP PROFILE:

File-id is protected

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.]

Using MOD PROFILE instead of XSETUP

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:

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.]

8.2  Modifying Other Application Components with 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.

Full Syntax of XSETUP

Rather than simply typing XSETUP and seeing a menu of choices, you may specify in your command exactly what you want to modify:

The * in XSETUP FORM * and XSETUP REPORT * refers to the currently selected entry form or report.

Choose a task in XSETUP

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.

8.2.1  Adding or Modifying Indexes: XSETUP INDEXES

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.

Modifying an index

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.

Before removing indexes

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.

8.3  Looking at Descriptions of Your Application Components

A set of SHOW commands is available to display information about components of your application, from within the application:

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.

Reports in Prism Profile

Help records

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.]

Fields in use

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.]

Indexes in use

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.

8.4  Modifying File Access: MOD ACCESS Entry Form

MOD ACCESS

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.

Choosing MOD ACCESS

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 the ACCOUNTS Statement in SPIRES

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.]

8.5  Disabling a Prism Application

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.

Disabling with XSETUP SELECT

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)
 __________________________________________________________________________

Re-enabling the file

To re-enable a file so that people can SELECT it:

PERFORM PRISM DISABLE SELECT

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:

To re-enable the file

The complementary command to re-enable the Prism file is:

Prism vs SPIRES access

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.

8.5.1  Disabling an Entry Form or Report Temporarily

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.

Re-enabling the form or 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.)

8.6  Removing a Prism Application: REM PROFILE

When you wish to remove a Prism application, here is the procedure to follow:

Make sure that none of your help records are being shared with other applications through the $XFILE control word before removing them.

REM PROFILE

 ____________________________________________________________________________
 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.

9  Adding Processing Steps (Optional)

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.

Types of steps

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

When steps are allowed

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.]

Protocol step only

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)

How Screen Steps and Protocol Steps Fit Together

Step id

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.

Order of steps

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.

The Interaction (and Execution Order) of Processing Steps

Example of step interaction

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.

9.1  Screen Processing Steps

Benefits of screen steps

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.]

Drawbacks

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.

Not for adding data

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.

The SPIRES Coding for Screen Processing Steps

Frames for screen steps

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:

[See 11.3 for information on screens for an entry form.]

Maximum length

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.]

Identifying Screens and Frames

Step id

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.

Naming conventions

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

Screen title

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.

9.1.1  Help Records for Screen Processing Steps

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.

Help for Errors in Screen Input: ?ERROR

Error help

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.

Example with Standard Error Codes

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.

Context Help During Input: ?INPUT...

Help during input

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.]

9.2  Protocol Processing Steps

Benefits of Protocol Steps

Protocol steps

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.]

Drawbacks

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.]

Aspects of Protocol Steps

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".

Some Characteristics of Protocol Steps in Prism

Invisible to users

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.

No protocol interaction with users

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.

Response Time

Effect on response time

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.

One Protocol Per Task

One protocol per form or report

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.

Protocol Naming Conventions

Protocol naming conventions

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.)

9.2.1  Adding Protocols to PRISM PROTO

PRISM PROTO subfile

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.]

PRISM PROTO in SPIRES

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:

Shortcut

As a shortcut, to bypass the "File-ID" prompt, you can include the file-id in your SELECT command:

The file-id that you enter when you select PRISM PROTO determines which protocols you may see, add, and update.

Adding a protocol

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:

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.

Working with 2 file-ids

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:

Working with any file-id

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.

Include file-id

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:

It also applies to the form of the protocol name that you type in the first line of your active file:

Global FOR

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:

Printing Your Protocols

Formatting protocols code

The PFORMAT command (a WYLBUR command) reformats protocols code in your active file, providing a standard indention style. (For details, in SPIRES, EXPLAIN PFORMAT.)

Printing your protocols

You can use standard SPIRES tools for printing and searching your protocols, such as the PERFORM PRINT command:

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.)

9.2.2  Preloading Code for Efficiency

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.

DECLARE PRELOAD

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.]

Upper limits

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.)

Resources that can be preloaded

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.)

Example

The example below shows the DECLARE PRELOAD statement near the beginning of a protocol, but it can appear wherever you wish.

-$PRELOAD control word

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:

9.2.3  Compiling Prism Protocols for Efficiency

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.

Telling Prism about compiled protocols

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:

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

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:

Note that if your protocol name contains blanks, you will need to enclose it in quotes in the COMPILE / RECOMPILE command.

SYS PROTO record

If you use the SYS PROTO technique of compiling your Prism protocol, follow the pattern below for your SYS PROTO record:

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":

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:

Thus the SYS PROTO record for the protocol "REPORT/MAIL LABELS" in an application with file-id "TESTFILE" might look like this:

9.2.4  Procs in Prism Protocols

Procs

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.

Structure of Protocol Procs and Steps

Structure of Prism 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.

Execution Order Determined by Procs

Order of execution

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

Step id for procs

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.

Protocol Steps and the Active File

Active file processing

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:

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.

9.2.5  Error Tracking in Prism Protocols

Tracking errors with $STATUS

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.

STATUS = STOP

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:

The RETURN here is important. Prism will not "see" the new $STATUS setting until you return control to Prism from your protocol.

How $MsgLine is used

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

STATUS = SYSERROR

SYSERROR

Set $STATUS to SYSERROR to indicate an unexpected command failure, as in the example below:

Setting $STATUS to 'SYSERROR' helps Prism back end-users out of system errors gracefully, while performing essential error logging.

More on System Errors

System errors

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.

Fixing errors

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.

For more information...

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

9.2.6  Accessing Other Files: Links and Paths

Linking to other files

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:

Benefits of PERFORM PRISM LINK

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.]

Setting Additional Formats

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.

9.2.7  Cautions on Protocol Code

Cautions

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.

Execution environment

Your protocol code should work behind the scenes without altering the Prism environment as end-users perceive it:

Cautions on paths

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:

More Cautions on Protocol Code for Prism

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.

9.3  Declaring Processing Steps

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.]

Declaring steps

The general method of declaring processing steps to Prism follows this pattern:

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.

Miscellaneous Notes

Timing of steps

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.]

Verifying step ids

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.

Removing Steps and Conditions

Removing steps

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.

Removing conditions

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.

10  Pre-Defined Reports in Prism

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.

Reports in 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.]

An Alternative to Reports: Additional Displays

Additional displays as reports

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.

Coding and Installing Reports

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.

10.1  Creating a Report using the SPIRES Formats Language

SPIRES report formats

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.

Reports With Multiple Formats

Online vs. printed versions of a report

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.]

Reports Wider Than 79 Columns

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.

SET HCLIP Uproc

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.

Controlling Searching and Sorting for the Report

Disabling searching

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

Automatic sequencing

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.

Disabling SORT

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".

Controlling Overflow in Reports Displayed Online

Overflow

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:

SET PUTDATA 4

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.]

10.2  Processing Steps in Reporting (Optional)

Processing steps

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.]

Uses for steps

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:

Report-Selection and Clearing

    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.

Report-Execution: Printing

Generating vs. dispatching

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.

Deferred printing of reports

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.

Report-Execution: Display Report

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.

10.3  Generating Report Output (Optional)

What is "generating"?

"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).

The OUTPUT step

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.

DISPLAY REPORT must be disabled

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.

Installing a Protocol Step for Report Generation

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   ________________________________

Protocol Steps and Active Files

Active file per step

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.

10.4  Dispatching Report Output

What is "dispatching"?

"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.

When is dispatching needed?

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.

Customized PRINT Parameters (Alternative to Dispatching)

Dispatching vs. custom print options

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.]

How to Dispatch a Report

$DEST, $DESTVAL, and $PARM

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.

Installing a Protocol Step for Report Dispatch

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   ________________________________

10.5  Creating Reports with $REPORT

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.

Report headers

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.

Creating the report protocol

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:

XSETUP REPORT questions

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___________

10.6  Installing and Modifying Reports: XSETUP REPORTS

XSETUP REPORTS

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.

...or MOD REPORTS

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.

Declaring each report

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: .........................
 _____________________________________________________________________________

PRINT defaults

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).

Extra features

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____________________________________________________________
 ____________________________________________________________________________
 ____________________________________________________________________________
 ______________________________________________________________________________

Declaring steps for reporting

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

 ______________________________________________________________________________

Instructions for Processing Steps

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    ________________________________

 _____________________________________________________________________________

Declaring conditions

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.

10.7  Help Records for Reports

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

?INTRO help

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:

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.

Parm screen instead of ?INTRO

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.

Other Help Records for Reports

<report-name> REPORT

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:
 - Or write a new help record with a key of <report-name> 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.

$CATEGORY REPORTING

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".

Context help for reports

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.

Context help for parm screens

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.]

10.8  Enabling the SETUP TASK Command in Your Application

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 you have parm screens

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.

DECLARE PARMS in your protocol

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.

In which 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.

Multiple parms to declare in a protocol

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

Parm screens that set $UNIVID

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.]

Adding parm screens when tasks already exist

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 your parm screens use screen steps

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.

Other Considerations for Your Protocol Code

Post-PRINT parm screens

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.

Initializing variables 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.

Screen prompts omitted in tasks

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.

Which variables to declare

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.

Design Considerations for Parm Screens

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.

11  Entry Forms in Prism

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.

Overview of Data Entry

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).

Types of Entry Forms

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.

Single-task forms recommended

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.

Transaction types

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:

Automatic GET or CREATE

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.

Automatic REVIEW after SEND

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.]

Other Features of Entry Forms

Helps

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.]

Customizing Guided Mode options

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.]

11.1  Automatic Control of Data Entry

Automatic installation

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

Automatic vs. Custom Control of Data Entry

Which method to use

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.

11.2  Creating an Entry Form with Screen Definer

Screen Definer

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.

Installing A Screen Definer Form 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______

Customizing Screen Definer Output

Modifying a generated record

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.

11.3  Creating or Modifying Entry Forms with SPIRES Formats

Screen Definer and formats

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.

Requirements for a SPIRES Format Supporting Data Entry

Format requirements

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 for adding records

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 for updating records

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 for removing records

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.

Direction and usage

For ADDs, UPDATEs and REMOVEs the Output Frame for each screen must be as follows:

For ADDs, UPDATEs and REMOVEs the Input Frame for each screen must be as follows:

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.

When FRAME-TYPE must be DATA

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.

Naming the Screens and Frames of an Entry Form

Step-id

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.

Screen title

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.

Naming your frames

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.]

Naming conventions

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

SPIRES Note: Automatic "Open" and "Close"

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.

Standards for Screen Layout

Coding standards

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 More Information

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".

The PREVIOUS Command

PREVIOUS

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.)

11.3.1  Record Redisplay After Input

REVIEW command

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.)

Automatic REVIEW

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.]

Format for REVIEW

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.]

Be sure to note that this special REVIEW frame goes into your input format, not into your display format.

Frame-Type = DATA

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.]

Overflow for REVIEW

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:

Redisplaying Multiple Records

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.

11.3.2  Error Handling in Entry Forms

The $STATUS and $SCRNSTAT Variables

$STATUS variable

To signal to Prism that reprompting is necessary, use the $STATUS Variable, giving it the value 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.

When to set STATUS

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.

Warning conditions

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.]

$STATUS vs. $SCRNSTAT

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.

Closeout errors

Currently, Prism does not support a method for detecting record closeout errors. You must detect errors while you are processing an individual screen.

Accepting Null Input

Null input

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.

11.3.2a  Defining Error Codes for Entry Forms

How errors are marked on entry screens

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.]

How error codes are defined

There are two ways to define the error codes that should display when an entry screen is reprompted in an error condition:

In the file definition

Here is an example of file definition code using the $MSG Inproc:

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:

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.)

In the input format

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:

For details about this technique, EXPLAIN SET UCODE.

Explanations of error codes

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.

11.3.3  Enabling Word Wrap in Text Entry Fields

Wrapping text

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:

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.]

Rules for a Wrapping Field

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:)

    .............       .............           .........
        .........       .............      ..............
        .........       .............      ..............

A limitation

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.

11.3.4  Coding an Entry Form for Record Removal

Guidelines

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.>
 _____________________________________________________________________________

What Happens after SEND?

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.

The Input Format for a Record-Removal Entry Form

Screen Definer

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.

In the .OUT frame

These label groups create the input field and label shown at the top of the screen sample above:

In the .IN frame

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.

Other Considerations for a Remove Form

YC error code

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:

You could also use the message-line (i.e., use SET MSGLINE within a Uproc) to tell how to cancel the removal.

FRAME-TYPE

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.)

Transaction type for the entry form

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.)

11.4  Controlling Data Entry With Processing Steps

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.]

Automatic installation

In the current chapter, we will assume that your entry form is used for adding or updating a single record per entry-cycle (i.e., the process between GET/CREATE and SEND will add or update only a single record). We will also assume that the form invokes screens from only a single SPIRES file, namely the file you named in ADD PROFILE.

If these two conditions are true for you, you can take advantage of the "automatic installation" of entry forms described earlier in this chapter. (But if these two conditions are not true for you, you will need to use the more complex "custom installation".) [See 12.]

Controlling data entry

As part of installing your entry form, you give explicit instructions on how the flow of the input transaction process should be controlled. The processing steps that you install for data entry control the timing and nature of everything from CREATE/GET to SEND/CANCEL.

Timing of screen execution

For automatic control of data entry, you install each of the screens coded in your format as a separate screen processing step in XSETUP FORMS. These screen steps will be executed, along with their associated protocol steps, starting from the top down, in the order of their installation in XSETUP FORMS (and not in their order in your format). Since steps are executed from the top down, once end-users have typed SEND, any screen steps that have not yet been executed will simply be passed over, though the two protocol steps, PRE and POST, if coded, would be executed at this point.

For each screen, you determine whether SEND is a valid option when you install the screen in XSETUP FORMS. Once you allow SEND as an end-user option for any screen in your entry form, all the screens installed after it by definition become optional, so you would not allow the SEND option on a screen until all the required data for a record had been prompted for.

If you choose "automatic" processing, these characteristics of your entry form will be determined through the installation of processing steps in XSETUP FORMS:

 - The order of each screen (and the order of the protocol steps, if any, between the screens)

Remember that the order in which you install processing steps for data entry determines the order in which the steps are executed when an end-user uses the form.

 - The maximum number of times a screen can be displayed
 - The command options to appear below the screen
 - The condition that must be true before a screen is displayed
 - The interaction between screens and protocol steps

Interaction of Screen Steps and Processing Steps

This modification of the earlier chart for entry indicates roughly the interaction and timing of your screen steps and your protocol steps. There can be as many as eight screens under automatic control:

   (P - mult)  --- indicates points where more than one protocol
                   step might occur

   (P - sing)  --- indicates where a single protocol step might
                   occur

              \                   \                    \                \
(GET or --------  SCREEN#1  --------   SCREEN#n -----------(SEND)----------
CREATE)    |  /                |  /               |    /              | /
           |                   |                  |                   |
           |                   |                  |                   |
        (P - mult)         (P - mult)          (P - sing)        (P - sing)

Note the many points at which protocol steps can come into play:

 - before any screen including the first
 - between any two screens
 - after any screen
 - before or after SEND (but not after CANCEL)

Note on Steps Associated with the SEND Command

There are two special protocol steps associated with the SEND command and labeled PRE and POST in XSETUP FORMS. These steps, if coded, would be executed even when end-users issue SEND before seeing all of the screens.

The PRE step is executed while the record is still in memory and allows you to perform final processing before the record is put into the data base.

The POST step occurs only after the record has been put into the data base and thus always implies a successful data entry transaction. You could use it for compiling statistics or sending notification to your account.

Overview of Installing an Entry Form Automatically

To declare processing steps for "automatic" data entry, follow this procedure in XSETUP FORMS:

(You can have as many as eight steps in automatic processing, plus two additional "SEND" steps, one which would take effect before and one after a record was successfully added or updated.)

Some of these options are protected (e.g., PREV on the first screen), and some of them are mutually exclusive (a "display only" screen cannot have multiple iterations, for instance). Also indicate whether the step should be executed only under "special conditions":

For protocol steps indicate whether there are "special conditions".

Note that for protocol steps the command and display options are protected, but you can ask for conditional execution of the protocol step by changing the value under SPECIAL CONDITIONS to 'Yes'.

Conditional execution would probably depend on variables previously set in your format. Remember that the syntax of a special condition in Prism allows whatever is allowed in SPIRES between IF and THEN.

The Validity of Step-Id's

Invalid step-id's

Prism does not verify the validity of the steps you name until they are evoked when your application is running. If, during a data entry session, Prism is unable to find one of the screens you have named, it will terminate the entry process with a system error. (The same holds for processing steps everywhere in Prism.)

"Display Only" Screens

Display only

Note that you can always make the invocation of a "display only" (protected) screen conditional based on end-user preference. For instance, you can code processing steps at form-selection time to ask end-users whether or not they want a redisplay option to be available, then activate your "display-only" screen only if they have said yes.

Note also that if you want to redisplay a screen for confirmation after input into the screen is finished (but before the end-user has typed SEND), you can install its step-id twice, the second time as a "display only" screen. [See 11.3.1 to redisplay a record after it has been added or updated.]

Installing the PREV(IOUS) Option

Although enabling the PREVIOUS option for a multi-page form is usually straightforward, sometimes you will need to make sure that information on all of the screens stays consistent, even though the end-user may have gone backwards with PREVIOUS and changed an earlier page. [See 11.3 For more information on PREVIOUS.]

11.4.1  Other Uses for Processing Steps

As you've seen, entry forms in Prism require at minimum one processing step to identify data entry screen(s). There are a few other places, within Entry Activity but outside the entry cycle (CREATE/GET through SEND/CANCEL), where you could add steps.

The following highly-simplified chart shows how extra processing rules might be applied during the process of form-selection. The horizontal line shows the flow of a basic Prism session, and the boxes below the line show places where your own processing steps and help records would affect a session:

FORM-SELECTION:

 (User          \                       \                             \
  selects ---------------------------------------------------------------
  form)         /                       /                             /
             |                /|\          |              /|\
             |                 |           |               |
            \|/                |          \|/              |
            PROCESSING STEPS               INTRO TO FORM
             (in place of or in             (the ?INTRO help
      (A)    addition to your          (B)  record
             ?INTRO record)

At least one of (A) or (B) is required, so that the form has an introductory screen.

At point (A) of the diagram, you could code a protocol step to perform a "hidden search", if you wanted your entry form always to deal with a particular subset of your file's records. [See 13 for details.]

NOTE: you can also code a protocol processing step (not shown in the diagram) for when end-users leave your form.

11.5  Installing and Modifying Entry Forms: XSETUP FORMS

XSETUP FORMS

To install or modify an entry form for your application, use the XSETUP FORMS command. As with all XSETUP commands for application maintenance, issue the command from within your own application. XSETUP FORMS is one of a family of XSETUP commands with which you may maintain your application. [See 8 for more information about XSETUP.]

...or MOD FORMS

As an alternative to XSETUP FORMS, you may use the MOD FORMS entry form in Prism Profile to install or maintain entry form definitions. Both methods present the same screens to fill in; XSETUP FORMS offers the advantage of being able to modify your application without having to move to Prism Profile.

Here is an example of the first screen of XSETUP FORMS, if you already have at least one form installed. (If you don't yet have any forms, you are taken directly to the screen shown on the next page.)

 _____________________________________________________________________________
 Directory                        XSetup Form                   04/07/90 10:16
                                Select Function
 -----------------------------------------------------------------------------

   _  <-- Type the number of the function you want to perform (1-3).
   1.  DEFINE a new entry form.
   2.  MODIFY or REMOVE an existing entry form.
   3.  CHANGE the order of entry forms on the Prism ENTRY menu.

  ___ <-- For MODIFY or REMOVE, type a number from the list below.
   1.  ADD                   To add a complete directory listing
   2.  UPDATE                To update a directory listing

 _____________________________________________________________________________

Here you indicate the task you want to do -- defining or modifying an entry form, or changing the order in which forms are listed.

The list in the bottom of the screen includes all entry forms currently defined for your application.

Installing a new form

Here is the first screen where you give details about an individual entry form:

 _____________________________________________________________________________
 Directory                        XSetup Form                   04/07/90 10:16
                                STAFFDIR: Form
 -----------------------------------------------------------------------------
 To remove, enter 'R': _

 NAME of form    PURPOSE of this form
 ____________    ________________________________________________

 Enter the format name to be used for this form: ____________________________

 Enter transaction type for this form*: _______
 Enter the type of processing step control (AUTOMATIC or CUSTOM): AUTOMATIC

 Are protocol processing steps compiled? No_
 Indicate all accounts, groups, or access lists that may use this form:
 ____________________________________________________________________________
 ____________________________________________________________________________
 ____________________________________________________________________________

 _____________________________________________________________________________

Streamlining the form

On this screen you can request features to streamline execution of your form and can ask to add processing steps:

 _____________________________________________________________________________
 Directory                        XSetup Form                   04/07/90 10:16
                           STAFFDIR: Form CHANGE PHONE
 -----------------------------------------------------------------------------

 Enter 'Yes' if searching is permitted when this form is selected: Yes
 Enter 'Yes' for an automatic GET when result=1: No_
 Enter 'Yes' for an automatic CREATE when result=0: No_

 Enter 'Yes' for an automatic REVIEW after send: No_

 For REVIEW, use this display defined for the file: FULL____________
         or, use this FRAME defined for the form:   ________________

 Enter 'Yes' to see screens to add, modify, or delete processing steps.
   - when this form is selected or cleared: No_
   - during data entry: Yes

 _____________________________________________________________________________

Declaring screens

On this screen, you declare the individual step(s) making up your entry form, in the order in which they should be executed.

 ______________________________________________________________________________
 Directory                        XSetup Form                   04/07/90 10:16
                STAFFDIR: Transaction Steps, FORM, CHANGE PHONE
 ------------------------------------------------------------------------------
 Please identify processing steps that Prism should execute.  For TYPE,
 enter "S" for a screen step, "P" for a protocol step.  The step labeled PRE
 will be processed after the SEND command is issued.  The step labeled POST
 will be processed after successful completion of the input transaction.

 STEP#    STEP ID       TYPE   TITLE/COMMENT

     1    SCREEN1____     s    First input screen______________
     2    PROC1.......    p    ................................  <--(SCREEN1,
     3    SCREEN2.....    s    Second input screen.............   PROC1, and
     4    ............    .    ................................   SCREEN2 are
     5    ............    .    ................................   sample values
     6    ............    .    ................................   only)
     7    ............    .    ................................
     8    ............    .    ................................
         SEND steps: PRE and POST
   PRE    ............    P    ................................
  POST    ............    P    ................................

 ______________________________________________________________________________

NOTE: for forms previously installed, the step-id's appear automatically. Alter or remove them here if you want.

For a custom-controlled entry form, you would fill out a different screen from this one. [See 12.]

User options

On this screen you declare which command options are linked to each screen, and establish other characteristics of the screens in an automatically-controlled entry form. [See 11.4.]

 ______________________________________________________________________________
 Directory                        XSetup Form                   04/07/90 10:16
                STAFFDIR: Transaction Steps, FORM, CHANGE PHONE
 ------------------------------------------------------------------------------
  PATRON OPTIONS: Enter "Yes" under options allowed for this screen.
  DISPLAY ONLY: Enter "Yes" if the screen data will not be read back.
  DO n TIMES: Indicate the number of times Prism should process this step.
  SPECIAL CONDITIONS: Enter "Yes" to declare or change conditional statements.

                               --Patron Options--   DISPLAY DO n    SPECIAL
 STEP#    STEP ID       TYPE   OK     SEND   PREV   ONLY    TIMES  CONDITIONS
     1    SCREEN1.....    S    Yes    No.    No.    No.     1.      No.
     2    PROC1.......    P    ---    ---    ---    ---     ---     No.
     3    SCREEN2.....    S    ---    Yes    No.    No.     1.      No.

 ______________________________________________________________________________

For all steps, the fields for STEP#, STEP ID, and TYPE are protected.

 - Patron Options. Indicate which commands (SEND,  OK,  and/or  PREVIOUS)  you  want  to  make
 available  to  end-users  when  the  screen  is  invoked during data entry.  (Some of these
 commands are protected for certain screens.)
 - Display Only. If you wish all the fields on the screen to be protected  (i.e.,  unavailable
 for input), change "No" to "Yes" here.
 - Do n Times. Indicate the maximum number of times you would like the screen to  be  invoked.
 - Special Conditions. Change the "No" to a "Yes" for any screen step that
 you would like to be conditionally executed.  (The following screen lets  you  specify  the
 conditions.)

(Note: for custom-controlled entry forms, these options and conditions would be specified in your protocol code.)

Special conditions

If you entered "Yes" under Conditions on the previous screen, here you specify the conditions. (To make the screen clearer, the sample below asks for special conditions for both screens as well as for the Proc.)

 ______________________________________________________________________________
 Directory                        XSetup Form                   04/07/90 10:16
                STAFFDIR: Transaction Steps, FORM, CHANGE PHONE
 ------------------------------------------------------------------------------

 DO ONLY IF: This condition must be true for the step to be done.
 AND THEN CONTINUE AS LONG AS: This condition must be true for every subsequent
                               execution of a step.

     1  SCREEN1      FIRST, DO ONLY IF: .......................................
          AND THEN CONTINUE AS LONG AS: .......................................
     2  PROC1        FIRST, DO ONLY IF: .......................................
     3  SCREEN2      FIRST, DO ONLY IF: .......................................
          AND THEN CONTINUE AS LONG AS: .......................................

 ______________________________________________________________________________

In terms of syntax, anything allowed between IF and THEN in SPIRES is allowed for a special condition in Prism.

Conditions for Screen Processing Steps

IMPORTANT NOTE: the second condition need not be true for the first iteration of the screen, nor need the first condition be true for iterations after the first one.

Conditions for Protocol Processing Steps

Steps for form select

This additional series of processing step installation screens only appears if you ask to "see screens for declaring processing steps" at form selection or clearing:

 ______________________________________________________________________________
 Directory                        XSetup Form                   04/07/90 10:16
                 STAFFDIR: Select/Clear Steps, FORM, CHANGE PHONE
 ------------------------------------------------------------------------------

 Please identify any processing steps that Prism should execute.  For TYPE,
 enter "S" for a screen step, "P" for a protocol step.  TITLE is required for
 screen steps since that title is used to label the screen.

 Processing steps for when form is selected:

 STEP#    STEP ID       TYPE   TITLE/COMMENT               Note:  To remove
     1    ............    .    ................................   a processing
     2    ............    .    ................................   step, delete
     3    ............    .    ................................   the value
                                                                under STEP ID
 Processing step for when form is cleared:

 STEP#    STEP ID       TYPE   TITLE/COMMENT
 CLEAR    ............    P    ................................

 ______________________________________________________________________________

Processing Steps for Form Selection and Form Clearing:

If you have coded screen steps or protocol steps for when your form is selected or when a user leaves the form, declare them to Prism here.

More conditions

On the next two screens (condensed onto one page below), you declare whether your steps for form-selection or clearing should only be invoked under special conditions, and if so, what those conditions are.

 ______________________________________________________________________________
 Directory                        XSetup Form                   04/07/90 10:16
                  STAFFDIR: Select/Clear Steps, FORM, CHANGE PHONE
 ------------------------------------------------------------------------------

 SPECIAL CONDITIONS: Enter "Yes" to declare or change conditional statements.

 Processing steps for when form is selected:

 STEP#    STEP ID       TYPE   CONDITIONS
     1    <step1>.....    S    No.               <----Change "No" to "Yes"
     2    <step2>.....    P    No.                    for any step that you
     3    <step3>.....    P    No.                    want conditionally
                                                      performed.
                                                            /
 Processing step for when form is cleared:                 /
                                                          /
 STEP#    STEP ID       TYPE   CONDITIONS                /
 CLEAR    <laststep>..    P    No.              <-------/

 ______________________________________________________________________________

 ______________________________________________________________________________
 Directory                        XSetup Form                   04/07/90 10:16
                  STAFFDIR: Select/Clear Steps, FORM, CHANGE PHONE
 ------------------------------------------------------------------------------

 DO ONLY IF: This condition must be true for the step to be done a first time.

     1  <step1>      DO ONLY IF: .......................................
     2  <step2>      DO ONLY IF: .......................................

 CLEAR  <laststep>   DO ONLY IF: .......................................
                                      /|\
 ______________________________________|_______________________________________
                                       |
                                       |
                  The blank beginning "DO ONLY IF:" appears only by
                  those steps for which you requested "special con-
                  ditions" on the previous page.  Specify here the
                  condition that must be true for the step to be
                  performed.  Once again, in terms of syntax,
                  anything allowed between IF and THEN in SPIRES
                  is allowed for a special condition in Prism.

11.6  Help Records for Entry Forms

Overview

You will need to install most or all of the following help records for each of your entry forms:

 ?INTRO/FORM/<form-name>       Introductory text for when
                                form is selected

 <form-name> FORM              Text explaining the form for
                                when end-users type HELP
                                <form-name>

 ?ERROR                        One line explanations of error
                                codes

 ?INPUT/FORM/<form-name>/      Context help for each screen
      <step-id>                 of the entry form

?ERROR

The ?ERROR help record contains short explanations of all error codes used in any screen in your Prism application. [See 9.1.1 for details, 11.3.2a for an explanation of how to add error codes to your application.]

?INPUT

For each screen of an entry form, you should create a ?INPUT help record describing the input fields on that screen. This context help record is shown when a user types HELP while on an entry screen. [See 9.1.1 for further information about these help records.]

?INTRO

For each entry form that you install, unless you have screen processing steps to do your introductory work for you, you should write an introductory help record whose key has this form:

E.g., an entry form called MICRO ORDERS would need a help record with a first line as follows:

The record should be no longer than 15 lines (excluding lines with control words like $XFILE) and should tell end-users everything they need to know before using the form, for instance:

Remember that you do not need to explain the mechanics of data entry in general; all you need to explain are the specific features of your particular form.

Screen step at form selection

In some cases you may need to ask for input from your end-users just at the point when they are selecting your form. To accomplish this you can code a screen processing step to appear right after end-users choose the form. This screen can either take the place of the ?INTRO screen or appear in addition to the ?INTRO screen. It would appear before ?INTRO if both were installed. [See 9 for details for coding this screen step.] Remember to install it as part of form-selection processing, not as part of data entry processing (which only includes screens invoked between GET/CREATE and SEND/CANCEL).

<form-name> FORM

The ?INTRO record covers situations where end-users have just selected your entry form. But end-users may also ask for help, specifically naming your form (whether or not they have selected it, or even want to). For instance, in the case of a MICRO ORDERS form, end-users might type HELP MICRO ORDERS simply out of curiosity. There are two different steps you might take to provide this help information:

If your introductory screen implies that an end-user has already selected the form (e.g. "You have now selected the Micro Orders entry form..."), you would have to use the second method listed above to avoid ambiguity.

On the HELP TOPICS menu, if the user has selected a form, one entry on the menu is "Help for the entry form you have selected". If the user chooses that item from HELP TOPICS, the <form-name> FORM record is shown.

$CATEGORY ENTRY

It's recommended that you include a $CATEGORY ENTRY control word in the <form-name> FORM help record, so that it is listed on the HELP TOPICS menu, in the section "Entering data in this file". [See 6.3.5 for an explanation of the $CATEGORY control word.]

If the number of different help records seems confusing, use the Appendix and Index to keep them all straight. [See 6 to see how they are installed.] Help records may be crucial to the success of your application, so it's worth the trouble even to install the optional ones.

12  Custom Control of Data Entry

For applications with complex needs, Prism offers you various ways of customizing the standard application that this document has described so far. This chapter will cover customized control of data entry. [See 13 for a discussion of ways of customizing the search process, 14 for a discussion of a relatively easy way of customizing some of the option text that accompanies your application, 16 for a description of how to install a file to be used for linking behind the scenes (a "secondary" file).]

Custom vs. automatic control

This chapter covers "custom control" of data entry, an alternate method of controlling execution of Prism entry forms. Custom control gives you more power over the entry cycle than the automatic control, but requires a greater command of SPIRES programming. Some of the details that Prism would have taken care of automatically suddenly become the developer's responsibility in a customized application.

This trade-off (of more power for less safety and convenience) makes sense for more complex entry forms. For simple entry forms that do not require much procedural coding, you can use the method described earlier. [See 11.]

If you do choose to control entry form execution by custom processing, you will still need some of the information (e.g., on formats coding standards) presented in the preceding chapter. You still install your entry form through XSETUP FORMS (though in a slightly different manner described below), and you still install help records in PRISM HELP, though the form of the key for some of the records is slightly different.

When Custom Control is Necessary

You will need to customize control of your entry form's execution if any of the conditions below is true:

 - Your form links to another, "secondary" Prism file behind the scenes and  invokes
 screens from that file.  If you wanted to link to a secondary file without invoking screens
 from  that  file,  you could do this within the limits of the automatic method described in
 the previous chapter.
 - Your form potentially adds or updates more than one record per entry cycle (whether or  not
 these multiple records are in the same file)
 - Your form needs  to  control  the  timing  of  opening  and  closing  a  record.   [See  11.3  for  the  method  by  which  this  timing is handled automatically.]
 - You wish to create  "boxes"  on  your  entry  screens  (e.g.,  to  implement  the
 f2=*Choices command).  [See 12A.]
 - Your form needs more steps or more conditions than are allowed in  automatic  installation,
 or needs some other customized feature.

(Note: this is not necessarily an exhaustive list; other situations besides these may call for custom control.)

One Protocol Processing Step for Custom Control

Single protocol step

Whereas in automatic installation, you install each screen of your entry form by its step-id, in custom installation you only install one protocol processing step to run the entire data entry cycle from GET/CREATE to SEND/CANCEL. The step-id of this protocol step corresponds to a Proc or subroutine in the protocol coded for the form. [See 9 for a discussion of protocol processing steps.]

Importance of the custom proc

IMPORTANT NOTE: The single protocol step running a "custom" entry form must contain within its code all of the commands necessary to invoke your screens in their proper order. The Proc must also contain whatever additional protocol code you need for executing the form -- that is, all the coding that you would have put in separate protocol steps for an "automatic" form generally goes within this single Proc for a "custom" form.

Since the procedural code running a "custom" form is no longer separated into multiple steps with distinct step-id's, it becomes your responsibility, within your protocol, to control the flow and timing of the entry form, and make certain that each part executes at the proper time and in the proper order. For instance, if you code a form with two screens and want your end-users on the second screen to be able to return to the first screen with PREVIOUS, you must give Prism specific instructions to this effect in the code that invokes the second screen. [See 12.1.3 for how to do this.] This is completely unlike "automatic" processing, where Prism would automatically know which screen was the "previous" one.

Through the single protocol step for custom data entry, you (and not Prism) become responsible for controlling the flow of screens, listing the correct command options, and opening and closing the record(s) in your application at the proper time. The protocol Proc for custom data entry, like all Procs for Prism, must be structured with a label statement at the beginning and a RETURN statement at the end. The label statement of this protocol step must correspond exactly to the single step-id for form execution that you install in XSETUP FORMS.

Installing a Custom-Controlled Entry Form

Installing custom entry

Installation of a custom-controlled entry form is fairly similar to installation of an automatically-controlled form. [See 11.] The main difference is that in XSETUP FORMS you ask to declare processing steps for custom instead of automatic data entry:

Then, on the following screen, you would enter the single step-id of the protocol Proc that controls execution of the entry form. In addition, if your entry form processes multiple transactions, you should request transaction group processing to make certain the transactions happen in an "all or nothing" fashion. (For more on transaction groups, see the end of this chapter.)

The following charts may help show how custom control of data entry differs in its essential structure from the automatic control described in the previous chapter:

Automatic Control


 (GET or   \   (Prism      (Prism          (Prism                   \
 CREATE) ----- opens   --- calls     ..... calls     --- (SEND) --------
           /   record)     1st step)       nth step)                /

                                         \   (Prism      (Prism      (Prism
                                 ----------- calls   --- closes  --- calls
                                         /   PRE         record)     POST
                                             step)                   step)

In automatic processing, Prism retains control of form-execution and calls your steps in the order that you have installed them. Prism opens and closes the record for you.

Custom Control (simpified diagram):

 (User     \   (Prism                                           (Your Proc
 types   ----- calls your                                       responds to
 GET or    /   protocol step                                    SEND and
 CREATE)       and turns some                                   returns
               control over                                     control to
               to you)                                          Prism)
                   |                                           /
                   |                                          /
                  \|/                                        /
                Within Proc,         Within Proc,    \
           (A)  you ask Prism ...... you ask Prism ---- (SEND)
                to invoke            to invoke       /
                1st screen           nth screen

In custom processing, you take control of the flow and timing of the entry process. Starting at point (A) you use various PERFORM PRISM commands to ask Prism to invoke screens, open records, etc.

12.1  PERFORM PRISM Commands for Custom Control of Data Entry

Special commands

As you saw in the previous charts, custom entry requires you to initiate a number of sophisticated processes from within your protocol code. Prism provides a set of special prepackaged commands to help you accomplish this task. These commands, all of which begin with the words PERFORM PRISM, will be described in detail in this section.

There are also some PERFORM PRISM commands that are designed for customizing the search process in Prism. [See 13.] And other commands are used in routing applications [See 12.3.] and to implement "boxes" on entry screens. [See 12A.]

The PERFORM PRISM Command

PERFORM PRISM

The PERFORM PRISM command is used to deliver high level functions to an application's protocol code. Essentially each PERFORM PRISM command packages together a complex sequence of events related to a single operation, such as prompting the end-user for input. A PERFORM PRISM command not only lets you accomplish a multi-part task through one command, but also guarantees a certain uniformity to the manner in which the task is accomplished.

Some of the functions provided by the PERFORM command are only accessible via the PERFORM command during input processing. Other options duplicate features built into Prism itself, and can be built into procedural code and executed within any protocol step anywhere in Prism.

Summary of PERFORM PRISM Commands for Data Entry

PERFORM PRISM OPEN          - Prepares a SPIRES record
                              for input

PERFORM PRISM CLOSE         - Closes out a SPIRES record
                              that had been opened

PERFORM PRISM ASSIGN        - Forces a specific record to be
  CURRENT                     the "current" record for REVIEW
________________________________________________________________

PERFORM PRISM SCREEN        - Invokes a complete screen, e.g.,
                              to prompt end-user for data

PERFORM PRISM LINK          - Transfers control to a secondary
                              file's environment

PERFORM PRISM UNLINK        - Returns control to the
                              primary file
________________________________________________________________

PERFORM PRISM REMOVE...     - Causes the currently OPENed
                              record to be removed from its
                              data base
________________________________________________________________

PERFORM PRISM GENERATE      - Overlays a display image with
  OVERLAY                     an input screen

PERFORM PRISM OUTPUT        - Allows multiple records to be
PERFORM PRISM INPUT           updated on a single screen.

PERFORM PRISM PAUSE         - Pause from Prism to WYLBUR

[See 13 for PERFORM PRISM commands for searching, 12.3 for commands used in routing applications, 12A for commands used in events and to generate boxes on entry screens.]

A Note on the Form and Syntax of PERFORM PRISM Commands

Most PERFORM PRISM commands can be (sometimes must be) followed by one or more options. Some options are single keywords, while others have associated values. Except where information is placed within quotes or apostrophes, case and punctuation is not significant. You can separate options by commas or by blanks, and can separate values from options either with an equal-sign or with blanks. Options can be abbreviated to three characters.

As in regular SPIRES protocol commands, you can use variables within PERFORM PRISM commands, preceding the command by a slash to force variable substitution:

    /PERFORM PRISM SCREEN screen1, TITLE='#scrntitle' ...

If there is a chance that the variable value contains apostrophes, surround the value with quotation marks rather than with apostrophes.

12.1.1  PERFORM PRISM OPEN and PERFORM PRISM CLOSE Commands

The PERFORM PRISM OPEN and PERFORM PRISM CLOSE commands act together to control adding or updating individual SPIRES records through Prism, especially when record modification involves prompting the end-user for data. In custom data entry, you must first use PERFORM PRISM OPEN to bring a record from the data base into main computer memory, before you can ask Prism to place data into it. Likewise, before creating a new record, the custom entry form must first use PERFORM PRISM OPEN to open space for it in main memory.

The PERFORM PRISM CLOSE command, nearly always paired with PERFORM PRISM OPEN, takes the record in computer memory and puts it into the data base (if it is a new record) or returns it to the data base (if it is an old record newly updated). Thus the natural sequence of a custom transaction is to OPEN a record, prompt the end-user for input into the record, then CLOSE it and send it (new or in changed form) back into the data base.

Not needed in automatic control

Note that in "automatic" control of data entry, Prism itself opens and closes the SPIRES record for you, so you should not need to use PERFORM PRISM OPEN or PERFORM PRISM CLOSE in an automatic form. [See 11.] Rather, you need these two commands when the timing of opening or closing a record becomes too complex for the standard method, or when you have to open more than one SPIRES record during a single CREATE/SEND or GET/SEND entry cycle.

Technical SPIRES Note on PERFORM PRISM OPEN and CLOSE

In SPIRES terms, when you issue the OPEN command, Prism performs a GENERATE REFERENCE or a REFERENCE <key>, and a FOR * command. Thus, internally all input into an OPENed record is by way of merge processing. When you issue the CLOSE command, Prism issues an ENDFOR * and an ADD or UPDATE, as appropriate.

PERFORM PRISM OPEN

The syntax of PERFORM PRISM OPEN is:

  PERFORM PRISM OPEN  {NEW|CURRENT|RECORD='key of record'} | NOUPDATE

The three options, NEW, CURRENT, and RECORD='key', are mutually exclusive, and one of the three must be specified as part of the PERFORM PRISM OPEN command.

PERFORM PRISM CLOSE

The syntax of PERFORM PRISM CLOSE is:

  PERFORM PRISM CLOSE  [NEW | CURRENT | RECORD='key'] [NOUPDATE]

The option NEW, CURRENT, or RECORD='key' is not required on the PERFORM PRISM CLOSE command (as it is on PERFORM PRISM OPEN), but any value you specify should match the value given in the corresponding OPEN command, unless you are deriving a new record from one that was already in the data base. For example:

 legal pair of commands:

    PERFORM PRISM OPEN NEW       <--- Prism assumes you mean
    PERFORM PRISM CLOSE               PERFORM PRISM CLOSE NEW

 illegal pair of commands:

    PERFORM PRISM OPEN NEW       <--- illegal because CURRENT
    PERFORM PRISM CLOSE CURRENT       doesn't match NEW

 legal pair of commands:

    PERFORM PRISM OPEN CURRENT   <--- legal, assuming you want to
    PERFORM PRISM CLOSE NEW           derive a new record from the
                                      current one that you opened

 legal pair of commands:

    PERFORM PRISM OPEN CURRENT   <--- current record opened as if it
    PERFORM PRISM CLOSE NOUPDATE      will be updated, but closed without
                                      updating, for some reason

PERFORM PRISM OPEN Paired With PERFORM PRISM CLOSE

Except in the two cases listed below, every OPEN command must be paired with a CLOSE command -- the two commands work together, and Prism treats an incomplete pair as an error.

 - Exception 1: the PERFORM PRISM OPEN ... NOUPDATE, which asks for a  record  to  be  brought
 into  memory  for  "read" access only, does not usually need to be matched with a
 PERFORM PRISM CLOSE.  You might need PERFORM PRISM CLOSE if subsequent protocol  processing
 requires that no record be open. For example, a SPIRES REMOVE command can't be done while a
 record is open.
 - Exception 2: After opening a record, with PERFORM PRISM OPEN CURRENT,  you  can  remove  it
 with  the  command  PERFORM  PRISM  REMOVE  CURRENT, in which case you should not CLOSE the
 record: [See 12.1.5.]

Issuing two PERFORM PRISM OPEN commands in a row (without a PERFORM PRISM CLOSE in between) is generally an error, but you can have two or more records OPENed simultaneously if one record is in the primary file and each of the other records is in a separate secondary file (a file accessed via the PERFORM PRISM LINK command). [See 12.1.4 for more on the PERFORM PRISM LINK command, 16 for more on secondary files.]

Deriving New Records From Existing Ones

The technique for deriving a new record from one already in the data base is to open an existing record, modify it, and then CLOSE it as a new record:

When deriving a new record from an existing one, you must take care that the source record's key is properly removed or altered in the new record, before it is sent into the data base.

Example of PERFORM PRISM OPEN and CLOSE

In this condensed example, the protocol code opens the end-user's current record (1), issues the PERFORM PRISM SCREEN command [See 12.1.3.] to ask Prism to invoke screens INPUT1 and INPUT2 (2a and 2b), then issues the PERFORM PRISM CLOSE command to send the updated record back into the data base (3).

Multi-Record Transactions Within a Single Form

Although the example above shows a single-record transaction, you can also issue the PERFORM PRISM OPEN and PERFORM PRISM CLOSE commands multiple times within one entry form, if you want your form to update multiple records within a single GET/SEND entry cycle. To the end-user, this transaction should still look like the update of a single record, however. (Some cautions on multi-record updating in Prism are discussed later in the chapter.)

Opening Large Records

Prism tries to accommodate large records by determining the size of the record and setting SUPERMAX to 120% of that size, to guarantee a successful OPEN. If SUPERMAX is already larger than the computed requisite size, the larger value is used. SUPERMAX is restored to its original value after the record is opened.

12.1.2  PERFORM PRISM ASSIGN CURRENT Command

Within an entry transaction, the PERFORM PRISM ASSIGN CURRENT command allows you to force a specific record to be the current record for purposes of the REVIEW or DISPLAY * command, in situations where Prism's usual rules for establishing a current record do not meet your needs.

For example, if you are using multiple PERFORM PRISM OPEN and PERFORM PRISM CLOSE commands to update several records within a single GET/SEND entry cycle, you may wish to specify exactly which of those records should be the one displayed with the REVIEW command at the end of the transaction. (Normally, the last record closed in the primary path is considered the current record.)

The syntax of PERFORM PRISM ASSIGN CURRENT is:

  PERFORM PRISM ASSIGN CURRENT RECORD='key'

12.1.3  PERFORM PRISM SCREEN Command

The PERFORM PRISM SCREEN command invokes a particular screen and displays it online to the end-users of the form. In SPIRES terms, PERFORM PRISM SCREEN invokes a pair of frames from your SPIRES input format, where the names of the invoked frames closely parallel the "screen-id" named in PERFORM PRISM SCREEN. [See 12a.1 for details about Prism screen processing.]

Although most often used in entry forms, PERFORM PRISM SCREEN can also be used in other places in Prism, e.g., to invoke a parm screen in reporting.

Syntax of PERFORM PRISM SCREEN

 PERFORM PRISM SCREEN  screen-id
                       ID = 'id'
                       TITLE = 'title'
                       WRITE | READ | PROMPT | REPROMPT | PROTECT | NOPROMPT
                       OK | OK = 'command'
                       SEND | SEND = 'command'
                       PREVIOUS | PREVIOUS = 'command'
                       CANCEL | CANCEL = 'command'
                       DONE | DONE = 'command'
                       YES | YES = 'command'
                       NO | NO = 'command'
                       OVERLAY = n
                       OPTOK = 'text'
                       OPTSENd = 'text'
                       OPTPREvious = 'text'
                       OPTCANcel = 'text'
                       OPTDONe = 'text'
                       OPTYES = 'text'
                       OPTNO = 'text'
                       ENDPROC = 'step-name'
                       TIMELIMIT = n
                       CURSOR = (row,col) | CMD

In the list of options above, screen-id is required, and the TITLE option is required for most screens (see below). In addition, either OK or SEND must be enabled for any screen except a NOPROMPT screen that is used for post-SEND confirmation.

Screen-id and ID (maximum length 12)

Screen-id is the unique identifier of the screen, corresponding to frame names in your format.

Screen-id is used:

 - To identify format frames that Prism should execute.
 - As  part  of  the  key  of  the  context  help  record  for  the  screen   (in   the   form
 ?INPUT/FORM/form-name/screen-id or ?INPUT/REPORT/report-name/screen-id)
 - In DECLARE SCREEN statements in protocols when events are defined as  part  of  the  screen
 processing

Schematic illustration of how screen-id is used:

 for PERFORM PRISM SCREEN SCREEN1 ...

 screen-id     frame names
 ---------     -----------
 SCREEN1       SCREEN1.IN
               SCREEN1.OUT

 help keys
 -------------------------------
 ?INPUT/FORM/form-name/SCREEN1     (if screen is in entry form)
 ...or
 ?INPUT/REPORT/rept-name/SCREEN1   (if parm screen for a report)

 to define screen events
 -----------------------------------------------------
 DECLARE SCREEN SCREEN1
   ON EVENT CHOICE IN ZONE zone-name, PROC proto-step
   ON COMMAND SEND, PROC proto-step

[See 12a.2 for explanations of DECLARE SCREEN, 6, 10.7, 11.6 to read about help records.]

ID option

The ID option names an ID other than "screen-id" to be used for context helps and for declaring events for the screen. Using ID lets you separate the controls for naming the format frames and identifying the screen for purposes of helps and events.

TITLE = 'title'

In the TITLE option, specify the screen title, to appear in the status area (2nd line of the screen). A title is required except when you are only reading the screen (READ), are reusing an existing screen (PROMPT or REPROMPT), or have created a post-SEND confirmation screen using NOPROMPT.

WRITE, READ, PROMPT, REPROMPT, and PROTECT Options

The processing of a screen consists of three phases -- generating the image via an output frame (Generate), presenting the end-user with the image and waiting for a response (Display), and reading the altered image back via an input frame (Process). The options listed above let you control each part of the process independently in cases where you need program control, say, after the screen is generated but before it is shown to the user. They let you control the timing of screen transmission much more precisely than automatic data entry allows.

                         Generate   Display   Process

        <default>:         yes        yes       yes
          PROTECT:         yes        yes       n/a

            WRITE:         yes        yes       no
             READ:         no         no        yes

         NOPROMPT:         yes        no        no
           PROMPT:         no         yes       yes
         REPROMPT:         no         yes       yes

PROTECT is useful when you have a display-only screen (such as a confirmation screen) that requires no input frame. It also allows you to use a regular screen, one that normally would create input fields, and display it protected, bypassing the input phase.

The WRITE/READ combination provides flexibility in how you process a screen image. For instance, you could use the command to display data from one file (with the WRITE option), next issue a PERFORM PRISM LINK or UNLINK command, and finally read the end-user's input into the linked file (with the READ option). [See 12.1.4.] As another possibility, separate WRITE/READ operations would allow an application to access the same image repeatedly for multiple record processing.

NOPROMPT/PROMPT/REPROMPT offer flexibility in the presentation of the screen image. For example, you may not know until the screen image is generated whether or not OK or SEND should be enabled:

REPROMPT provides a function similar to $STATUS=REPROMPT during screen processing, but allows you to invoke reprompting from within protocol code in cases where the error can only be detected in the protocol, not the format. As with $STATUS=REPROMPT in a format, the REPROMPT option here will cause changed field information to be remembered and transmitted back to your input format. REPROMPT can even be used the first time a screen is written to cause it to behave as a reprompt screen, e.g., any message will be presented BRIGHT and YELLOW, and $ScrnStat will be set to REPROMPT. This is useful in cases where an application is set up to detect errors in existing data and wishes to alert the user when they first visit a screen.

PROMPT is just like REPROMPT, except it does not set $ScrnStat to REPROMPT nor cause any message in $MsgLine to be treated as error messages.

NOPROMPT Option

The NOPROMPT option lets you invoke a confirmation screen to appear after the end-user has typed SEND and a record (or more than one) has been successfully added or updated. The screen occurs "outside" the entry form from the end-user's point of view and so it does not prompt for input or enable paging commands such as SEND or OK. Because of the extra options that appear underneath this screen in Guided Mode, 15 lines is the maximum length for a confirmation screen on a standard 24-line terminal.

A record must be OPENed (1) before its data can be displayed by PERFORM PRISM SCREEN...NOPROMPT (2). In other words, you would ordinarily invoke the NOPROMPT screen (2) before CLOSing the record (3):

If because of SPIRES close-out processing, or for some other reason, you must CLOSE the record before invoking the NOPROMPT screen, you can refetch it using PERFORM PRISM OPEN...NOUPDATE, then PERFORM PRISM SCREEN...NOPROMPT.

You can also use NOPROMPT to invoke an introductory screen at the time of file-, report-, or entry-form-selection. The screen could display variable data unlike a normal help record, but would not enable the OK command.

Enabling Commands: OK, SEND, PREVIOUS etc. Options

The OK, PREVIOUS, SEND, CANCEL, DONE, YES, and NO options enable the corresponding commands for the end-user while the screen (or box) is prompted. You may follow them by a protocol command to be executed if or when the end-user issues the command.

PREVIOUS is virtually always followed by a protocol command to handle branching back to an earlier screen. Custom data entry does not automatically branch back to the "previous" screen, because it has no way of knowing what that screen is.

Details about command presentation at a screen level:

 - SEND is not applicable on parm screens, so is ignored; you must enable  it  on  entry  form
 screens.
 - OK is automatically supplied on parm screens; you must enable it  on  entry  form  screens.
 - CANCEL is automatically supplied on parm and entry form screens.
 - You must enable PREVIOUS on parm screens and entry form screens.
 - None of the commands should be enabled on a NOPROMPT screen.

Boxes

If you are using PERFORM PRISM SCREEN in a box, see the chapter on boxes for a discussion of commands that should be enabled. DONE, YES, and NO are applicable only within boxes. The CANCEL option enables either f8=Cancel (on a screen) or f9=Cancel Box (in a box). [See 12a.6.2.]

Changing commands during an event

During an event proc, you may use the "PERFORM PRISM DISABLE (or ENABLE) pfkey" command to disable or enable commands (function keys) when the parent screen is shown again after the event. [See 12a.16.]

CANCEL = 'command'

You may specify a protocol command to be executed when the CANCEL command is issued by the user on this screen. For example, you might branch to protocol code to perform "cleanup" activities or to set the $NextCmd variable. [See 17.6.] Of course, the current transaction should not continue once the user issues the command, so your CANCEL clause should not present additional screens. Note that the presence or absence of the CANCEL option in your PERFORM PRISM SCREEN command does not control whether or not the command is enabled on the screen -- Prism controls that automatically. The option simply provides a command clause for the case when the command is used.

OVERLAY = n

This option is used in conjunction with a PERFORM PRISM GENERATE OVERLAY command in order to merge an input screen with a display screen image. The "n" here refers to which of a series of generated display images should be shown with the input screen. [See 12.1.6 for details and an example.]

TIMELIMIT = n

This option allows a timeout interval to be associated with the screen read. "n" is an integer, from 1 to 6000, indicating seconds. This option would cause a session that has been idle for "n" seconds to invoke a timeout, cancelling the current process (input, file selection, etc.).

CURSOR = (row,[col]) | CMD

This option lets you specify cursor position on a screen. Row is specified relative to your display, not relative to the "absolute" row on the screen. The CMD option places the cursor on the command line.

OPT... = 'text'

You may control the wording of the Guided Mode options at the bottom of the screen with the OPTOK, OPTPREV, etc. options on PERFORM PRISM SCREEN. Your text may be up to 36 characters long, and it is used after Prism's leading text "Type: <command> ". A trailing period is supplied if it is not included in your text. The option text only appears, of course, if the corresponding command is enabled on the screen.

For example, this command:

would cause the Guide Mode options for screen PAGE1 to appear as:

Prism juggles the option text on the screen to take maximum advantage of the space available, as the relevant command options are presented. Although 36 characters are allowed, some of your text may be truncated if there are two long option text strings on the same line. Prism does the best it can, but it is prudent to check the appearance of the text online in cases of doubt.

Note that the MOD OPTIONS entry form in Prism Profile also lets you control the wording of Guided Mode options. MOD OPTIONS let you control the text for an entire entry form; these options on PERFORM PRISM SCREEN give you control on a screen-by-screen basis.

ENDPROC = 'step-name'

This option lets you specify a protocol processing step to be executed after all other screen work has been done. An ENDPROC protocol step is invoked after the <screen>.IN frame has executed, in response to an OK, PREVIOUS, or SEND command. This protocol step might be used for protocol code that does work not possible in your format, but which must be done to complete a particular screen, for example, lookups or inter-element edits that require PERFORM PRISM LINK or other PERFORM commands. You can think of the ENDPROC protocol step as an extension to your input frame processing.

Resolution boxes

Note that any interaction with the user during ENDPROC processing should be via boxes. One use of an ENDPROC option, in fact, is to name a protocol step to generate a resolution box. [See 12A for complete details about boxes.]

ENDPROC will be phased out

Note that the ENDPROC option is being phased out, in preference to the use of the ON COMMAND statement in the DECLARE SCREEN section of protocols. The new tool lets you declare protocol steps to be executed when specific commands are issued, including CANCEL. [See 12a.1, 12a.2.]

Notes on Screen Control after PERFORM PRISM SCREEN

When PERFORM PRISM SCREEN is issued, control passes from your protocol to the format supporting the screen. After appropriate prompting, control remains with Prism or the format until the end-user types SEND, OK, or PREVIOUS. Prism will process a $STATUS value of REPROMPT or WARN, and will also process the UNDO command. Should a CANCEL request, a timeout, or a system error occur, Prism will clean up the uncompleted transaction, back out of both the PERFORM and the custom Proc, and prompt the end-user for a new command. Some other system-wide commands (including PAUSE, SHOW, SUGGEST, and HELP) also continue to be processed by Prism even within an entry environment.

12.1.4  PERFORM PRISM LINK / PERFORM PRISM UNLINK

The PERFORM PRISM LINK command lets you link your application to a secondary Prism file to which you have authorized access. While the link is in effect any command you issue (e.g., to invoke a screen or to input data into a file) will take place in the secondary file, not in your primary file.

PERFORM PRISM UNLINK breaks the linkage and restores your primary application as the environment in which commands take effect.

For a PERFORM PRISM LINK request to succeed, the file to which your application links must be installed in Prism Profile as a "secondary" file and your application's name (or your account as file owner of the application) must be installed as having access to the secondary file. This process is carried out using the ADD LINK entry form. [See 16.]

The syntax of PERFORM PRISM LINK is:

  PERFORM PRISM LINK file-id [FORMAT format-name]

The LINK command changes the file environment to the secondary file specified by its file-id. You can also name a SPIRES format to be set in the secondary environment to support any screen, menu or other formats processing required there. If the format name contains a blank, enclose the name in quotes.

The syntax of PERFORM PRISM UNLINK is simply:

  PERFORM PRISM UNLINK [CLEAR]

PERFORM PRISM UNLINK removes your application from the environment of your secondary file and returns you to your calling application's environment. The CLEAR option unloads the code associated with the secondary file from memory, increasing efficiency and making more memory available to the rest of your application. It's a good idea to include this option when a LINK is used only once at the start of a select, report or an entry form. It should not be used if a LINK is used more than once, for instance, during searching, printing or an input transaction.

PERFORM PRISM LINK and UNLINK can also be used in protocol steps outside data entry, e.g. to look up information in a secondary file.

PERFORM PRISM LINK and Security

Note that installing a secondary file with the ADD LINK form in Prism Profile is a better way to support linking files than using SPIRES path processing in a protocol step, because of the security offered by the PROGRAM = PRISM statement in the secondary file's file definition, and by ADD LINK. [See 16.] If the SPIRES file definition for a secondary file includes a PROGRAM = PRISM statement in its subfile-section, other Prism applications will not be able to select or link to the secondary file through a path, but only through the PERFORM PRISM LINK command.

Example of PERFORM PRISM LINK

In this condensed example, the protocol code opens and closes a new record in the primary file (1), then performs a link to a secondary file that was installed with file-id TESTLINK (2). At the time of the link it also asks Prism to set the format named "LINK FILE". (This format was written for the secondary file, not the primary, and did not need to be installed or declared in Prism Profile.)

Within the secondary file, the protocol step opens a new record (3), invokes a screen for input (4), closes the new record, and breaks the link, returning to the environment of the primary file. The end-user never needs to be aware at any point that data entry is actually going on in two files, instead of just one.

Multi-Record Transactions and PERFORM PRISM LINK

As mentioned earlier, in general you need to "close" a PERFORM PRISM OPEN command with PERFORM PRISM CLOSE before you issue a second OPEN command. [See 12.1.1.] But this is not the case when the second record is in a linked secondary file. For instance:

(Some cautions on multi-record transactions are discussed later in the chapter.)

12.1.5  PERFORM PRISM REMOVE

The PERFORM PRISM REMOVE command can be used to remove a record within custom data entry. Many record removal entry forms can be simple enough to handle with automatic control and would therefore not need to use PERFORM PRISM REMOVE. [See 11.3.4 for guidelines for designing record removal screens and information about installing an automatic-control entry form for removing records.]

The syntax of PERFORM PRISM REMOVE is:

  PERFORM PRISM REMOVE CURRENT

CURRENT refers to the current record -- i.e., the record that the end-user specified with the GET command.

A removal transaction follows the general pattern shown here:

This is one of the rare cases where PERFORM PRISM OPEN is not paired with a PERFORM PRISM CLOSE command.

Notes on PERFORM PRISM REMOVE

Note that only the currently OPENed record (the CURRENT record) can be removed with the PERFORM PRISM REMOVE command.

Also, once this command is issued, no more screens with frame-type of DATA can be invoked from that record, though other records might be opened with PERFORM PRISM OPEN, and screens with frame-type of XEQ might still be invoked with PERFORM PRISM SCREEN.

Entry forms for record removal should generally be devoted to that one task only. But it's technically possible to install an entry form with transaction type of UPDATE that conditionally issues a PERFORM PRISM REMOVE of the retrieved record.

In addition, there is no way directly to REVIEW a removed record, though you can code a confirmation screen using an XEQ frame to confirm the record's removal after the end-user types SEND.

12.1.6  PERFORM PRISM GENERATE OVERLAY

The PERFORM PRISM GENERATE OVERLAY command supports a technique of generating a multi-page display image and then merging that image with an input screen.

To see an example of how this is used, look at the EXAMINE entry form in the Forms Action file. (See screen sample below.) Briefly, the first input screen that you see when you GET a record in EXAMINE is composed of a section at the top of the screen with a single input field and some text. This part of the screen is generated by the routing application. Below that is a protected area consisting of data formatted by a display format in the sub-application. (That is, Prism's routing application calls the sub-application's display format.)

Forms Action               Entry Form: EXAMINE             02/06/92 16:01
REGISTRATION # 4039                                       Record 13 of 14
   _   <-- Action (A=Acknowledge FYI)
   Enter "A" and type SEND below to indicate that you've seen the form.
   To examine the complete form, add remarks, or add to the routing list,
   leave "Action" blank and type OK below.

-------------------------------------------------------------------------
REGISTRATION # 4039:  Jeffrey Powell -- Registered for DSG.999E. [Last
approved by Stevens on 12/13/91.]
    Student:  Jeffrey Powell
     Course:  SNAP Checks Travel Screens Demo(DSG.224)
       Date:  Location:  Turing Aud (Polya 111  12:00 - 1:30)

    [etc. ... the display image continues]

How is this accomplished? The PERFORM PRISM GENERATE OVERLAY command generates a display image and places it into stored CRT areas. The SPIRES variable $CRTCNT then contains the number of stored screen images (e.g., if the generated display image takes several screens).

The syntax is:

 PERFORM PRISM GENERATE OVERLAY FRAME=frame
                                [RECORD=key]
                                [PROTECT]

Then, a PERFORM PRISM SCREEN command with an OVERLAY=n option tells Prism to merge the screen output with the nth stored display image. To support paging through a multi-screen display image, your protocol needs to use $CRTCNT to keep track of which stored image the user is currently looking at, and how many remain.

Code template

Here is a simple template outlining how these commands might be used:

12.1.7  PERFORM PRISM OUTPUT and PERFORM PRISM INPUT

Interim documentation

Note: These commands have been used for many years in applications maintained by Prism staff, but have never been documented for public use. This documentation is from internal technical notes and may be incomplete; if you have questions, contact DTR staff.

Purpose

The PERFORM PRISM OUTPUT and INPUT commands allow a Prism application to write multiple records to the screen and then process them iteratively on input. Multiple pages (OK and PREVIOUS) are handled by Prism automatically.

To see an example of how this is used, look at the SUMMARY entry form in the Forms Action file. (See screen sample below.) Each of the input fields on this screen applies to a different record.

 Forms Action                Entry Form: SUMMARY              07/17/92 17:41
                                                                  18 records
 ---------------------------------------------------------------------------
 APPROVAL forms - "Actions" are A=Approve, R=Return to originator, H=Hold

 Action  Form and summary (* indicates urgent items)
    __   PURCHASING # A00870: DEMO Standard Requisition Total $14.95 --
             7SKP101-94610 First Account. (Paste pots for Patty)
             [Originated by John Klemm. Last approved by Johnstone on
             03/23/90.  Remarks by Klemm]
    __   PURCHASING # A00872: DEMO Standard Requisition Total $11.80 --
             7SKP101-94610 First Account. (Pencil cup cleaners for Cleo)
             [Originated by John Klemm. Last approved by Nardini on 09/07/89.
             Remarks by Klemm]
    __   PURCHASING # A00873: DEMO Standard Requisition Total $13.30 --
             7SKP101-94610 First Account. (Paper clip detanglers for Denise)
             [Originated by John Klemm. Last approved by Sebald on 08/14/91.
             Remarks by Klemm]
    __   TJOURNAL # 8908730AR: Transfer of Expense  # 730  08/31/89  1 Items
             2 Lines  Tot.Cr 44.97. (Correct charges for film "Basic Dimple
             Removal".) [Originated by John Klemm. Last approved by dietrich
             on 09/21/89.]
    __   TJOURNAL # 8908730AV: Transfer of Expense  # 730  08/31/89  1 Items
             2 Lines  Tot.Cr 31.19. (Correct charges for film "Getting
             Control of Your Armpits".) [Originated by John Klemm. Last
             approved by Gotelli on 09/14/89.]
    __   TJOURNAL # 8908730AZ: Transfer of Expense  # 730AZ  08/31/89  1
             Items 2 Lines  Tot.Cr 75.66. (Correct charges for film
             "Sphygmomanometers: Why so hard to spell?".) [Originated by
             John Klemm. Last approved by Sebald on 08/14/91.]

The entire multi-record sequence is set up in an initial PERFORM PRISM OUTPUT, then a subsequent PERFORM PRISM INPUT is used to read records one at a time. It is similar to GLOBAL FOR processing in SPIRES where a single command (e.g., FOR RESULT) establishes the sequential processing environment while later commands (e.g., DISPLAY) deal with the records one at a time.

The initial PERFORM currently looks like this:

 PERFORM PRISM OUTPUT screen-id
                      [ALL | range]
                      TITLE='title'
                      [NEW | FROM source]
                      [TIMELIMIT=n]
                      [CURSOR='n,m']     <not yet supported>

Records output may be variable in length. You must use PUTDATA=1 in order to trigger overflow when a record is too large for the screen. You must also make sure that the first PUTDATA done will access the highest row required for that record, otherwise partial records may be written.

If multiple pages are generated, Prism allows OK on all pages but the last, PREVIOUS on all pages but the first.

PERFORM PRISM INPUT

PERFORM PRISM OUTPUT only establishes the information required for multiple record processing; it does not actually output any record. This does not happen until you request the first record to be processed. Once the multi-page processing parameters are established, you actually do the processing with the PERFORM PRISM INPUT command:

 PERFORM PRISM INPUT [NEXT]
                     [REFERENCE]
                     END='command'
                     [CURRENT | *]

When this command is issued, Prism will first check to see if the requested record is on the current page. If not, the next (or first) screen of records is generated and shown to the user for input. After the user has input values into the records on the screen and that screen is transmitted back to Prism, then Prism invokes the input frame against the requested record.

Each invocation of PERFORM...INPUT processes the frame against the entire DATA area on CRT. $PARM is set to the starting row for the current record. This way the input frame can start at $PARM and do relative row processing, yet still do a GETDATA on an absolute row,

The END clause is executed when the application requests input from the next record and no more exists, or if the user has typed SEND on the current screen and the last record on the screen had been processed.

The output frame ("screen-id.OUT") must be a DATA frame. The input frame ("screen-id.IN") can be either a DATA for XEQ frame. If it is a DATA frame, each PERFORM PRISM INPUT automatically opens and closes each transaction; nothing else is required of the application. If "screen-id.IN" is an XEQ frame, Prism will merely XEQ the frame against the DATA area on the screen. Processing of any information read from the screen must be done by the application in subsequent protocol statements.

If the REFERENCE option is included in PERFORM PRISM INPUT, Prism will re-fetch the record and drive it through a frame named "screen-id.REF", which must be a DATA frame.

Example

Here is a COMPLETE multiple record process using a DATA input frame:

 ++STEPID
   PERFORM PRISM OUTPUT screen
 ++LOOP
   PERFORM PRISM INPUT, END='RETURN'
   JUMP LOOP

Here's how it looks if the application uses XEQ frames. This gives an application the opportunity to only do an update if data read on the screen is changed.

 ++STEPID
   PERFORM PRISM OUTPUT screen
 ++LOOP
   PERFORM PRISM INPUT, END='RETURN'
   IF ~#CHANGED : JUMP LOOP
   PERFORM PRISM OPEN CURRENT
   USING frame MERGE
   PERFORM PRISM CLOSE
   JUMP LOOP

Note that the "CURRENT" record stays in sync with the record that is being read off the screen.

REPROMPT

Ideally the user should see the screen as just like any other, and if an error occurs they should be able to move about and change anything on the screen. This means that in any REPROMPT situation, Prism reprompts the user, completes the processing of the current record, but on the next PERFORM...INPUT request it backs up to the top of the screen and resumes processing with the first record on the current page. This works fine for UPDATES, but could cause redundant ADDs if reprompting took place during NEW processing. This is an area for future consideration.

12.1.8  PERFORM PRISM PAUSE

The PERFORM PRISM PAUSE command provides a programmatic way to pause from a Prism input screen to WYLBUR, so that a user might work on data in a WYLBUR active file.

Prism manages the transition from Prism to WYLBUR and back to Prism. But your code needs to do everything else, including opening a new active file, doing something with the contents of the active file, and restoring the user's previous active file.

It is recommended that you OPEN a new, temporary, named and titled active file for the user (e.g. OPEN EditText TEMP TITLE 'Edit description').

The syntax is:

 PERFORM PRISM PAUSE TEXT = 'text'

The TEXT option on PERFORM PRISM PAUSE is required. This text is shown after Prism pauses and before the WYLBUR command prompt. Prism itself supplies the message "-Type CONT to re-enter Prism" after your text. (Use // in your text to signal line breaks.)

For example, this command:

would produce this interaction:

Here is a more complete protocol example showing how you might use PERFORM PRISM PAUSE to allow a user to edit data in the active file after activating an on-screen button.

12.1.9  PAUSE in PRISM

In General Access Prism (aka Anonymous Logon Prism or GA PRISM), the PAUSE command is blocked. But in regular Prism, at the "Your Response" prompt, you may respond with the PAUSE command. You are placed in a line-by-line command prompt loop that limits your commands to the list below.

1.  CONtinue  or  RETurn ; gets you back to Prism session.
2.  ?anything  or  HELp anything ; gives you the message:
    -Type CONT to re-enter Prism
3.  EXIt, Quit, END ; all exit you from Prism.
    LOGanything ; also exits you from Prism.
4.  The following do what you'd expect:
    /*anything
    ..protocol (executes protocol from PUBLIC PROTOCOLS)
    SHOw anything
    IN ACTive {CLR|CLN|CONtinue|CLEar|CLEan} SHOw anything
    EXPlain anything
    PERform SYStem something (PRInt, MAIL, SEND, DUMP) ...
5.  SELect, LET, EVAl ; are blocked with error message.
6.  Anything else is sent to the underlying Emulator,
    which may pass it to Unix.  These include:
    a.  SET commands, such as: SET PREFIX ...
    b.  USE, PICK, OPEN, CLOSE, SAVE, ...
    c.  ls, pwd, vi, wylbur, %commands, ...
    d.  Wylbur commands over the interconnecting pipe.
        DELETE, COPY, CHANGE, ...

12.2  Cautions on Multi-Record Transactions

Cautions

There are three important things to consider when you code an entry form that will add or update more than one record:

Transaction Groups

Transaction groups

Because bracketed transaction groups are essential to the success of a multi-record update, Prism provides them for you, as long as you request them within XSETUP FORMS. E.g., for a custom form whose single step-id is CUSTOMSTEP:

  Enter custom processing step-id: CUSTOMSTEP

  Enter 'Yes' if transaction processing is required: Yes

If your form potentially adds or updates more than one record, you should definitely answer 'Yes' to this prompt.

Locking Records

Reserving records

You should take care to reserve exclusive use of all records to be OPENed within a multi-record transaction; you can accomplish this for each individual record by issuing (within your protocol step) the SPIRES command SET RECORD LOCK followed by the key of the record to be reserved.

These locks must also be cleared later so that other end-users can get to them later -- this happens automatically in most cases, but in some situations you may need to issue the CLEAR RECORD LOCK command in order to free records that you earlier locked. See SPIRES documentation on transaction groups and on record-locking for more information.

Hiding Multi-Record Updates in a Single Transaction

Multi-record updates

In the future, Prism may allow end-users to update multiple records within a single GET/SEND or CREATE/SEND entry cycle, but currently each entry cycle works with only one visible record per transaction. For instance, if an end-user has a search result of five records, and has chosen an entry form to modify all the records, each GET/SEND cycle will update only one of the five records in the search result. (The end-user would have to use the GET command five times to modify all five records.) For the sake of consistency with end-user expectations, a multi-record entry form should probably maintain the appearance that a single record is being updated.

The REVIEW Command with Multi-Record Transactions

REVIEW command

The REVIEW command works for customized entry the same way as described earlier. [See 11.3.1.] Normally, Prism assumes that the last record closed in the primary path is the "current" record, so that is the one that is displayed with the REVIEW command.

If necessary, you may use the PERFORM PRISM ASSIGN CURRENT command to force a different record to be the current record for purposes of REVIEW. [See 12.1.2.]

As mentioned earlier,most REVIEW frames are of frame-type DATA. [See 11.] However, you can also code a frame of type XEQ, which Prism will execute without accessing any records. If your end-user's Prism transaction actually updates multiple records behind the scenes, you can code a XEQ frame that provides a summary of all the data entry, displaying values that were assigned to variables during the entry process.

Note on Help Records for Custom Processing

?INPUT help

If you install context help as described earlier for a custom-controlled input screen, the help record's key should identify the screen it supports by "screen-id" rather than by "step-id" (since all your screens are invoked within a single processing step). [See 9.1.1 for installing context help.] The screen-id is the root of the frame-id of the frames supporting the screen -- i.e., a screen CUSTOM1.

12.3  A Note on Routing Applications in Prism

Online forms

In addition to the entry forms described in the last few chapters, Prism also offers a facility for creating routing applications: entry-oriented applications that not only process transactions but also "route" the completed record for approval and action.

Instructions for creating a forms routing application are in a separate manual called "How to Install a Routing Application in Prism". Use the PUBLISH command to print a copy.

The following PERFORM PRISM commands are covered in detail in that document:

 PERFORM PRISM ROUTE             - Invokes the routing page
                                   in Prism

 PERFORM PRISM ASSIGN ROUTE      - Supplies approver names on routing
                                   pages automatically

 PERFORM PRISM ASSIGN ENDROUTE   - Supplies endroute approvers

12a  Extensions to Normal Screen Processing: Events and Boxes

This chapter describes tools and techniques available to control application flow above and beyond the normal screen processing provided by PERFORM PRISM SCREEN:

 - Events: places during screen processing where independent modules of protocols  code  can  be
 executed.
 - Boxes: overlays on top of the background screen image, where you  can  present  new  text  or
 input areas.
 - Zones: designated places on an input screen to which your protocol code might refer, or where
 an action might occur that should invoke an event protocol step.
 - Trigger fields and buttons: input fields that can cause a change in the screen  image  simply
 by the fact that data enters the field.

In addition to describing extensions to the Prism protocols language and providing examples, standards, and guidelines for the use of events, boxes, zones, and trigger fields, this chapter covers a number of PERFORM PRISM commands that are useful with these tools:

 PERFORM PRISM SET SUBAREA        - Defines size and placement of
                                    a box on a background screen

 PERFORM PRISM CHOOSE             - Presents a list of items for
                                    the user to choose from

 PERFORM PRISM PROMPT TEXT        - Prompts text for the user

 PERFORM PRISM PROMPT VALUE       - Provides a simple input field

 PERFORM PRISM COPY               - Copies values to or from a screen

 PERFORM PRISM SET ERROR          - Updates a screen image with an error

 PERFORM PRISM RESET UNDO         - To control scope of UNDO command

 PERFORM PRISM DISABLE pfkey      - Disables or enables commands (and
 PERFORM PRISM ENABLE  pfkey        function keys) in an event proc

12a.1  Explanation of Prism Screen Processing

This section explains what happens during processing of a PERFORM PRISM SCREEN command, how "events" and "boxes" fit into the picture, and what some of your options are for controlling the flow of your application during screen processing.

Events

"Events" are places where your application can take control during screen processing, when one of several pre-defined situations occurs. Events happen within a single PERFORM PRISM SCREEN call, but are independent of your main flow of screen logic. You could describe events as "asynchronous interrupts" (to borrow terminology from other programming languages) or as independent modules of protocols code that may or may not get called from your mainline screen code.

When a screen is presented to a user, there are a number of things that might happen under Prism's control and without application knowledge, such as the user issuing a HELP or SUGGEST command. Prism executes its own code to process the HELP or SUGGEST command and then returns control back to your screen processing code. Similarly, you can think of events as things that can happen during screen presentation in response to some action, where your application (rather than Prism) does have control, but still independent of the main screen flow.

Boxes

"Boxes" are an extension of normal screen presentation in which new text or input fields are displayed in a box that overlays part of the screen. [See 12a.5.1 for examples of boxes.]

Boxes happen in response to events. One of the primary uses of events is to generate boxes on screens, but events may do other things besides present boxes.

Types of events

There are several different types of events whose timing and purpose differ.

 - Choice events -- invoked when a  user  presses  the  f2=*Choices  key  while  his  cursor  is
 positioned in a field labeled with an asterisk. The purpose of a choice event is to present a
 "choice  box"  where  the  user  sees  a  list  of  possible  values for the field.
 - Trigger or button events -- invoked when a trigger field or "button" is  activated.
 The  purpose  of  a  trigger  or  button  event is to present a "trigger box" or to
 refresh a screen image.  [See 12a.4.]
 - Command events -- invoked when a particular command is issued. One use of command  events  is
 to  present  a  "resolution  box".   These  are  also  known  as ON COMMAND events,
 referring to the protocol statement with which they are declared.

Zones

When you declare a choice, trigger, or button event, you also specify a "zone" where the relevant choice field, trigger field, or button is located on the screen. A particular screen might have several buttons or choice fields, each of which might activate its own event protocol step. The zone name links a particular event to the correct protocol step. [See 12a.3.]

Screen processing

First, let's see where events fit into the normal screen processing flow. Then the details of how events are declared in your code will be presented.

                         (A)
    set status restart     PERF PRISM SCREEN         set status restart
 or set status repeat          |                  or set status repeat
       -->>---------->>        | <<----------------<<----------------<<----
      |                        |                                           |
      | set status       (B)   |                                           |
      | reprompt or      .OUT frame                                        |
      | redisplay              |             screen redisplayed (default)  |
      |----->>----->>          | <<----------------<<---------------       |
      |                        |                                    | -or- |
      |                  (C)   |           (D) f2=*Choices          |      |
  if screen       ---<<- prompt screen    -->>-------------->>   event proc
  should display |             |               trigger/button     executes
  again, event   |             |
  proc sets      |       (E)   |
  $status        |       OK, PREV, SEND,
      |          |       YES, NO, DONE
      |      CANCEL            |
      |      (bypasses         |
      |       .IN)       (F)   |
      |          |       .IN frame
      |          |             |
      |          |             |
      |           ---->> (G)   |
      |                  ON COMMAND event
      |                  proc executes
       ------------<<--  (if coded)  **
                               |
                               |
                         (H)   |
                         return from screen
                         processing to
                         mainline code

  (Letters in parentheses refer to notes on the next page.)

Notes on the diagram:

Error Handling Within Events

If an unexpected error happens in an event (such as a PERFORM PRISM syntax error) or if the event explicitly sets $STATUS to STOP or SYSERROR, Prism will terminate the entry transaction. An exception is that if an error occurs in a choice event, Prism will give a message "Error processing CHOICES command" but will not stop the transaction.

What Next?

So what do you need to learn in order to add events and boxes to your application?

 - Examples of Boxes [See 12a.5.1.]
 - Standards and Guidelines for Boxes [See 12a.6.]
 - How to Code Boxes [See 12a.7.]
 - and the sections about the PERFORM PRISM commands that are primarily of use for  boxes  and
 events.  [See 12a.8 and following.]

12a.2  Declaring Events in Your Protocol

DECLARE SCREEN section of protocol

The DECLARE SCREEN section of your protocol lets you specify which protocol step should be executed when particular events occur.

This DECLARE SCREEN section goes in whichever protocol is controlling the screen for which you are declaring events -- in an entry form protocol (when defining events or boxes for an entry form screen) or a report protocol (for an event on a report parm screen) or a file protocol (for an event on an initial parm screen when the file is selected).

The DECLARE section is shown here at the beginning of the protocol, before the first label, but it may occur anywhere in the protocol. Blank lines and comment lines, including control words like -$SUBJECT, may also occur in the DECLARE block.

ENDDECLARE signals the end of the DECLARE section of the protocol.

The DECLARE SCREEN section must be in the main, top-level protocol (the FILE or FORM/form-name or REPORT/report-name protocol). The event proc itself must be located in the same protocol that contains the PERFORM PRISM SCREEN command for the screen being declared. This might be a nested protocol, if your main protocol includes an XEQ FROM or "..protocol" command.

Screen-id

"Screen-id" here should match the "screen-id" or ID in the PERFORM PRISM command for the screen where the event occurs (e.g., the screen where the box will be generated). If several screens share the same event definitions, you may name multiple screen-ids in the DECLARE SCREEN statement.

Screen-ids are specified in the ID parm of PERFORM PRISM CHOOSE, ... PROMPT VALUE, ... PROMPT TEXT, ... ROUTE. For PERFORM PRISM SCREEN, there is both an ID option and the explicit "screen-id" (as in PERFORM PRISM SCREEN "screen-id"). If ID is present, that's the ID to use in DECLARE SCREEN; otherwise use "screen-id". [See 12.1.3.]

Zonename

"Zonename" should match the name in your EVAL $ZONEDEF... Uproc in your input format. [See 12A.3.] If you include the LIKE option, Prism will do stem-matching against the "zonename" and will execute the named protocol step when an event happens in any zone whose name begins with the stem in "zonename". This is useful when you need to create a series of zones to invoke the same protocol code, e.g. multiple buttons for multiple occurrences of a field. [See 12A.4A for an example of this technique.] The $EVENTZONE variable will contain the exact zone name that triggered the current event.

Command-list

The "command-list" after ON COMMAND can be a single command from this list: PREVIOUS, OK, SEND, CANCEL, YES, NO, DONE. Or several commands can be listed inside parentheses if the same protocol step applies to all.

Note that this command list is not what determines which commands are enabled on the screen. That is determined by the commands listed in PERFORM PRISM SCREEN commands (or other PERFORM PRISM commands with similar options to enable commands on the screen). There are no cross-checks between commands you enable with PERFORM PRISM commands and commands you list here in the DECLARE SCREEN section.

Proto-step

And "proto-step" is the label of the protocol step that should be executed when the event occurs. [See 12a.1 for details about events and PERFORM PRISM SCREEN processing.]

Enabling f2 and buttons

It's the presence of an ON EVENT CHOICE... statement that causes Prism to enable the f2=*Choices key on the named screen.

And an ON EVENT BUTTON... statement causes Prism to create a button on the screen, as long as the corresponding EVAL $ZONEDEF Uproc to define the button's zone has been executed in your format.

Nested events

The maximum number of nested events possible is 8. [See 12A.6.3 for an example of nested events.]

Upper limits

Prism allows a maximum of 160 declared "resources" per file select, 120 of which may be events. "Resources" include preloaded code (via the DECLARE PRELOAD statement), declared events, and also resources that Prism loads on your behalf (such as code needed for a routing application to work).

The ENDPROC Option on PERFORM PRISM SCREEN

The ENDPROC=step-name option on PERFORM PRISM SCREEN is an alternative way to declare a protocol step to be executed for a "command event". However, it is more limited than the ON COMMAND declaration and is being phased out of Prism.

An ENDPROC step will be executed when OK, PREVIOUS, or SEND is issued by the user.

ON COMMAND Events Compared to <command>= on PERFORM PRISM SCREEN

It's important to understand the difference between nested event steps and mainline flow-control statements. For example, in the code sample below, there are two places where the protocol specifies things to happen when the SEND command is issued:

    DECLARE SCREEN INPUT1
      ON COMMAND SEND, PROC VERIFY
    ENDDECLARE

    ++START
    PERFORM PRISM SCREEN INPUT1, OK, SEND='JUMP DONE'
    PERFORM PRISM SCREEN INPUT2, SEND
       :
    ++DONE
       :
    RETURN

    ++VERIFY
       :
    RETURN

The VERIFY step is a part of the internal processing of the screen. As a nested event, it allows screen REPROMPTs and REPEATs. The SEND='JUMP DONE' clause is simply a mainline statement to branch past an optional second screen. That JUMP executes after the screen has successfully completed processing, which includes any ON COMMAND procs. [See 12a.1.]

Controlling CANCEL BOX

It would technically be possible to present a resolution box by means of protocol code in either the VERIFY event step, or the DONE step. However, your application must do more work if a box is presented as part of the mainline code rather than in an event step. When the box occurs in an event step, Prism automatically keeps the mainline (screen) level environment distinct from the box level code. CANCEL BOX is supplied as specified, and subareas are automatically discarded after the event. If the box occurs as part of mainline code, you must specify what happens as a result of a CANCEL BOX command. That is, you must use the CANCEL='command' option (e.g. on PERFORM PRISM CHOOSE or PERFORM PRISM PROMPT VALUE) to explicitly clear any subarea in effect and branch back to repeat the screen the user was on when the resolution box occurred.

12a.3  Defining Zones on an Entry Screen ($ZONEDEF)

In order to create a choice or trigger or button event, you must define "zones" on your entry screen in which the event will occur. Zones are created in the output frame of your input format, using the $ZONEDEF function. You refer to zones by name in the DECLARE SCREEN section of a protocol. [See 12A.2.]

You can also refer to stems of zone names. One use of this technique is when you want to define multiple zones for multiple occurrences of elements or structures, each of which might have an event associated with it. In this case, you might want to add an occurrence counter to the zone names that you create with $ZONEDEF. [See 12A.4A for a complete example of how to do this.]

Zones may also be used with the PERFORM PRISM COPY command, which provides a way to copy values to and from a screen image. [See 12a.14.]

Syntax

The syntax of the $ZONEDEF function is:

Example

Here is an example of how to use $ZONEDEF in a format label group:

Notice that a zone does not have to correspond to a data field. Here, a zone has been defined to encompass both the title and the field. This example illustrates a zone supporting a choices event. The user can have his cursor either on the title or within the field, and a choices event for "Application ID" will work. This code example matches up with the Prism screen example shown in full in 12A.5.1 and excerpted here:

Using * to label fields with choices

The sample label group shown above also illustrates another item in the coding checklist for choice boxes. Notice that the label for the "Application ID" field includes an asterisk, to alert the user that choices are available. [See 12A.6.1 for more on labeling fields for choices.]

SPIRES Techniques For Finding Information About Defined Zones

When you create zones for use on Prism screens, you are using SPIRES Device Services coding techniques. (Prism itself uses Device Services capabilities to create its full-screen interface.)

There are a few Device Services techniques that you may find useful in managing your Prism zones. They are summarized here, in the context of Prism coding, and are fully documented in the manual SPIRES Device Services.

SHOW ZONES command

While your code is executing in Prism, you might find it helpful to exit to SPIRES and issue the SHOW ZONES command. This command displays information about the zones currently defined. For example

(Here, GUIDED.INPUT is the value of $AREANAME and $SCRNAREA while this Prism code is executing in Guided Mode.) EXPLAIN SHOW ZONES in SPIRES for further information about this command.

Note that SHOW ZONES will sometimes include information about zones that Prism itself defines, as well as those defined by your application. In particular, when a choice box is generated, Prism defines zones for the input fields in the box. Zones that Prism defines have names that start with "$". You can refer to these zones in coding your event procs, just like zones that you define yourself. [See 12A.10.]

$EVENTZONE variable

The $EVENTZONE variable holds the name of the zone that triggered the current event.

$GETAREA function

You can use the $GETAREA function to determine 1) the current row and column position of the user's cursor on the screen, and 2) which zone is associated with that particular location on the screen.

Why would you need to do this? If you have a series of trigger fields or buttons on the screen, all of which invoke the same code (e.g., for multiple occurrences of an element or structure), you might need to figure out which occurrence of the element you are dealing with. You could define separate zones for each occurrence, but this is awkward. An alternative is to define one larger zone encompassing all occurrences, and then use techniques described here to determine where the user is in the zone.

Here is a composite example; each statement is explained in the paragraphs following:

The first two statements determine the position of the cursor:

The CRow and CCol options refer to the current row and column of the cursor within the uncontained CRT area. CRow is an absolute position, and includes the top two status lines on the Prism screen.

Then, using this cursor position information, you can find the zone number for this position on the screen area:

(If no zone is found for that location, "0" is returned.)

This statement uses $SCRNAREA instead of CRT for the area name. $SCRNAREA is a SPIRES variable that is managed by Prism, that contains the name of the area currently active within the CRT area. (And $AREANAME is a variable available in formats, with the same information). Here is a graphic representation of these two areas:

      ------------------------------------             <---
     |   status line 1                    |                |
     |   status line 2                    |                |
     |....................................|                |
     :                                    :  <---          |
     :                                    :      |         |
     :   the data area on a Prism screen  :   $SCRNAREA    |the CRT area
     :                                    :   $AREANAME    |
     :                                    :      |         |
     |....................................|  <---          |
     |   message line                     |                |
     |   options text                     |                |
     |   function key list                |                |
      ------------------------------------             <---

Note that the #CursorRow variable was decremented by 2 to account for the two Prism status lines, since $SCRNAREA was used as the area name in this $GETAREA statement.

And you can use this zone number to determine the corresponding zone name:

For complete details about this function, type EXPLAIN $GETAREA in SPIRES.

Of course, you could combine all of these operations into one statement, if you wish:

Other uses of $GETAREA

As mentioned at the beginning of this section, zones are used with PERFORM PRISM COPY, which lets you read values from a zone, or write values to a zone. In some situations, when PERFORM PRISM COPY and zones don't meet your needs, you might need to use $GETAREA (and its companion function $PUTAREA) to read and write values directly. [See 12a.14 for an explanation of PERFORM PRISM COPY, 12a.14.1 for examples of using $GETAREA and $PUTAREA.]

12a.4  Trigger Fields and Buttons

What is a Trigger Field?

A trigger field is a field on an input screen in which user input automatically triggers a change in the screen, without the OK, SEND, or PREVIOUS commands being issued.

What kind of change might occur on a screen when a trigger field is activated?

How Do You Implement Trigger Field Processing?

Several different techniques are possible for implementing trigger behavior on a screen:

 - You might use formats processing entirely. This is likely if you want input  into  a  trigger
 field to cause highlighting on the screen or to rewrite the screen with new data.
 - You might use protocol processing entirely, in a trigger or button event.  This is likely  if
 you want to create a button that generates a trigger box on the screen.
 - Or, as you might guess, you can use a combination of formats  and  protocol  processing.  You
 might  need  protocol  control  but  also need to invoke your .OUT frame again to rewrite the
 screen.

What is a Button?

A "button" is a trigger field with specific characteristics managed by Prism itself. It is a 1-character trigger field, displayed in reverse video with a "+" symbol inside the reverse-video block, and with a text label (that your application supplies) telling the user what will happen when the button is activated (e.g. "Type an "X" on this button to see a complete course description"). [See 12a.6.1 for guidelines for labeling buttons and trigger fields.]

Buttons were designed as the recommended presentation for trigger fields whose purpose is to provide a place where the user "clicks" to cause something (perhaps in a box) to happen.

Formats Coding for Trigger Fields and Buttons

How to create a trigger field

To create a trigger field, define an input field with LENGTH of 1 to 10 and DISPLAY = TRIGGER. (An alternative, DISPLAY = WRAP, is possible for trigger fields longer than one character. See below for an explanation of the difference between these two options.)

If the trigger field will be used to invoke a trigger event, you must define a zone to encompass the trigger field. That's what the EVAL $ZONEDEF statement above does. [See 12a.1, 12a.3.] Along with defining the trigger field in your format, your protocol supporting the entry screen must declare a "trigger event" and define a protocol step to execute during that event. Then, input into the trigger field will cause that code to execute, generating a box on the screen or otherwise changing the screen image. For example:

How to create a button

To create a button, define a 1-character zone in your input format. Then declare the button in the protocol supporting the screen.

This coding causes Prism to know that the 1-character zone should be treated as a button. Prism generates the reverse-video block and the + sign inside the block. [See 12a.3 for more about defining zones.]

"Conditional" buttons

Note that the ON EVENT BUTTON... statement by itself does not cause Prism to create the button on the screen. Both the protocol statement and the zone definition have to happen in order for the button to display. One implication of this is that your format can include logic to bypass the zone definition, if you want a button to display in some circumstances but not others.

Other format considerations

If the trigger field will be used for screen-refresh, you must include logic in your input frame to recognize input in a trigger field and cause something appropriate to happen on the screen.

Note that the discussion of "Details of Trigger Field Processing" below is generally not needed for trigger fields or buttons used for trigger boxes. The exception to this is if you come back to your main screen after a trigger box with a REPEAT or RESTART status (i.e. if you need to invoke your .OUT frame again). In that case, the details are relevant to your code.

DISPLAY = TRIGGER and DISPLAY = WRAP

For trigger fields longer than one character, there are two possibilities. First, you may define the field so that input into any character position causes the trigger to happen (DISPLAY = TRIGGER). Or you may use DISPLAY = WRAP to specify that the trigger shouldn't be activated until the last character position is changed.

If you know that a trigger field will always be completely filled in, you might choose to use DISPLAY = WRAP so that the "triggering" happens when the last character is changed. In other cases, DISPLAY = TRIGGER would be better. For example, you might want a 2-character trigger field, to accommodate input of numbers from 1 through 99. You want the trigger to cause highlighting of the item the user chooses. With DISPLAY = WRAP, the trigger would only be activated if a 2-digit number were typed (or if a single digit were typed into the last position in the field). With DISPLAY = TRIGGER, highlighting would happen even if a single number is typed in the first character position.

Word wrapping vs. trigger fields

Trigger fields with DISPLAY = WRAP use the same mechanism as fields with automatic word-wrap. In both cases, model terminal code in the front-ends signals Prism that input has happened in a field with a WRAP attribute. The distinguishing factor is the length of the field. The current system assumes that a 1 to 10 character field on a single row with DISPLAY = WRAP is a trigger field. Any field 11 or more characters and taking more than 1 row (and with DISPLAY = WRAP) invokes the automatic word-wrap. Simple word-wrapping (and invocation of a trigger "event" for trigger boxes) is handled by Prism without involving any application code. Trigger field processing for screen-refresh involves a cycle of events described below.

Restriction for 327x terminals

Note that VTAM terminals (327x models) do not support trigger field processing at all. Currently, f12 is used as an explicit substitute.

What Happens During Trigger Field Processing?

Trigger processing is handled within PERFORM PRISM SCREEN and its associated format frames:

Details of Trigger Field Processing

The user may have input data on the screen besides the value in the trigger field. When the trigger is processed, you want to respond to the trigger, but probably not do normal data edits. That is, when the screen is refreshed for the user, you wouldn't present the error codes that you might when you are processing an OK or SEND command.

To do this, you can process user-input data on a trigger screen via variables in order to bypass PUTELEMs and GETDATAs. For example:

Input frame

Input in a trigger field causes frame.IN to execute with $ScrnStat = 'TRIGGER'. Frame.IN tests $ScrnStat for 'TRIGGER' and branches accordingly. The trigger-processing component of frame.IN must then instruct Prism to execute frame.OUT again by including the Uproc SET STATUS='REPEAT' or SET STATUS='RESTART'.

The difference between the statuses REPEAT and RESTART is the scope of UNDO: if $Status = 'REPEAT' when Prism starts to execute frame.OUT, UNDO will restore the screen to what it was just prior to trigger processing; if $Status = 'RESTART', UNDO will restore the screen to what it was when Prism first executed frame.OUT for the current PERFORM PRISM SCREEN.

For each non-trigger input field that has changed, be sure to update the corresponding variable with $UVal so that the user's latest input doesn't get "undone". The trigger field itself is a special case: update its variable or not depending on whether the triggering value should stay there when the screen is repainted.

As well as bypassing all PUTELEMs during trigger processing, be sure to bypass all inprocs and other edits. Otherwise, unexpected errors may pop up in response to a trigger processing. The only edits should be those that pertain to the trigger field itself.

Output frame

Frame.OUT tests $ScrnStat for 'REPEAT' or 'RESTART' and branches accordingly.

By default, the cursor will appear in the next input field past the trigger field. If the trigger field was the last field on the screen, the cursor appears in the command line. To alter default cursor positioning, use one of the following uprocs:

Is a Picture Worth a Thousand Words?

12a.4a  Coding Technique for "Multiply-Occurring Zones"

This section describes a technique to use stem-matching of zone names in order to refer to groups of zones in ON EVENT declarations. The most direct application of this technique is to support multiple buttons or trigger fields on an entry screen, in a situation where you have multiple occurrences of a field or structure, each of which needs to have a button or trigger field associated with it.

For example, the screen below is from the New Patients file, which is a demonstration application used to help teach people how to make Prism applications. The bottom half of the screen has a series of lines for multiple occurrences of a VISIT structure, with information about each visit this patient has made to the doctor. The "Code" is a trigger field; if you type a valid code in that space, the "Treatment Name" area is automatically updated with the code expansion.


=============================================================================
NEW Patients                  Entry Form: ADDUPD2         07/22/91 11:12 PEAK
Patient Demographic Data                                        Record 5 of 9
-----------------------------------------------------------------------------

     NAME:       Programmer,_Ace_____   Type an 'X' to view/modify Notes... +
                                            No notes for this record.
     ADDRESS:    273_Silicon_Ave.____
                 Homebody,_IO_84501__
                 ____________________

     VISIT INFORMATION - To remove a visit, mark an X under '(Delete)'
No.   (Delete)   Date       Code*   Treatment Name                       Cost
-----------------------------------------------------------------------------
1)       _       05/13/83    E66    Eye strain relaxant             ____$9.40
2)       _       02/20/84    X12    Shot in the arm                 ____$5.00
3)       _       ________    ___                                    _________
4)       _       ________    ___                                    _________
5)       _       ________    ___                                    _________
6)       _       ________    ___                                    _________

-Form continues on the next page
Type: OK below to continue to next page.  Use CHOICES key for fields marked *
      SEND to complete this transaction.  CANCEL to cancel transaction.
YOUR RESPONSE:
f1=Help f2=*Choices           f5=OK f6=Send f7=Undo f8=Cancel      f0=Display
=============================================================================

Each trigger field needs to do the same work -- looking up the code in a table and copying the expansion onto the screen (using PERFORM PRISM COPY). A single proc can take care of this; the tricky part is keeping track of which VISIT occurrence you're dealing with.

Declare the event in the protocol

First, here's the event declaration for this part of the screen:

IN ZONE LIKE TREATMENTCD here means that the EV.COPY.TNAME proc will be executed when a trigger field is activated in any zone whose name starts out with "treatmentcd". [See 12A.2 to read about the DECLARE SCREEN section of a protocol.]

Define the zone in the format

In the format for this screen, an indirect frame deals with the VISIT structure, generating the four input fields on each line (one line is one visit structure) and defining a zone for each "Code" field. Each "Code" zone has a name that includes the visit occurrence number as a suffix. (As SPIRES loops through the indirect frame, the visit occurrence counter is incremented by the format in the calling label group.)

The "Treatment Name" area is also given a zone name with an occurrence counter, since the protocol will be using PERFORM PRISM COPY to copy the code expansion into that zone. [See 12A.14.]

Here's what the SHOW ZONES command tells us (this is an excerpt):

And here are the label groups in the format that create the zones for "Code" and "Treatment Name": [See 12A.3 to read about defining zones.]

Here is the EV.COPY.TNAME proc that does the work of looking up the code and copying the expansion into the correct line:

Note that this proc uses the $EventZone variable to determine exactly which zone (which trigger field) has been triggered in the current event.

If you would like to see the complete format or protocols code for this screen, or if you have questions about the techniqes illustrated here, contact Peter Tuttle.

12a.5  Boxes

Most of the rest of this chapter describes the use of on-screen "boxes" -- an adjunct to normal screen presentation in which new fields or information are displayed in a box that overlays part of the screen, in response to some event on that screen.

3 types of boxes

There are three types of boxes, corresponding to three ways in which they are invoked:

Boxes appear on top of a screen image, and the background screen is disabled. Part of the box paradigm is the ability to return to that background screen, either optionally or implicitly as a natural result of finishing an interaction with the box. Choice and trigger boxes always take the user back to the original screen, while resolution boxes should allow the user to continue to the next screen if the conflict can be resolved, or to return to the original screen for other actions.

Function key labels appear inside a box, to remind the user of the navigation commands available. At the same time, all of the normal function labels at the bottom of the screen are disabled and dimmed by Prism, except for f1=Help, which is always available.

Boxes on Prism screens are similar to dialog boxes on a Macintosh. Some of the standards and guidelines recommended here for format and placement of boxes, and navigation between the box and the main screen are meant to reinforce this image for users.

Prism provides tools to define the size and placement of a box, as well as tools to easily place in a box a choice list, text, or a simple input field. You may also use PERFORM PRISM SCREEN and a format to provide the contents of a box.

12a.5.1  Examples of Boxes

Example of a Choice Box

Choice box

Here is an example of a screen on which the f2=*Choices key is enabled. Two fields on this screen -- "Application ID" and "Reported Incident Type" -- are labeled with an asterisk, indicating that the CHOICES command is available to provide assistance for those fields.

Prism enables the f2=*Choices key on any screen for which a choices "event" is defined in the supporting protocol. It is up to your application code to define those choices events (i.e. what should be shown to the user when f2=*Choices is pressed and where the box should be drawn on the screen) and also to include an asterisk in the applicable field labels on the input screen. [See 12A.2 for how to define a choices event, 12A.6.1 for standards for labeling input fields.]

XSAQA Incidents             Entry Form: INCIDENT            08/07/90 16:20
INCIDENT INFORMATION
--------------------------------------------------------------------------

   Incident No.: 100239    Incident Date: 08/07/90

   JES2 Job No.: ____      Job Time (HHMM): ____    Number of Retries: ___

   Application ID* ________________________________

   Reported Incident Type* ___
   Reported By: Jimmie Burgess
     Contacted* ________________________________________

-------------------------- Incident Description --------------------------
__________________________________________________________________________
__________________________________________________________________________
__________________________________________________________________________
__________________________________________________________________________
__________________________________________________________________________

Type: OK below to continue to next page.   CANCEL to cancel transaction.
      Use CHOICES key for fields marked *. UNDO to discard changes to page.
YOUR RESPONSE:
f1=Help f2=*Choices                f5=OK        f7=Undo f8=Cancel

Here is what happens when the user places the cursor in the "Application ID" field and presses f2=*Choices. Note that the choices box is placed in close proximity to the field to which it applies. You determine how big the box is and where it is placed, as well as what values are listed as choices. (Prism automatically provides the "paging" mechanism for long lists that don't fit in one page of the box.) You also control the wording of the explanatory text in the box.

XSAQA Incidents             Entry Form: INCIDENT            08/07/90 16:20
INCIDENT INFORMATION
--------------------------------------------------------------------------

   Incident No.: 100239    Incident Date: 08/07/90

   JES2 Job No.: ____      Job Time (HHMM): ____   Number of Retries: ___

   Application ID* ________________________________
       *--------------------------------------------------------------*
   Repo| __ <-- Choose one from the list below.                       |
   Repo|     1. ADMUTD, SSA DAILY AND RELATED FILES                   |
     Co|     2. ADMUTN, AIS-SSA Communication Programs                |
       |     3. ADMUTP, PMT Processing Program                        |
-------|     4. ADMUTS, SSA SUPPORTED COMPONENTS                      | --
_______|     5. ADMUTU, USER STAGING PROGRAMS                         | __
_______|     6. AUTOSAQA, AutoSAQA online                             | __
_______| (No. 1-6 of 50)                                              | __
_______|          f3=Done         f5=OK                 f9=Cancel Box | __
_______*--------------------------------------------------------------* __

Type: OK to continue forward.     CANCEL BOX to cancel box.
      DONE to leave this box.
YOUR RESPONSE:
f1=Help f2=*Choices                f5=OK        f7=Undo f8=Cancel

Choice is copied for the user

When the user picks an item from the list and presses f3=Done, the value from the list is automatically copied back into the entry field on the main screen and the box is "closed", returning the user to the screen from which the f2=*Choices command was issued. You have control over exactly what is copied back onto the main screen.

Multiple or single choices

The example above illustrates a choice box asking for a single choice; you may also provide a list where multiple choices are possible. You also can use the value of the $FIELDVAL variable (which contains any value the user may have typed in the input field before pressing f2=*Choices) to limit the scope of the list in the box. These features and other details of choice boxes are explained in a later section. [See 12A.7.]

Example of a Trigger Box

Below is an example of a screen that employs a trigger box. To implement a trigger box, you would code a trigger field on your input screen and label it so that it's clear to the user what to do. And in the protocol code for this screen, you would define the placement and contents of the box that will be drawn on the screen in response to the trigger field. [See 12A.4 to learn how to code trigger fields, 12A.6.1 for guidelines for use and labeling of trigger fields.]

Here is the sample screen with a trigger field (the "Add Component->" field).

XSAQA Applications           Entry Form: APPLICATION           08/09/90 08:45
APPLICATION COMPONENTS
-----------------------------------------------------------------------------
To add a component description to TAPELOAD, mark the ADD button. To modify a
component description, mark the button next to the appropriate ID.

 Modify  Component ID                     Component Name (or Type)
         Add Component-> _                Borrow Component-> _
 _    1. LOADING.ROUTINE                  (Submit Job)
 _    2. MARC.CONVERSION                  (SPIRES Format)
 _    3. TAPE.BACKUP                      (Submit Job)

-Form continues on the next page
Type: OK below to continue to next page.   PREVIOUS to return to prior page.
      SEND to complete this transaction.   CANCEL to cancel transaction.
YOUR RESPONSE:
f1=Help               f4=Previous f5=OK f6=Send f7=Undo f8=Cancel

When the user types a value in the trigger field, the box is drawn on the screen. Note that neither OK nor SEND is required to cause the screen to be rewritten, but simply input into the trigger field.

Here is the screen with the trigger box drawn.

XSAQA Applications           Entry Form: APPLICATION           08/09/90 08:45
APPLICATION COMPONENTS
-----------------------------------------------------------------------------
To add a component description to TAPELOAD, mark the ADD button. To modify a
component description, mark the button next to the appropriate ID.

 Modify  Component ID                     Component Name (or Type)
  *------------------------------------------------------------------------*
 _|      Component ID: ________________________________                    |
 _|    Component Name: __________________________________________________  |
 _|    Component Type* __                                                  |
  |                                                                        |
  | ----------------------- Component Description -----------------------  |
  | ____________________________________________________________________   |
  | ____________________________________________________________________   |
  | ____________________________________________________________________   |
  | ____________________________________________________________________   |
  | ____________________________________________________________________   |
  | f2=*Choices f3=Done                                      f9=Cancel Box |
  *------------------------------------------------------------------------*

Type: DONE to leave this box.     Use CHOICES key for fields marked *.
      CANCEL BOX to cancel box.
YOUR RESPONSE:
f1=Help               f4=Previous f5=OK f6=Send f7=Undo f8=Cancel

As in the earlier example of a choices box, f3=Done takes the user back to the main screen after the box is filled in. (Or if he starts filling out the box and changes his mind, f9 will cancel the box and return to the main screen.)

Nested boxes

Note that this box itself has a field for which f2=*Choices is enabled; this illustrates how you can provide "nested" boxes when appropriate. Here is the screen after f2=*Choices is used for the "Component Type" field.

XSAQA Applications           Entry Form: APPLICATION           08/09/90 08:46

-----------------------------------------------------------------------------
To add a component description to TAPELOAD, mark the ADD button. To modify a
component description, mark the button next to the appropriate ID.

 Modify  Component ID                     Component Name (or Type)
  *------------------------------------------------------------------------*
 _|      Component ID: archive_________________________                    |
 _|    Component Name: Archive tape *--------------------------------------*
 _|    Component Type* __           | __ <-- Choose one from the list      |
  |                                 |        below.                        |
  | ----------------------- Componen|     1. SPIRES Component (%)          |
  | ________________________________|     2. SPIRES File Definer (%D)      |
  | ________________________________|     3. SPIRES File Definition (%F)   |
  | ________________________________|     4. SPIRES Format (%G)            |
  | ________________________________|     5. SPIRES Protocol (%P)          |
  | ________________________________|     6. SPIRES Record Definition (%R) |
  | f2=*Choices f3=Done            f| (No. 1-6 of 57)                      |
  *---------------------------------|    f3=Done   f5=OK     f9=Cancel Box |
                                    *--------------------------------------*

Type: OK to continue forward.     CANCEL BOX to cancel box.
      DONE to leave this box.
YOUR RESPONSE:
f1=Help               f4=Previous f5=OK f6=Send f7=Undo f8=Cancel

Examples of Resolution Boxes

Below are some examples of resolution boxes. Resolution boxes are used when you detect a condition needing some resolution while processing a user's OK, PREVIOUS, SEND, or CANCEL command, and the resolution can be handled most naturally and effectively by a box interaction rather than flashing error codes on the screen. [See 12A.6 for further guidelines.]

Here is an example of how a resolution box might be used. The (abbreviated) sample screen below lets the user specify a delivery method. Some of those methods require a small additional bit of information, which could be requested in a resolution box at the time the user issues an OK or SEND command.

SNAP                       Entry Form: CHECK REQUEST           08/09/90 09:24

-----------------------------------------------------------------------------

    Check Amount: _______________
         :
       Payee SSN: ___________
      Payee Name: __________________________________
         :
         :
         :
         :
         Send by: _ I(D Mail), U(S Mail), W(ill Call), C(ourier)
         :

Type: OK below to continue to next page.    PREVIOUS to return to prior page.
      SEND to complete this transaction.    CANCEL to cancel transaction.
YOUR RESPONSE:
f1=Help               f4=Previous f5=OK f6=Send f7=Undo f8=Cancel

If the user specifies delivery by ID mail, this resolution box would appear:

SNAP                       Entry Form: CHECK REQUEST           08/09/90 09:24

-----------------------------------------------------------------------------
                             *------------------------------------------*
    Check Amount: ___________|               ID Mail Address            |
         :                   |                                          |
       Payee SSN: ___________|  In care of: __________________________  |
      Payee Name: ___________|  Department: __________________________  |
         :                   |     Address: __________________________  |
         :                   |              __________________________  |
         :                   |        f5=OK               f9=Cancel Box |
         :                   *------------------------------------------*
         Send by: _ I(D Mail), U(S Mail), W(ill Call), C(ourier)
         :

Type: OK to continue forward.
      CANCEL BOX to cancel box.
YOUR RESPONSE:
f1=Help               f4=Previous f5=OK f6=Send f7=Undo f8=Cancel

After the user fills in the box and issues the OK command, his previous command (OK or SEND) would be processed and the transaction would continue as usual.

Another example, already common in Prism routing applications, is the "name resolution box" that is shown when you enter a non-unique name on an identification screen. Here is an example:

Forms Action                       Search                      08/09/90 09:18

-----------------------------------------------------------------------------

                      Enter your name or University ID:

                      j_williams______________________

                Acting for: ________________________________
      *-----------------------------------------------------------------*
      | There are 4 names like J WILLIAMS.                              |
      |                                                                 | .
      | _ <-- Choose a name by entering a number from the list below.   |
      |     1. Williams, Jane H                                         |
      |     2. Williams, Jo Ellen                                       | g.
      |     3. Williams, Joann                                          |
      |     4. Williams, Marli J                                        |
      |                                f5=OK             f9=Cancel Box  |
      *-----------------------------------------------------------------*

Type OK to continue forward.
Type CANCEL BOX to cancel box.
YOUR RESPONSE:
f1=Help                         f5=OK         f7=Undo f8=Cancel

Navigation commands

The commands to navigate through a resolution box are different than for choice and trigger boxes. The reason for the difference is that the character of the interactions is somewhat different. Both choice and trigger boxes result from an explicit request from the user, while resolution boxes result from an application detecting a condition needing resolution.

The commands offered in a resolution box are OK (to continue forward with the process that was interrupted, once the conflict is resolved) or CANCEL BOX (to discard the box and return to the prior screen to change the data that caused the conflict). An OK from a resolution box causes the user's initial command (OK, PREVIOUS, SEND, or CANCEL) to be processed.

DONE and CANCEL BOX are offered instead on choice and trigger boxes, to signal that the user has finished with the box interaction and is ready to return to the main screen (DONE) or that he has changed his mind about using the box (CANCEL BOX).

[See 12A.6.2 for more on navigation commands.]

Confirmation (Yes-No) Boxes

Confirmation boxes are a special category of resolution boxes, where the resolution can be expressed as a simple yes/no choice by the user. In this case, f4=No and f5=Yes are the commands offered in the box. In keeping with the intended purpose of Yes-No boxes, you should not provide data entry fields, but use it only to present the question and the yes/no choice.

Consider XSETUP FIELDS, with which you can remove a reporting field defined for your application. Rather than simply putting a warning error code on the screen if you attempt to remove a field that is currently in use in a Personal Report, the application could provide some explanatory text in a confirmation box and ask whether the field should really be removed or not:

United States                      XSetup Field                08/09/90 09:24
                              STATES: Field FLOWER
-----------------------------------------------------------------------------
   To remove, enter 'R': r
   NAME of field      DESCRIPTION of this field
   FLOWER________     State flower__________________________________
   Enter an 'X' next to the Prism processes in which this field is available.
            X REPORTING             _ FILTERING           _ SORTING
       * --------------------------------------------------------------*
       | Warning -- This field is in use in Personal Report(s).        |
       |    Before removing the field, run the CHECK FIELDS report in  |
       |    Prism Profile to see where it is used.  Type HELP CHECK    |
       |    FIELDS for further details.                                |
       | Do you still want to remove the field?                        |
       |                  f4=No   f5=Yes                               |
       * --------------------------------------------------------------*

   Indicate all accounts, groups, or access lists that may use this field:
   PUBLIC___________________________________________________________________
   _________________________________________________________________________
   _________________________________________________________________________

Type NO to keep the field.
Type YES to remove the field.
YOUR RESPONSE:
f1=Help                         f5=OK f6=Send f7=Undo f8=Cancel

Here, an f4=No command would presumably return the user to the screen from which he came, so that the remove request could be blanked out. And f5=Yes would proceed to process the original command (OK or SEND) that the user issued.

12a.6  Standards and Guidelines for Boxes

As application developers begin to implement boxes in production applications, we hope to share examples, problems, and solutions, and come up with standards and guidelines for the use of boxes. Following the guidelines will help the Prism user community see boxes as a coherent part of the Prism interface.

The guidelines and examples in the following sections will continue to evolve as discussions about boxes continue.

If you have questions or ideas to share, contact Lynn McRae (gq.ltm) or use the SUGGEST command in Prism.

12a.6.1  How to Label Choice Fields, Trigger Fields, and Buttons

Label for choice lists

The standard way to mark a field for which choices are available is to add an asterisk to the field label. The f2=*Choices function key label also includes an asterisk; the idea is that the user will be able to make a conceptual link between the function key and the fields with asterisks.

The asterisk should be placed near the start of the input field to which it applies. When the field title is in front of the input area, replace the colon with an asterisk. This will place the asterisk close to the input area. If the field title ends with a question mark (or other punctuation mark that can't be omitted) put the asterisk after the punctuation mark.

If the input area is on the line below the field title, put the asterisk at the front of the input area:

For column headings, put the asterisk at the beginning of the first line of the heading:

If space considerations on your screen will allow, we recommend that you follow these guidelines, so that users will see consistent labels from application to application for fields where f2=*Choices works.

Buttons and trigger fields

Buttons or trigger fields that will generate a box on the screen should be labeled clearly to let the user know the purpose of the field. Buttons (rather than plain trigger fields) are the recommended signal to present when you are providing a place where the user should mark a field to cause something to happen. [See 12a.4 for a discussion of trigger fields and buttons.]

One good method is to use a sentence or phrase indicating both the action ("Type an X...") and effect ("...to add a comment") and to point to the button with an arrow. For example:

Alternatively, if the label needs to be placed to the left of the button:

This type of label might appear above a column of trigger fields or buttons:

Ideally, the instructions for a trigger field should be as close as possible to the trigger field itself.

It's preferable to let any character trigger the trigger field, rather than requiring an X, for example.

And the trigger should be blanked out when you return to the main screen after presenting the trigger box. You can do this with the command SET FIELDVAL " " in your trigger event protocol step. If you create a button, Prism itself will take care of presenting the button image before, during, and after activation.

12a.6.2  Function Keys and Navigation Commands

The earlier section illustrating the different types of boxes referred to the navigation commands used to move between the main screen and a box. [See 12A.5.1.] This section summarizes the recommended presentation of function key commands in different situations.

Command presentation is under your application's control, via options on your PERFORM PRISM commands, and you should follow the guidelines here in deciding which commands to enable. [See 12a.7 for coding details.]

f2=*Choices

Note that it is the ON EVENT CHOICE statement in a protocol that enables the f2=*Choices function key on a screen.

Choice and Trigger Events

DONE and CANCEL BOX

DONE and CANCEL BOX are the primary navigation commands for boxes presented during choice and trigger events. Include DONE and CANCEL options on your PERFORM command to enable those function keys. [See 12a.1 for a definition of "events".]

These are the commands with which the user says that he is finished with the box interaction (DONE) or that he wants to simply discard the box (CANCEL BOX). Both commands take the user back to the main screen.

OK and PREVIOUS

OK and PREVIOUS are automatically supplied in PERFORM PRISM CHOOSE lists when needed for scrolling through a long list. No option is required on your PERFORM PRISM CHOOSE command to enable OK and PREVIOUS for scrolling in this situation.

You may explicitly supply OK and PREVIOUS if needed to move between successive pages of a box; otherwise don't enable those commands. [See 12a.6.3 for more on multi-page boxes.]

SEND

SEND is never appropriate in a choice or trigger event, and Prism ignores it if included on your PERFORM command.

Resolution Boxes

OK and CANCEL BOX

OK and CANCEL BOX are the commands to navigate through a resolution box. Include OK and CANCEL options on your PERFORM command to enable those function keys.

OK is the command with which the user says that he is finished with the resolution box and wants to proceed with the command he issued earlier. CANCEL BOX signals that the user wants to return to the main screen from which that command was issued.

SEND

SEND is never appropriate in a resolution box, and Prism ignores it if included on your PERFORM PRISM command.

DONE and PREVIOUS

Don't enable the DONE command in a resolution box; it is not appropriate. You may explicitly supply PREVIOUS if needed to move between successive pages of a box; otherwise don't enable it. That is, don't enable PREVIOUS as a paging command to move back to the original screen, since CANCEL BOX is intended to serve that function.

Why different navigation commands?

Why is there a difference between resolution boxes and choice/trigger boxes in the navigation commands recommended and/or allowed? The choice and trigger boxes introduce a new navigation model into Prism, distinct from the normal screen navigation using OK and PREVIOUS. You can think of it as a "nesting model" rather than a "paging model". With a choice/trigger box, the user is "nesting" to a detour, on demand, and is then specifying when the detour is done (with DONE). In contrast, the resolution box appears not on request by the user, but on the application's decision, so the user is led forward with the normal paging command of OK, continuing the same paging model as on the main screens.

Confirmation (Yes-No) Boxes

YES and NO only

Confirmation boxes are a special case. Their purpose is to present a yes/no question in a resolution box situation. Therefore, NO and YES are the appropriate navigation commands here -- include NO and YES options on your PERFORM command and don't enable the other commands.

Text-only Boxes

Choice, trigger, and resolution boxes that are text-only (i.e. generated with PERFORM PRISM PROMPT TEXT or PERFORM PRISM SCREEN...PROTECT) only require one navigation command, in general -- DONE or OK is sufficient and CANCEL should not be enabled.

Summary of Function Key Recommendations

Here is a chart summarizing the recommendations in preceding paragraphs:

                          *PREVIOUS *OK     DONE   CANCEL  YES      NO
                          -----------------------------------------------
Choice box                   x       x     supply  supply   x       x

Choice box, text-only **     x       x     supply    x      x       x

Trigger box                  x       x     supply  supply   x       x

Trigger box, text-only       x       x     supply    x      x       x

Resolution box               x      supply   x     supply   x       x

Resolution box, text-only    x      supply   x       x      x       x

Confirmation box             x       x       x       x     supply  supply

--------------------------------------------------------------------------

   "supply" - means you should enable the command by including an option
                on your PERFORM command
   "x"      - means you should not enable the command

Notes:

*    PREVIOUS and OK are supplied automatically by Prism when needed
       for scrolling in choice lists.
     You should enable PREVIOUS if needed in a multi-page box. Enable
       OK instead of DONE on the first page of a multi-page choice
       or trigger box.  That is, use OK for paging, and DONE to
       return to the main screen after the event is finished.

**   A "text-only choice box" is not likely, but you might imagine
       a situation where the usual response to f2=*Choices is a choice
       list, but in some exceptional circumstance you need to present
       text explaining why a choice is not available this time.

CANCEL vs. CANCEL BOX

Note that a CANCEL option on a PERFORM command causes either f8=Cancel or f9=Cancel Box to be enabled, depending on whether the PERFORM is presenting data on a screen or in a box, respectively.

At the Screen Level

The PERFORM commands discussed in this chapter are useful primarily in boxes, but it is also possible to use them at a screen level (PERFORM PRISM CHOOSE is the most likely of these commands to be useful on a screen, as things stand now). At the screen level, normal navigation rules apply:

 - DONE, YES, and NO are not applicable, so are ignored.
 - SEND is not applicable on parm screens, so is ignored; you  must  enable  it  on  entry  form
 screens.
 - CANCEL is automatically supplied on parm and entry form screens.
 - OK is automatically supplied on parm screens; you must  enable  it  on  entry  form  screens.
 - You must enable PREVIOUS on parm screens and entry form screens.

Disabling or Enabling Commands During an Event

During an event proc, you may use the "PERFORM PRISM DISABLE (or ENABLE) pfkey" command to disable or enable commands (function keys) when the parent screen is shown again after the event. [See 12a.16.]

Details About Paging in Choice Lists

A PERFORM PRISM CHOOSE list in a choice box (event) is circular until the DONE command is issued. That is, OK takes you to the next part of the list even if you've filled in a choice. If you're looking at the last part of the list, OK takes you back to the beginning. DONE is what takes you back to the main screen.

A PERFORM PRISM CHOOSE list in a resolution box (in an ON COMMAND event) or at the screen level is circular until you've made a choice, since DONE should not be present in a resolution box, according to current guidelines. Once you've made a choice, OK moves you forward out of the resolution box. One implication of this is that for a CHOOSE MULTIPLE list in a resolution box, once you've made at least one choice, you can't circle back to the first part of the list again. Once you've made a choice, OK at the end takes you forward out of the resolution box.

12a.6.3  Guidelines for Use of Boxes

Boxes are an ancillary screen tool, generally relating to individual screens, and should not be used as a substitute for screen-to-screen navigation. In general, think of boxes as an optional or exceptional detour from the main processing flow, rather than a required step in a transaction. Don't nest into major portions of a transaction in boxes -- that's more appropriate for separate screens.

Boxes should provide a simple interaction directed toward a single purpose. The sequence of events within a box should not be so complicated as to bring about some of the same difficult navigation problems that complex cycles of optional screens do at the screen level -- the kinds of problems that boxes themselves were introduced to solve.

Here are some general guidelines, in no particular order:

Purposes of Boxes

Choice boxes

Choice boxes are the most straightforward of the three types. Their purpose is to present a list of choices for the user. Their primary use is to help the user fill in an entry field by presenting possible values to choose from.

A choice event (i.e., what happens in response to the f2=*Choices key) must include the presentation of a choice list. You might decide to have an intervening prompt to ask a question of a user before presenting the list, but the main point of a choice event is the list of choices.

You might also imagine a situation where some condition on the main screen causes no choices to be applicable. You could code your protocol so that the response to f2=*Choices in this case is to present text explaining the situation (e.g. because of what you entered in field XYZ, none of the choices that are normally relevant for this field are applicable). This would be a case where no choice list is presented, because of exceptional circumstances, but it still follows the "spirit" of a choice box.

Trigger boxes

You might implement a trigger box to provide a detailed display for something that's summarized on the main screen (e.g., a full course description for a course listed by title). Adding comments or doing "table maintenance" activities are also candidates for trigger boxes. Keep in mind that a general goal is to use boxes for "optional" activities, and not as a substitute for screen navigation.

Resolution boxes

Consider a case where a screen is filled in, but based on some value the user gave, you need a small extra bit of information. For example, the user indicated they want delivery by ID mail, and now you need to prompt for an ID mail address. A resolution box here is a good alternative to an extra screen for a small amount of extra input.

Or you might be able to design a screen with boxes to avoid making the user tab through many fields that are likely to be used rarely (only needed in certain situations). That is, rather than providing spaces on a screen for every possible condition, ask questions to define the conditions, then present a box for the extra input needed for that condition.

For inter-element or consistency edits, it might be preferable to use a resolution box to present an error explanation instead of standard error codes. A resolution box could present the data that needs resolution and give the user a chance to change one or the other of the values.

Confirmation boxes

Confirmation boxes are a special category of resolution boxes, where the resolution can be expressed as a simple yes/no choice by the user. In this type of box, you would offer f4=No and f5=Yes as the available "navigation" commands. The question you ask in the box should clearly state what the 2 choices are and what will happen as a result of a "No" or "Yes" response.

Confirmation boxes are most useful for a single-panel "alert"-style box. For example, you might provide a warning if the user issues a CANCEL command after a long and complex transaction (perhaps after a certain threshold that you keep track of). The confirmation box could ask whether the user really intends to cancel the transaction.

Nested Boxes and Multi-Page Boxes

Nested boxes

It is possible to generate "nested boxes". "Nested boxes" means having more than one box visible on the screen at once, as in this example of a trigger box that itself might have a choice box overlaid on top. [See 12a.5.1 for the original presentation of this example.] With nested boxes, you have to discard one box after another in order to get back to the main screen.

XSAQA Applications           Entry Form: APPLICATION           08/09/90 08:46

-----------------------------------------------------------------------------
To add a component description to TAPELOAD, mark the ADD button. To modify a
component description, mark the button next to the appropriate ID.

 Modify  Component ID                     Component Name (or Type)
  *------------------------------------------------------------------------*
 _|      Component ID: archive_________________________                    |
 _|    Component Name: Archive tape *--------------------------------------*
 _|    Component Type* __           | __ <-- Choose one from the list      |
  |                                 |        below.                        |
  | ----------------------- Componen|     1. SPIRES Component (%)          |
  | ________________________________|     2. SPIRES File Definer (%D)      |
  | ________________________________|     3. SPIRES File Definition (%F)   |
  | ________________________________|     4. SPIRES Format (%G)            |
  | ________________________________|     5. SPIRES Protocol (%P)          |
  | ________________________________|     6. SPIRES Record Definition (%R) |
  | f2=*Choices f3=Done            f| (No. 1-6 of 57)                      |
  *---------------------------------|    f3=Done   f5=OK     f9=Cancel Box |
                                    *--------------------------------------*

Type: OK to continue forward.     CANCEL BOX to cancel box.
      DONE to leave this box.
YOUR RESPONSE:
f1=Help               f4=Previous f5=OK f6=Send f7=Undo f8=Cancel

Since the first, base box may have a screen-id, it can be declared as a screen on which other events may happen. For example:

A general recommendation is that you use nested boxes only to offer f2=*Choices within a trigger or resolution box (although other permutations are technically possible). The maximum number of nested events is 8.

Multi-page boxes

Within one choice, trigger, or resolution protocol step, it is only possible to define one subarea (box) at a time. [See 12a.9.] Within that subarea, you could provide multiple "pages". For example, you might first prompt for a value and then (after the user issues an OK command) present a list of choices related to that value somehow. This would be accomplished with (at least) two PERFORM commands, but both steps should occur in the same subarea. In other words, it is undesirable to move the location of the box or change its size for the successive pages (steps) of the interaction. The only exception is a box that might shrink or expand vertically to accommodate a varying size list.

Navigation Commands Within A Multi-page Box

Follow the guidelines given earlier for navigation commands for the different types of boxes. [See 12a.6.2.] In addition, you should enable OK and PREVIOUS as paging commands within a multi-page box (that is, between the pages within the box). Don't, however, enable PREVIOUS on the first page of a box, since DONE and CANCEL BOX are the standard ways to go back to the main screen from the beginning of a box.

12a.7  How to Code Boxes

Boxes happen in response to "events" as described earlier. [See 12a.1.] The event might be the user pressing the f2=*Choices key (for a choice event/box) or entering a value in a trigger or button field (for a trigger box in a trigger or button event) or issuing a particular command (for a resolution box in an ON COMMAND event).

An event invokes a separate protocol processing step that does the work of generating the box. Events are defined in a DECLARE SCREEN section of the protocol supporting the screen. [See 12a.2.]

An event step executes between the output and input frames of PERFORM PRISM SCREEN processing. Though they are embedded in screen processing, it's appropriate to think of their logic as independent of the main screen flow. [See 12a.1.]

Only for custom control

Since an entry form installed with automatic control generally would not have a supporting protocol, and because boxes require protocol code, for all intents and purposes, boxes are not possible in automatic entry forms.

Checklist for Coding Choice Boxes

Here is a summary checklist of the steps in coding a choice box:

Checklist for Coding Trigger Boxes

Here is a summary checklist of the steps in coding a trigger box (the steps are very similar to those for choice boxes):

Checklist for Coding Resolution and Confirmation Boxes

Here is a summary checklist of the steps in coding a resolution box:

12a.8  Protocol Code to Generate Boxes

Naming the protocol step

For choice and trigger boxes, the ON EVENT... statement defines which protocol step is executed to generate the box in response to the f2=*Choices key or input into the trigger field or button. For resolution boxes, the ON COMMAND... statement names the protocol step. For example:

Your protocol step can be as short or as complex as required to support a given function. It has access to all PERFORM commands, although some, like those related to searching, would presumably make no sense in this context.

A protocol step for an event may perform many different tasks, but any interaction with the user should be via boxes, since events define a form of secondary processing within the screen. (In fact, you will get an error when your protocol is executed if in an event step you try to generate a screen image that is not contained in a subarea.)

ENDPROC alternative

Note that the ENDPROC option on PERFORM PRISM SCREEN is an alternative to the ON COMMAND statement to declare a protocol step to execute during a "command" event. However, ENDPROC is being phased out. [See 12a.2 for details about ENDPROC processing.]

Tools for generating boxes

The primary tools that Prism provides to generate boxes are:

If needed as an alternative to the pre-packaged tools listed above, you may use PERFORM PRISM SCREEN to invoke a format to present data in a box. This would require writing additional format frames, with dimensions customized to fit in your box. These frames would go in your input format (for a box on an entry form screen) or report format (for a box on a parm screen for a report) or display format (for a box on a parm screen at file-selection).

12a.9  PERFORM PRISM SET SUBAREA (and ... CLEAR SUBAREA)

PERFORM PRISM SET SUBAREA defines the size and placement of a choice, trigger, or resolution box. It establishes a rectangular area within the main data area (or any current subarea) in which future screen interactions will take place for the remainder of the current processing step, or until a ...CLEAR SUBAREA or another ...SET SUBAREA command occurs.

Subareas are automatically cleared after leaving the event. But for tidiness' sake, your protocol step could include a PERFORM PRISM CLEAR SUBAREA command before RETURN.

Syntax of PERFORM PRISM SET SUBAREA

height BY width

"Height" can be a positive integer, for a box of fixed height, or 0 for a box of variable height. "Width" is a positive integer indicating a fixed width for the box.

Variable height boxes

A variable height box is valid only for PERFORM PRISM CHOOSE, PERFORM PRISM PROMPT TEXT, and PERFORM PRISM PROMPT VALUE. By specifying variable height with PERFORM PRISM CHOOSE, Prism will use as much of the screen as is available for the list of choices; that is, a larger screen will accommodate a longer list automatically. By using variable height with PERFORM PRISM PROMPT TEXT and PERFORM PRISM PROMPT VALUE, you don't have to calculate how many lines are required to present your text or input field -- Prism will make the box tall enough automatically.

<height>x<width> is an acceptable synonym for <height> BY <width>.

AT [RELATIVE | ABSOLUTE] row, col

Specify a row and column in which data inside your box should start. In the simplest case, "row" and "col" are positive integers indicating a fixed location.

* for relative placement

For choice boxes, the row and column designations may be *, *+n, or *-n, indicating a position relative to the start of the field where the cursor is located (i.e. where the cursor is located when the f2=*Choices key is pressed).

UP, DOWN, CENTER, LEFT, RIGHT

In place of "row" you may use one of the terms UP, DOWN, or CENTER. And for "col" you may use LEFT, RIGHT, or CENTER. These designations will position the box in the available space, at the top, bottom, left, right, or center of the screen. For example, PERFORM PRISM SET SUBAREA 5x40 AT DOWN,RIGHT will place a box 5 rows tall by 40 columns wide in the lower right corner of the screen.

RELATIVE and ABSOLUTE

The term RELATIVE indicates that the coordinates are relative to the containing box when one subarea is created inside another. (RELATIVE is the default.) ABSOLUTE means that the coordinates are at fixed positions on the background screen, regardless of intervening boxes.

Syntax chart

Here is another way of looking at the syntax of the AT <location> option for PERFORM PRISM SET SUBAREA:

(UP or UPPER is a synonym for TOP, and DOWN is a synonym for BOTTOM.)

Examples

Here are some examples:

Errors in specifying box size

If your requested subarea dimensions, in combination with its placement on the parent screen (or box) would cause the box to fall off the edge of the screen in any direction, Prism will treat this as an error.

Or if you specify a subarea too narrow for the function keys needed in the box, Prism will treat this as an error. Prism does its best to abbreviate function key designations and squeeze the space between them, but there is a minimum space required for the function keys. This minimum varies, of course, depending on how many function keys are needed in the box. [See 12A.6.2 for recommended function key presentation.]

The box surrounding your subarea

Subareas are automatically surrounded by a ruled box. Your dimensions and location determine the size and the top-left corner (the logical row 1 and column 1) of the data area within the box. The ruling font box lies outside these dimensions and should be taken into account in determining where you want the box to occur. The upper and lower boundaries of the box are -1 row before and +1 row after the data. Because of a "field attribute character" which occupies a place on the screen between ruling and non-ruling data, the sides of the box are located -2 columns before and +2 columns after the data subarea. So any subarea must start on row 2 or higher, must end one row before the bottom of the screen, and may not extend into columns 1/2 nor 78/79.

12a.10  PERFORM PRISM CHOOSE

PERFORM PRISM CHOOSE provides a pre-packaged way to present a list of items to choose from. The items typically represent possible values for an entry field, and are presented in a "choice box" via the f2=*Choices key. [See 12A.5.1.]

The items on the list can be derived from an array, or a search result or stack from a subfile. The list may allow a single choice or multiple ones; the user's choice is copied back into the entry field from which the f2=*Choices key was used.

PERFORM PRISM CHOOSE includes options to provide customized header text and prompts for the list, and Prism automatically takes care of presenting multiple pages of a long list. Prism also automatically handles error-checking (e.g. to edit whether a valid choice has been made). [See 12a.6.2 for additional details about paging in choice lists.]

Enabling f2=*Choices

It is the ON EVENT CHOICE... statement in a DECLARE SCREEN section of a protocol that enables the f2=*Choices function key on a screen. [See 12a.2.] Note that the only appropriate action for your application to take when the user presses f2=*Choices (according to current guidelines) is to present a box with a list of choices for an entry field. While PERFORM PRISM CHOOSE is certainly the easiest way to create this list, you may also write your own format and use PERFORM PRISM SCREEN to present the list, if you have requirements that are not met by the general tool.

Uses other than for f2=*Choices

Although the primary use of PERFORM PRISM CHOOSE is to present a choice box (and that is the focus of this description), the command may be used anywhere you need to present a list of choices. For example, you might code a trigger or button event in which part of your interaction with the user is to present a list (in a box).

PERFORM PRISM CHOOSE may also be used at the screen level to present a list that is not in a box (subarea), as long as this is done in your mainline screen processing code and not in an event.

Zones for input fields

When a choice list is generated on the screen, Prism defines "system" zones for each of the input fields associated with the list. There will be one input field for CHOOSE SINGLE and multiple input fields for CHOOSE MULTIPLE; the input fields are trigger fields. These zones have names prefixed with "$"; you may use the SPIRES command SHOW ZONES to see the names assigned to such zones. (While the choice list is displayed on the screen, type SPIRES to exit to SPIRES temporarily, then type SHOW ZONES to see the list of currently defined zones.)

One implication of this is that if you need to, you can set up trigger events off of these Prism-defined zones:

[See 12A.2, 12A.3.]

Syntax of PERFORM PRISM CHOOSE

The required options for PERFORM PRISM CHOOSE are SINGLE|MULTIPLE, FROM, and OUTPUT.

Examples

Here are a few examples of commands. Details about the options follow below.

SINGLE or MULTIPLE

The SINGLE option generates a choice list that has only a single input field, associated with the PROMPT string (see below). The user may only choose one value from the list (by entering a number from the list).

The MULTIPLE option creates a list with input fields beside each item on the list; the user may choose multiple items by marking each choice with an X. (See the examples below, in the paragraphs describing the TEXT and PROMPT options.)

FROM, OUTPUT, and INPUT

These three options define the contents of the items in the choice list.

FROM

The FROM option describes where the items on the list come from -- an array, a search result or stack, or all records from a subfile. To use FROM RESULT, STACK, or SUBFILE, your protocol code must establish a link to a secondary file (with PERFORM PRISM LINK) and assemble a search result (for example) from which the choice list should be generated. [See 16 to read about secondary files.]

If you specify FROM SUBFILE, then Prism presents all records in the secondary file in the choice list, via FOR SUBFILE. Note that the choice list is built in memory, so it is not prudent to use FROM SUBFILE against a large subfile. A lengthy choice list (say, more than 100) is probably unwieldy for the user anyway, but building a list of, say, more than 1000 is likely to cause memory difficulties for your application.

OUTPUT

For FROM ARRAY, the OUTPUT option specifies an array name. For FROM RESULT, STACK, or SUBFILE, the OUTPUT option specifies an element name. The source named in the OUTPUT option provides the actual values to be shown in the choices list. Only one element may be named here. If you need to present multi-part items in the list, you might define a dynamic element in your protocol code and use that element name in the OUTPUT option. [See 12a.17 for an example.]

When the values for a choice list are coming from an array, Prism starts with the variable occurrence numbered 1 in the array, e.g. variablename::1 and not variablename::0.

INPUT

The INPUT option defines an element name or array name whose values should be returned by PERFORM PRISM CHOOSE and optionally placed in the entry field on the main screen after a choice has been made. That is, $PARM and/or $FIELDVAL is set from values in the INPUT source. (See discussion of $PARM and $FIELDVAL below.)

INPUT and OUTPUT sources may be the same. Currently, list items are limited to one line in your box and are truncated if they are too long.

The INPUT option may be omitted, in which case Prism will return the number or numbers chosen, instead of values.

If list has only 1 item

If it turns out that your FROM source ends up with only one item to choose from, Prism will bypass the choice box itself and just "choose" it automatically, placing a value in the entry field, unless you have coded a VERIFY option (see below).

Example

Here is sample protocol code for the first choice box illustrated in an earlier section. [See 12A.5.1.] This example illustrates many of the commands and options described so far and shows how they all fit together.

The protocol links to a secondary file; all of the records in the subfile will be presented in the choice list (...FROM SUBFILE). A dynamic element (XAPPL) is defined as the OUTPUT source for the list items, although what is mapped back to the entry field when the user chooses is the value of the APPL.ID element (INPUT=APPL.ID). The REPLACE option is described next; it specifies that the user's choice should be placed in $FIELDVAL and mapped back into the field from which f2=*Choices was pressed, replacing whatever was there before. (In this case, it is an APPL.ID value that will go into the field.)

REPLACE and BUILD

The REPLACE option instructs Prism to take the user's choice and map it back to the original field when processing the f2=*Choices command. The INPUT option defines exactly which element or array is used to provide the values. See the section on $PARM and $FIELDVAL below for examples of cases where you might want to omit the REPLACE option. [See 12a.16 for an example of another way to control mapping of choices back to the main screen.]

HORIZONTAL

For multiple-choice lists, the REPLACE option can be followed by either HORIZONTAL or VERTICAL, to describe how multiple choices should be mapped to multiple fields on the original screen. HORIZONTAL means that multiple choices are mapped to consecutive fields, starting with the initial field and tabbing right. HORIZONTAL is the default multi-value mapping if REPLACE is specified.

VERTICAL

VERTICAL means that multiple choices are mapped back to fields below the initial field (for example a column of values).

BUILD and SEPARATOR

Like HORIZONTAL and VERTICAL, the BUILD option is only applicable for multiple-choice lists. BUILD specifies that multiple choices should be concatenated into a single string, with the individual choices separated by a comma-space. You can also specify a separator other than a comma with the SEPARATOR option. This is useful when a multiple-choice box is intended to fill out a single field on the screen, or when you do not use the REPLACE option and instead wish to work with the value returned in $PARM for other purposes.

$PARM and $FIELDVAL Variables

When a user presses the f2=*Choices key for a field, the $FIELDVAL variable contains any value currently in that field. In your protocol code, you might use $FIELDVAL to alter or control the list that is presented to the user. [See 12a.16 for an example.]

After PERFORM PRISM CHOOSE is done, the user's choice is placed into $PARM. In addition, if you have included the REPLACE option on PERFORM PRISM CHOOSE, then the user's choice is also placed into $FIELDVAL. When the user leaves the box and returns to the main screen, $FIELDVAL is placed into the input field from which the CHOICES command was issued. In other words, $FIELDVAL is always placed into the original field on the main screen. But the user's choice is only placed into $FIELDVAL if the REPLACE option is used on PERFORM PRISM CHOOSE.

A field's value will be replaced if $FIELDVAL has changed even if the user cancels out of a box (i.e. if your code issued a SET FIELDVAL command). This allows your application to always reset a field by resetting $FIELDVAL first in the event step.

Your application might, in some circumstances, need to omit the REPLACE option so that after the user's DONE or OK command is issued, your code can manipulate $PARM in some way and then SET FIELDVAL explicitly.

Cursor positioning

You may imbed cursor positioning control sequences in your SET FIELDVAL command, in order to fill in multiple fields or otherwise control where the cursor is positioned after the value is placed into an input field on the main screen. [See 12A.16 for examples.]

Using $PARM without REPLACE option

Another example of how you might use $PARM as set by PERFORM PRISM CHOOSE is if your choice list simply sets some parm that will be used in a subsequent process. For example, a choice event might first present a list asking the user whether he wants to see a "short menu" or "long menu". You'd use PERFORM PRISM CHOOSE without REPLACE and then capture the $PARM value to use in constructing the next list.

TEXT and PROMPT

The TEXT option provides text to go at the top of the choice box. The PROMPT option supplies a prompt at the top of the list. The default prompt is "Choose one from the list below." or "Choose one or more from the list below." (for CHOOSE SINGLE and CHOOSE MULTIPLE, respectively).

Examples

These very simple examples illustrate how the TEXT and PROMPT values are used inside choice boxes.

In the TEXT option, you may use double slashes as a "line-feed" indicator. This simple formatting tool lets you force a line break or add blank lines. For example:

This command would produce a choice list with text formatted like this:

ID = screen-id

You may supply a screen identifier, for use in the key of a context help for the screen image containing your choice list, or for use in a DECLARE SCREEN statement (to declare an event for the choice list screen). This is analogous to the screen-id for regular input screens (e.g. in PERFORM PRISM SCREEN commands).

TITLE = 'screen title'

If you are using PERFORM PRISM CHOOSE at the screen level (as opposed to using it in an event and presenting the choices in a box) then you should supply a screen title. This title appears in the second line of the screen (in the status area). The TITLE option is not required, but you are strongly encouraged to use it when coding a choice list at the screen level. When PERFORM PRISM CHOOSE is coded in an event, the TITLE option has no effect.

VERIFY [= 'text']

Normally when the choice list would only contain one item, Prism will bypass the screen prompt and assign the value to $PARM and/or $FIELDVAL directly. The VERIFY option will cause even a single item to be verified as the desired choice. Verification is via a YES/NO box; for example:

When optional "text" is supplied with the VERIFY option, it will replace the default text of "Only one choice found:", e.g.:

For the "text" of the VERIFY option, you may use double slashes as a "line-feed" indicator, as described above for the TEXT option.

DEFAULT = 'n,n,...'

When the DEFAULT option is used, the "nth" entry or entries will be pre-selected in the CHOOSE list. Specify one number for CHOOSE SINGLE (DEFAULT = n). Multiple numbers might be used for CHOOSE MULTIPLE (DEFAULT = 'n,n,...').

For CHOOSE SINGLE, the specified number will be prompted in the entry field and the corresponding choice will be highlighted. For CHOOSE MULTIPLE, each specified entry will be marked with an X and highlighted.

REQUIRED

The REQUIRED option specifies that the user is required to make a choice from the list before proceeding (or must otherwise issue the CANCEL BOX command). If REQUIRED is coded and the user issues the DONE or OK command without making a choice, an error message is given.

Enabling Commands: DONE, OK, CANCEL, etc. Options

The DONE, OK, PREVIOUS, SEND, CANCEL, YES, and NO options enable the named commands for the box (or screen) where PERFORM PRISM CHOOSE is used.

The recommended command presentation for boxes was described in an earlier section. [See 12a.6.2.]

Most typically, when PERFORM PRISM CHOOSE is used in a choice box (event), DONE and CANCEL BOX should be enabled. When a choice list is presented in the context of an ON COMMAND event, OK and CANCEL BOX should be enabled.

OK and PREVIOUS are supplied automatically by Prism when needed for paging through a list that doesn't fit on one page. Otherwise, function keys are enabled automatically by Prism only if your PERFORM PRISM CHOOSE command does not specify navigation commands.

OPT... = 'text'

You may control the wording of the Guided Mode options at the bottom of the screen with the OPTOK, OPTPREV, etc. options on PERFORM PRISM CHOOSE. These work the same as on PERFORM PRISM SCREEN. [See 12.1.3.]

TIMELIMIT=n

This option allows a timeout interval to be associated with the screen read. "n" is an integer, from 1 to 6000, indicating seconds. This option would cause a session that has been idle for "n" seconds to invoke a timeout, cancelling the current process (input, file selection, etc.).

12a.11  PERFORM PRISM PROMPT VALUE

PERFORM PRISM PROMPT VALUE provides a pre-packaged way to build a simple screen to prompt for a single value. For all practical purposes, a PROMPT VALUE input screen is useful only within a box (although this is not a technical restriction). [See 12a.17.]

The value that the user enters in the input field on a PERFORM PRISM PROMPT VALUE screen is returned in the $PARM variable.

Syntax of PERFORM PRISM PROMPT VALUE

The required options for PERFORM PRISM PROMPT VALUE are {OPTIONAL | REQUIRED}, LENGTH, and PROMPT.

OPTIONAL or REQUIRED

The term OPTIONAL or REQUIRED determines whether the input field is optional or required.

LENGTH

The LENGTH option determines how long the input field is. If the LENGTH exceeds the width of the subarea (box) in which the input field appears, Prism will create a multi-line input area. The input area will grow to the length specified, up to the box's height. That is, if the length you specify won't fit in the size box you specified, Prism will simply truncate the input field, filling up the box. If the height of the box is coded "0" (e.g. PERFORM PRISM SET SUBAREA 0x50) then the box will grow to the bottom of the screen in order to accommodate the length specified for the input field in your PERFORM PRISM PROMPT VALUE command.

In addition, the input field will be padded out so that the last line of a multi-line input area extends all the way to the right hand side of the box, even if that makes the input area exceed your specified LENGTH.

DEFAULT

You may prompt a default value in the input field with the DEFAULT option.

TEXT and PROMPT

TEXT provides text to go at the top of the box. The PROMPT option supplies a prompt immediately above the input field. A blank line is supplied between the TEXT and PROMPT text.

Prism will put the PROMPT and the input field on the same line if they fit.

Here is a simple illustration of the screen layout for PERFORM PRISM PROMPT VALUE:

In the TEXT option, you may use double slashes as a "line-feed" indicator. This simple formatting tool lets you force a line break or add blank lines. For example:

ID = screen-id

You may supply a screen identifier, for use in the key of a context help for the PROMPT VALUE screen image, or for use in a DECLARE SCREEN statement (to declare an event for the PROMPT VALUE screen). This is analogous to the screen-id for regular input screens (e.g. in PERFORM PRISM SCREEN commands).

TITLE = 'screen title'

If you are using PERFORM PRISM PROMPT VALUE at the screen level (as opposed to using it in an event and prompting for a value in a box) then you should supply a screen title. This title appears in the second line of the screen (in the status area). The TITLE option is not required, but you are strongly encouraged to use it when coding this command at the screen level. When PERFORM PRISM PROMPT VALUE is coded in an event, the TITLE option has no effect.

Enabling Commands: DONE, OK, CANCEL, etc. Options

The DONE, OK, PREVIOUS, SEND, CANCEL, YES, and NO options enable the named commands for the box (or screen) where PERFORM PRISM PROMPT VALUE is used.

The recommended command presentation for boxes was described in an earlier section. [See 12a.6.2.]

OPT... = 'text'

You may control the wording of the Guided Mode options at the bottom of the screen with the OPTOK, OPTPREV, etc. options on PERFORM PRISM CHOOSE. These work the same as on PERFORM PRISM SCREEN. [See 12.1.3.]

TIMELIMIT=n

This option allows a timeout interval to be associated with the screen read. "n" is an integer, from 1 to 6000, indicating seconds. This option would cause a session that has been idle for "n" seconds to invoke a timeout, cancelling the current process (input, file selection, etc.).

12a.12  PERFORM PRISM PROMPT TEXT

PERFORM PRISM PROMPT TEXT provides a pre-packaged way to present a simple text message to the user. For all practical purposes, a PROMPT TEXT input screen is useful only within a box (although this is not a technical restriction). [See 12a.17.]

Syntax of PERFORM PRISM PROMPT TEXT

The 'text' to be prompted may be up to 480 characters. The text wraps automatically within the box in which it is presented. You may use double slashes as a "line-feed" indicator. This simple formatting tool lets you force a line break or add blank lines. For example:

You may supply a screen identifier with the ID option, for use in the key of a context help for the PROMPT TEXT screen image, or for use in a DECLARE SCREEN statement (to declare an event for the PROMPT TEXT screen). This is analogous to the screen-id for regular input screens (e.g. in PERFORM PRISM SCREEN commands).

TITLE option

If you are using PERFORM PRISM PROMPT TEXT at the screen level (as opposed to using it in an event and presenting the TEXT in a box) then you should supply a screen title. This title appears in the second line of the screen (in the status area). The TITLE option is not required, but you are strongly encouraged to use it when coding this command at the screen level. When PERFORM PRISM PROMPT TEXT is coded in an event, the TITLE option has no effect.

Enabling commands

The DONE, OK, PREVIOUS, SEND, CANCEL, YES, and NO options enable the named commands for the box (or screen) where PERFORM PRISM PROMPT TEXT is used.

The recommended command presentation for boxes was described in an earlier section. [See 12a.6.2.]

The OPT... and TIMELIMIT options (which are all optional) work as described for PERFORM PRISM SCREEN. [See 12.1.3.]

12a.13  PERFORM PRISM SET ERROR

The PERFORM PRISM SET ERROR command is used during event processing to do error code processing parallel to that available in the input frame of a screen. If an event detects an error, it can use PERFORM PRISM SET ERROR to update the screen with an error code much like the combination of SET UCODE and SET ERROR S in the format.

The syntax is:

The maximum number of PERFORM PRISM SET ERROR commands allowed in one event step is 32.

This PERFORM will set status REPROMPT or WARN appropriately, though the protocol can later override this, say, to change REPROMPT to REPEAT, or to STOP if necessary. Errors should be processed at the end of the event to guarantee the desired STATUS values will be returned to Prism; otherwise the application must take care to SET STATUS explicitly before returning.

As with formats ERROR/ESTART processing, the first error indicated will establish the cursor position for reprompt, and the spaces occupied by the error codes will be reset to blank after each screen prompting in case other errors case a REPROMPT after these errors are fixed.

12a.14  PERFORM PRISM COPY

The PERFORM PRISM COPY command lets you read values from the screen, or place values on the screen, without the need for formats processing. This is a useful tool for simple reading and updating of screens by means of procedural code, such as in events (choice or trigger events, or ON COMMAND events).

By using PERFORM PRISM COPY, you can avoid having to code complex logic in a screen's input and output frames for different behavior depending on whether the image is being generated or read after, say, a trigger instead of an OK. For instance, an entry screen might show both the current code in an input field, with the code's expanded value displayed next to it. If f2=*Choices is used to change to a new code, the application could use PERFORM PRISM COPY VARIABLE...TO ZONE... to keep the screen in sync with the changed code.

The syntax is:

For example:

Zones are defined in your input format, using the $ZONEDEF function. [See 12a.4.]

DISPLAY option

The DISPLAY option can be used to change the display attributes of the "destination" zone as you copy a value into it. If you specify any display attribute, you must specify a complete "set" for the zone in question. That is, the attributes you specify in PERFORM PRISM COPY are not "additive" to the attributes already in effect for the zone -- they completely replace the existing attributes.

For a complete list of possible display attributes, EXPLAIN $SETAREA or see 4.5 in "SPIRES Device Services". The most common display attribute designations are:

 colors:
 RED, BLUE, YELLOW, GREEN, CYAN, WHITE, PINK

 emphasis:
 HIDE, REVERSE, BRIGHT, BLINKING

 pre-defined combinations:
 REQUIRED, OPTIONAL, ERROR, WARNING, TITLE, TEXT, DATA

 other:
 PROTECT, UNPROTECT, UNDERLINE

Multiple display attributes may be specified, for example:

Note that you can, in effect, simply change display attributes (without changing any values on the screen) by copying a zone over itself:

Where copying is done

Note that PERFORM PRISM COPY applies to the main screen image being processed, even if the command happens in an event proc that is also generating a box on top of the background screen image. This means, in effect, that when you are coding a screen with a box on top, you can't use PERFORM PRISM COPY to copy data to or from the box -- it is a tool to manage the background screen. If you are coding nested boxes (a box generated on top of a box), then PERFORM PRISM COPY applies to the background box.

Alternative to PERFORM PRISM COPY

The next section describes how to use Device Services coding techniques (the $GETAREA, $SETAREA, and $PUTAREA functions) as an alternative to PERFORM PRISM COPY. [See 12a.14.1.]

$SCRNAREA

PERFORM PRISM COPY addresses the area named in the $SCRNAREA variable. $SCRNAREA is a SPIRES variable that is managed by Prism, containing the name of the area that is currently active.

$SCRNAREA is null when an application runs offline (e.g. when a Prism task executes).

12a.14.1  Using $GETAREA and $PUTAREA Instead of PERFORM PRISM COPY

In some situations, if PERFORM PRISM COPY and zones do not meet your needs, you might need to use $GETAREA and $PUTAREA functions to read and write values on Prism screens directly. (Please contact the Prism consultants to discuss ideas for enhancing PERFORM PRISM COPY so that it can be more useful. The intent is to provide adequate functionality in the PERFORM so that you can avoid Device Services coding.)

$SCRNAREA and $AREANAME

$GETAREA, $PUTAREA, and $SETAREA are SPIRES Device Services functions that refer to areas. For Prism applications code, always use $SCRNAREA or $AREANAME as the area name. The value of $SCRNAREA is managed by Prism and contains the name of the area that is currently active; it is available in formats or protocols. $AREANAME is a SPIRES variable set for formats whenever a frame is executed in a device services area. [See 12a.3 for a picture illustrating $SCRNAREA/$AREANAME.]

Reading from a Prism Screen

$GETAREA lets you read a value from a particular position on a Prism screen. The syntax is:

The "row,column,length" identifies the location and length of the information you wish to read. For example:

will read a 3-character value from the data portion of the screen starting on row 5 at column 20.

EXPLAIN $GETAREA if you need further details about this function.

Writing to a Prism Screen

Writing to a Prism screen is more complicated; it involves the $PUTAREA, $SETAREA, and $GETAREA functions. Below is an example; refer to the SPIRES Device Services manual for details.

First, you would probably assign the value that you want to write to the screen to a variable. In this example, assume the value is in #CodeName.

Here is the entire example, with explanations of the individual statements in the paragraphs following:

$PUTAREA to write data

The $PUTAREA function writes the data value to the area. The syntax is:

Note that you must "pad" the field into which you are writing data with blanks, in order for screen attributes to be assigned properly.

In this sample statement, a field 30 characters long, at row 4 and column 45, is being filled in with the #CodeName value, padded with blanks (or more precisely, padded with the $TermPad character).

What is a "field"?

Note that "field" here means a Device Services field, and not a data entry field in the sense of input areas on a Prism entry screen. In Device Services, a "field" is a consecutive set of characters, all with identical characteristics (display attributes). So a Prism entry screen has input "fields" (the places where users type data) next to protected "fields" (text labels for the input areas, or the blank areas in between input areas).

$SETAREA for display attributes

Finally, use $SETAREA to set the appropriate display attributes for the field into which you are writing data. The syntax is:

The "fieldnumber" refers to the consecutive numbers that SPIRES assigns to each Device Services field in the area. You can use $GETAREA, with the ALOC option, to determine the appropriate field number:

It's important to look up the field number after you write data to the area with $PUTAREA, in case the writing operation creates a new "field".

DATA is a term representing a combination of PROTECTED, WHITE, BRIGHT display attributes. See 6.1.0 in SPIRES Device Services for a list of possible terms to use with $SETAREA (or EXPLAIN ATTRIBUTES).

12a.15  PERFORM PRISM RESET UNDO

The PERFORM PRISM RESET UNDO command is used during event processing to control the scope of the UNDO command. It makes the current CRT image the one that will be restored if the user issues the UNDO command.

This command is useful in situations where your protocol event step has done work that cannot be "un-done" simply by refreshing the screen image to its state before the event started.

The default is that the scope of UNDO does not change during an event, and you are encouraged not to reset UNDO unless necessary. That is, if the work that is done in an event is fully reflected on the parent screen and can be reversed, it is best not to alter the scope of UNDO -- to let the user revert to the original screen image if needed.

12a.16  PERFORM PRISM DISABLE (or ENABLE) pfkey

"PERFORM PRISM DISABLE (or ENABLE) pfkey" lets you disable or enable commands (and the corresponding function keys) on a parent screen during event processing. For example, you might first present a screen with both OK and SEND enabled. During an event proc (e.g. in a trigger event, or after presenting a choice box), you might determine that when the parent (base) screen is shown again, only SEND should be enabled.

Syntax

The 'command' clauses are protocol commands to be executed if or when the end-user issues the command, just as with PERFORM PRISM SCREEN. The OPT... options control wording of the guided mode options at the bottom of the screen. [See 12.1.3 for detailed explanations of these options.]

12a.17  Tips and Tricks for Boxes and Events

This section contains miscellaneous coding tips:

Example 1: One Choice = Multiple Fields Filled In

You can cause a choice of value for one field to map to several fields on the main entry screen. The effect for the user is that several fields get filled in automatically as a result of picking a value for one field.

The mechanism to do this is to imbed "tab symbols" into values for a field, as illustrated below. Currently, these tab symbols are available:

Say that the main entry screen has City and State fields:


 City* __________________________    State: __
  :

When the user presses the f2=*Choices key for the City field, he sees:

After making a choice, the main screen looks like this:


 City* Charlottesville___________    State: VA
  :

To accomplish this, you could define an array with values like this:

Then, your protocol code would follow this pattern:

Example 2: Controlling Cursor Position After Events

You can SET PARM, either in a protocol command or in a formats Uproc, to control the position of the cursor. (You don't have to be working with events or boxes to use this technique.)

If you SET FIELDVAL in a choice or trigger/button event, you can imbed cursor positioning control sequences in the value (the same codes listed in the first part of this section):

This example would place "San Francisco" in the first input field (the first field in the zone from which the event happened), tab to the next field and place "CA", then back tab (back to the "city" field).

Example 3: Use a Dynamic Element for Items in a Choice List

The OUTPUT option on PERFORM PRISM CHOOSE can only name a single element from a subfile with which to construct the items in a choice list. But you can define a dynamic element that concatenates values from several elements and then use that dynamic element as the source for your list.

This example was shown earlier, but is repeated here as a coding example. [See 12A.10.]

In this code, the dynamic element XAPPL concatenates values from two subfile elements. XAPPL values are shown in the choice box (OUTPUT=XAPPL).

Note that each item in a list is only allotted one line, in the current implementation. If OUTPUT values are longer, they are truncated.

Example 4: Using $FIELDVAL to Determine Items in a Choice Box

Here's a screen where you ask the user to enter a last name before using f2=*Choices:


 Enter an Advisor ID.  Or, if you only know a last name, enter
 the name and press f2=*Choices.
 Advisor* ____________________________________
   :

Here's how the protocol code for this choice box might use the value entered in that advisor field.

Example 5: Using Boxes PERFORM Commands Without Subareas

Prism's tools for packaging the contents of a box -- PERFORM PRISM CHOOSE, PERFORM PRISM PROMPT TEXT, and PERFORM PRISM PROMPT VALUE -- have been described in this chapter in terms of using them with boxes. There is no technical restriction to prevent you from using these commands at a screen level instead of within a subarea, although practically speaking, PERFORM PRISM CHOOSE is really the only one of these commands fully-developed enough to make sense at a screen level.

Prism does edit to ensure that within an event, any command to generate a screen image (PERFORM PRISM SCREEN, CHOOSE, PROMPT TEXT, PROMPT VALUE) is used within a subarea (box). An exception is made for PERFORM PRISM SCREEN READ, which may be used in an event at the screen level. Outside of an event, these commands can be used at the screen level, without a defined subarea.

Parm screens using choice lists

You might, for example, code a protocol to provide a parm screen whose contents are generated by PERFORM PRISM CHOOSE rather than a format. (You'd omit the PERFORM PRISM SET SUBAREA command in this case.)

When used outside of a subarea, the data generated by PERFORM PRISM PROMPT TEXT and PERFORM PRISM PROMPT VALUE are presented up at the top of the screen, using the full screen width. The only formatting control that you have for the text being prompted is the use of double slashes to signal line breaks. [See 12a.11, 12a.12.]

Use as development tools

But you might find it helpful as a development tool to use PROMPT TEXT or PROMPT VALUE at a screen level as a placeholder for a parm screen, as you're coding prototypes for new parts of your application.

13  Protocol Steps for Searching and Other Special Search Features

Most searches in Prism are handled automatically, without any intervention by your application. When an end-user types a search (e.g., FIND + search type + value), Prism passes the search request on to SPIRES. (In your profile, you have listed the SPIRES search term that corresponds to each Prism index.) SPIRES performs the search and passes the search result back to Prism. Your own code does not have to issue a FIND or equivalent command to support these standard searches.

Special features for searching

For more specialized needs, Prism offers the following capabilities to more closely control searching processes in your application:

 - You may add protocol processing steps to be executed after the user has supplied  a  search
 value  for  an  index  but  before the search has been done in SPIRES.  (For value-supplied
 indexes, the protocol step would execute after the index is chosen.)  These protocol  steps
 are  associated with a particular Prism index, and are sometimes referred to as "index
 exits".
 - "Pre-search" and "post-search"  protocol  steps  may  be  supplied,  to
 execute  either  before or after a search has completed in SPIRES. These steps apply to all
 indexes.  You may define separate protocol steps for a zero result or a result greater than
 zero.
 - You may add protocol steps to do "hidden" searches on behalf  of  the  user.  For
 example,  you  might want to do a search automatically when your file is first selected, or
 when a particular report or entry form is chosen.  In this case, the user would not have to
 issue a FIND command, but would have a pre-assembled search result to work with.
 - You may disable searching completely when a particular form or report is chosen.
 - And finally, there are three special types of Prism indexes:
 - Value-supplied: The user does not need to supply a search value.
 - Stand-alone: The index may not be combined with other indexes.
 - Qualifying: May only be used in combination with another index.

Some of these special features are implemented by simply answering questions in your profile. Others require you to write protocol code and install protocol steps in your profile.

PERFORM PRISM Commands

There are several PERFORM PRISM commands that are of use in search-related protocol steps; these are explained in this chapter:

 - PERFORM PRISM SET SEARCH -- lets you reset indexes or search values before  the  search  is
 passed to SPIRES for execution.  This command is of use for index exits (and only for index
 exits).  Reminder: an index exit is a protocol step associated with a specific Prism index,
 to execute after a search command has been issued in Prism but before the search is done in
 SPIRES.
 - PERFORM PRISM ASSIGN SEARCH -- assigns a stack or result gathered behind the scenes as  the
 end-user's  visible  search  result.  This command is useful in post-search protocol steps,
 where you need to modify a completed search, or in other kinds of protocol steps where  you
 want  to  establish  a search result (that is, steps executed when your file is selected or
 when a report or entry form is chosen). It may help to think of  this  as  an  "ASSIGN
 RESULT"  command,  since  it  is used to create a search result on behalf of the user.
 - PERFORM PRISM SEARCH -- asks Prism to perform an index search of your subfile. This command
 is virtually obsolete, and should not be used.

Uses for Searching Protocol Steps

Examples

Here are a few examples of how "search steps" might be used.

13.1  How to Create a Hidden Search

A "hidden" search lets you pre-assemble a search result automatically on behalf of the user, either when he first selects your file, or when he chooses a report or entry form. (You could have a different hidden search at each of these points.)

Steps

To install a hidden search:

Which protocol?

Here is a reference chart to figure out where to put the protocol Proc:

  for a hidden search ...    proc goes in ...     install with ...
  -----------------------    ------------------   ------------------
  at file selection          FILE                 XSETUP PROFILE

  for a report               REPORT/report-name   XSETUP REPORT

  for an entry form          FORM/form-name       XSETUP FORM

Example

In this type of protocol step, you normally issue SPIRES commands to gather the search result, and then include a PERFORM PRISM ASSIGN SEARCH command to post the search result in Prism for the user. Here is a very simple example:

PERFORM PRISM ASSIGN SEARCH is described in more detail in a later section. [See 13.2.]

XSETUP PROFILE

This example is for a hidden search at file selection, so it would be installed with XSETUP PROFILE. Here are the relevant questions:

 Orders                       XSetup Profile                02/08/92 12:03
                          ORDERS: Profile, page 3
 -------------------------------------------------------------------------

    Enter 'Yes' to see screens to add, modify, or delete processing steps.
     - when the subfile is selected or cleared: yes_
     - when search is completed: No_
    Enter 'Yes' if the protocol steps for this file are compiled: No_
 Orders                       XSetup Profile                02/08/92 12:03
                  ORDERS: Select/Clear Steps, File Select
 -------------------------------------------------------------------------

 Please identify processing steps that Prism should execute.  For TYPE,
 enter "S" for a screen step, "P" for a protocol step.  Title is required
 for SCREEN steps since that title is used to label the screen.

 Processing steps for when file is selected:

 STEP#    STEP ID           TYPE   TITLE/COMMENT              Note: To
     1    first.search____    p    hidden search_____________  remove a
     2    ________________    _    __________________________  processing
     3    ________________    _    __________________________  step,
                                                               delete the
 Processing step for when file is cleared:                     value under
                                                               STEP ID.
 STEP#    STEP_ID           TYPE   TITLE/COMMENT
 CLEAR    ________________    P    _______________________________

Disabling the FIND Command for Reports or Forms

Turning off searching

You may want the result retrieved by a hidden search at report selection or form selection to be the only search result your end-users can apply to that form or report. In that case, you may disable searching (i.e., turn off the FIND command and related commands) when you install the form or report. To do this for an entry form, in XSETUP FORMS answer 'No' to the following question:

(There is a similar question in XSETUP REPORTS.)

It is not possible to turn off searching at file-selection, so an end-user will always be able to modify or replace the hidden search you provide then.

13.2  Protocol Steps for an Index: Coding Techniques

This section discusses protocol steps that are associated with a particular index -- how they are installed in your profile, variables and PERFORM PRISM commands that you will likely need to use, and how control passes between Prism and your protocol step.

Index exits

These protocol steps are sometimes referred to as "index exits" since they're associated with a particular index. Index exits typically transform a user's search value and pass the new search statement back to Prism for processing. The function of the PERFORM PRISM SET SEARCH command is to pass the search statement from your protocol back to Prism.

Where the protocol code is installed

Protocol steps associated with a particular Prism index are

Here are the relevant questions:

 Orders                        XSetup Index                 02/08/92 12:22
                              ORDERS: Index
 -------------------------------------------------------------------------
    Enter the following information as it should appear on the FIND menu:
    NAME        DESCRIPTION for this index           Sample Search Value
    ________    _________________________________    _____________________
       :
       :
    Enter 'Yes' to declare ... special features for this index: yes_
 Orders                        XSetup Index                 02/08/92 12:22
                          ORDERS: Index STATUS
 -------------------------------------------------------------------------
   1  <-- Indicate how this index is used by choosing one category
       1. Regular search type
       2. Stand-alone search type
       3. Qualifying search type

    If this index has a processing step, enter its name: _________________

Variables for Accessing the User's Search Value

$SRCHTYPE and $SRCHVAL

The search type (index) currently being processed is stored in the $SRCHTYPE variable. The user's search value for that index is in $SRCHVAL.

$LASTCMD

The $LASTCMD variable contains the command immediately applicable to the search value being processed (i.e., FIND, AND, NOT, OR).

Example: A Template for ALSO Processing

Here is an example of a common use for index exits. Assume the Prism application has a DATE index that is installed as a qualifying index. There is no corresponding SPIRES index, but a protocol step following the pattern below is installed for the DATE index in Prism. In the DATE index exit, ALSO processing is done against the current search result.

This index exit uses stored result techniques to convert the modified search into an object that can be referenced with the SET SEARCH command.

 ++DATE.SEARCH
   ; --------------------------------------------------------------------
   ; Index for date qualification.  There isn't a SPIRES index available,
   ; so we use ALSO processing.  The index is designated for
   ; qualification-only in the profile, so this exit will only be
   ; called for AND and AND NOTs.
   ; -------------------------------------------------------------------

  /also date.written $srchval
   if $no : - some recovery, using SET STATUS STOP...

   if $SRCHSTAT = 4 : let newSearch = '@ZRESULT.RSTATUS'
   else if $ZRESULT : let newSearch = '@ZRESULT.RSTATUS'
   else begin
      let counter = counter + 1
     /store TEMP RESULT.DATE.#counter replace
      let newSearch = '@TRESULT.DATE.' || #counter
      backup ; restore the result we started with
   endb

  /perform prism set search #newSearch

   return

When Your Protocol Step Will Be Invoked

The protocol step for an index is always invoked after the end-user has typed in the search value. If the end-user is prompted for a search value and simply presses the Return key to bypass the prompt, your protocol step for that search type will be bypassed.

The protocol step is invoked once for each search value being processed. For example, if the user types FIND STATUS OLD OR NEW and you have a search step for the STATUS index, the protocol step will happen first for $SRCHTYPE STATUS and $SRCHVAL OLD and then again for $SRCHTYPE STATUS and SRCHVAL NEW. This lets your protocol step work on each search value independently.

Timing

These diagrams illustrate how control passes between your protocol and SPIRES/Prism.

 User                            SPIRES search               Prism presents
 types ----------------------->- is executed ------------>-- search result
 simple                |   /|\                     | /|\
 search, e.g.          |    |                      |  |
 FIND STATUS OLD       |    |                      |  |
                       |    |                      |  |
                      \|/   |                     \|/ |
              protocol step for                 post-search
              STATUS index                      step
              ($SRCHTYPE = STATUS)
              ($SRCHVAL = OLD)
              ($LASTCMD = FIND)
 User                                      SPIRES search      Prism presents
 types ----------------------->----------- is executed --->-- search result
 compound              |   /|\    |  /|\                  |
 search, e.g.          |    |     |   |                   |
 FIND STATUS OLD       |    |     |   |                   |
 AND AUTHOR JONES      |    |     |   |                 (post-search
                      \|/   |    \|/  |                  step)
            protocol step for     protocol step for
            STATUS index          AUTHOR index
         ($SRCHTYPE = STATUS)     ($SRCHTYPE = AUTHOR)
         ($SRCHVAL = OLD)         ($SRCHVAL = JONES)
         ($LASTCMD = FIND)        ($LASTCMD = AND)
 User                                      SPIRES search      Prism presents
 types ----------------------->----------- is executed --->-- search result
 compound              |   /|\    |  /|\                  |
 search, e.g.          |    |     |   |                   |
 FIND STATUS OLD       |    |     |   |                   |
 OR ARCHIVED           |    |     |   |                 (post-search
                      \|/   |    \|/  |                  step)
            protocol step for     protocol step for
            STATUS index          STATUS index (2nd time)
         ($SRCHTYPE = STATUS)     ($SRCHTYPE = STATUS)
         ($SRCHVAL = OLD)         ($SRCHVAL = ARCHIVED)
         ($LASTCMD = FIND)        ($LASTCMD = OR)

13.2.1  Search Processing Details

There are several ways in which Prism's searching environment differs from that of SPIRES:

In addition to those searching interface features, there are some differences in how Prism interprets searches or manipulates them before passing the search commands on to SPIRES. (Remember that the SET STRACE command lets you see how a search in your application is being sent to SPIRES.) [See 7.4.2.]

Prism sometimes adds an = sign to ensure that a string is treated as a search value and not an index. One reason for this this to avoid situations where a SPIRES index exists but not a Prism index, and there's a match between a search value and the SPIRES index name. Example:

 find name smith or jones

    passed to SPIRES as:  find name smith or = jones

Prism adds parentheses to group together multiple search values for an index in situations like this:

 find dept classics and name smith or jones

    passed to SPIRES as:  find dept classics and (name smith or = jones)

In SPIRES, the logical operators would be interpreted left to right, producing a different result than the Prism form of the search.

Phrase processing

When you install a Prism index, one of your options is:

 Enter 'Yes' to treat search values as phrases: No_

If you answer "yes" Prism will interpret a string of words after an index name as one search value. The string will be enclosed in quotes when the search is passed to SPIRES. For example:

 find status a or b

    passed to SPIRES as:  find status "a or b"
      (if "phrase processing" is enabled)

 find title war and peace

    passed to SPIRES as   find title "war and peace"
      (if "phrase processing" is enabled)

There are two situations where you might want this interpretation of search values. One is where an index is a text-oriented "phrase" index and search values might include words AND, OR, and NOT that should be treated as part of the search value rather than as a logical operator (as in the TITLE example above).

Another reason to use "phrase processing" is to control how a protocol step for the index is invoked when a search value includes logical operators. If the search value is treated as a phrase and placed in quotes by Prism, your protocol step will be invoked only once. If the search value is not quoted and a logical operator is present, the protocol step would be invoked once for each search value. For example:

 find status "a or b"           (phrase processing enabled)

   invokes your protocol step once, with $SrchVal of "a or b"

 find status a or = b           (no phrase processing)

   invokes your protocol step twice, first with $SrchVal of "a"
   and then with $SrchVal of "b" and $LastCmd of "or"

13.2.2  PERFORM PRISM ASSIGN SEARCH

The PERFORM PRISM ASSIGN SEARCH command notifies Prism that the current RESULT or STACK should be treated as the end-user's search result. The result or stack can be obtained through non-index processing (e.g., Global FOR or the ALSO command) or by a FIND command.

If used in a report exit, this command only affects the search population for DISPLAY REPORT or a PRINT of the report, not the population for DISPLAY.

Syntax

The syntax is:

Examples

Here is a simple example -- for a value-supplied search type -- where Global FOR is used to retrieve all records for the current year. Then the assembled stack is assigned as the end-user's search result. If the search type is called THIS.YEAR, the status line will read "Find THIS.YEAR" when the result is posted.

In this example -- for a hidden search when a report is selected -- a standard FIND command is used and the result is assigned as the Prism result. The status line will have the label "Find Pending orders".

Limitations on Stack-Based Searching

Under current SPIRES restrictions, if the search result is from a stack, the index must be installed to stand alone -- it cannot be used in combination with other indexes. [See 13.4.1 for more about stand-alone search types.] To get around this limitation, after creating a stack, use the GENERATE RESULT command in your protocol step and then PERFORM PRISM ASSIGN SEARCH FROM RESULT.

The one exception to the stand-alone rule is a stack created out of a search result by the SEQUENCE command. The SEQUENCE stack is combinable with other search types because it is backed up by a "real" search result, whereas most stacks in SPIRES consist of key values only. However, the effect of sequencing would be lost.

Don't use with PERFORM PRISM SEARCH

Warning: do not mix PERFORM PRISM SEARCH and PERFORM PRISM ASSIGN SEARCH commands within protocol processing for a single search type. Since both of these commands tell Prism to post a particular search result for the user, use one or the other. In fact, PERFORM PRISM SEARCH is virtually obsolete and any use of the command at all is discouraged.

13.2.3  PERFORM PRISM SET SEARCH

PERFORM PRISM SET SEARCH lets you reset an end-user's index or search value, perhaps based on tests in your procedural code. This command does not actually do the search -- it simply transforms the search values and passes them back to Prism (which passes the new search request to SPIRES). In this sense, it's like $REPARSE in SPIRES.

For index exits

Index exits -- protocol steps associated with a particular index -- typically manipulate the user's search statement and then use PERFORM PRISM SET SEARCH to pass the new search statement to Prism for processing. [See 13.2 for more about index exits, including an example for ALSO processing.]

Syntax

The syntax is:

The "search-argument" consists of a valid SPIRES index and a search value (or a variable standing for a search value). It may also be a stored result name. The maximum length of "search-argument" is 253 characters.

Examples

In the example below, a user's NAME search is transformed to an OR search using two indexes (NAME and NEWNAME).

In the next example, a protocol step determines whether to proceed with a simple index built from QYY or to switch to the global QYY qualifier, depending on the command being processed. (When AND is used, the qualifier is much more efficient.)

13.2.4  PERFORM PRISM SEARCH (Use of This Command is Discouraged)

Not recommended

PERFORM PRISM SEARCH is virtually obsolete, and its use is discouraged. Note the limitations described at the end of this section. See the explanations of PERFORM PRISM SET SEARCH and PERFORM PRISM ASSIGN SEARCH for alternatives.

PERFORM PRISM SEARCH causes a search to be done in SPIRES and the result posted in Prism. The search could either establish a new result or modify an existing result.

One way to think of this command is that it's like doing a combination of a standard FIND in your protocol and then PERFORM PRISM ASSIGN SEARCH FROM RESULT.

The syntax is:

The search-argument consists of a valid SPIRES search term and a search value (or a variable standing for a search value, such as $SRCHVAL or $ACCT). Do not include a leading FIND, AND, NOT, or OR on your "search-argument". Prism adds the FIND or the appropriate Boolean operator (whatever was typed by the user).

Example

In this example, the user's search is modified so that he sees only salaries in his own department.

Interrupted Searches

If a search is interrupted (by a system error, ATTN/BREAK, or an end-user error caused by improper search values), control returns to Prism, not to the processing step. Prism then either reports the condition to the end-user, or reprompts the end-user for a new value, depending on how the interruption occurred.

Assuming no error or interruption occurs, then Prism returns control to the protocol step after performing the search.

Limitations When Using PERFORM PRISM SEARCH

A search type that does a PERFORM PRISM SEARCH in a protocol exit can only be used in a non-compound search, or when it is one of a set of indexes picked from the search type menu. (Multiple indexes picked from the menu are treated as iterative, not compound searches.) If an end-user does a compound search that includes a search type that does PERFORM PRISM SEARCH in a protocol step, he will get an error message indicating that this is an invalid use of the search type. (The user is referred to HELP COMPLEX SEARCH in Prism for an explanation.)

Note: In earlier versions of Prism, whenever a search step was coded, you were required to process the search in the protocol step (with PERFORM PRISM SEARCH or PERFORM PRISM ASSIGN SEARCH). Now, you may use a protocol step that does work other than processing the search (e.g., setting a flag, changing a search value with PERFORM PRISM SET SEARCH). Then, Prism will complete processing of the search, just as under automatic control. One benefit of this approach is that when Prism processes the search (rather than your PERFORM PRISM SEARCH command) you avoid the restriction described in the paragraph above.

13.2.5  PERFORM PRISM GET LOCAL (obsolete)

The PERFORM PRISM GET LOCAL command is obsolete as of the 7/92 Prism release. Its purpose was to access a search value for a secondary search type when multiple secondary search types were defined for an index. Secondary search types are no longer supported in Prism.

13.3  Pre-Search and Post-Search Protocol Steps

As mentioned at the beginning of this chapter, it is possible to install protocol steps to execute either before a search, or after a search has completed in SPIRES. These steps are not associated with a particular Prism search type, but instead will be done before or after any search. You may define separate post-search protocol steps for a zero and a non-zero search result.

Pre-search and post-search protocol steps are coded in your FILE protocol.

Pre-search

Although a pre-search protocol step would run before every search, it is expected that applications would only allow this step to execute before the first FIND of an application session. Your protocol code should set a condition and prevent the protocol code from executing except for the first FIND.

Pre-search and post-search steps are installed in XSETUP PROFILE. Here are the relevant questions:

 Orders                       XSetup Profile                02/08/92 14:12
                          ORDERS: Profile, page 3
 -------------------------------------------------------------------------

    Enter 'Yes' to see screens to add, modify, or delete processing steps.
     - when the subfile is selected or cleared: No_
     - before every search No_
     - when search is completed: yes_
    Enter 'Yes' if the protocol steps for this file are compiled: No_
 Orders                       XSetup Profile                02/08/92 14:13
                           ORDERS: Result Steps
 -------------------------------------------------------------------------

 Please identify processing steps that Prism should execute.

 Processing step to be executed for RESULT = 0
 STEP#    STEP ID           TYPE   COMMENT                    Note: To
     1    ________________    P    __________________________  remove a
                                                               processing
 Processing step to be executed for RESULT > 0                 step,
 STEP#    STEP ID           TYPE   COMMENT                     delete the
     1    ________________    P    __________________________  value under
                                                               STEP ID.

13.4  Special Kinds of Prism Indexes

Some of the indexes described here appear in special categories on the FIND menu because there are restrictions on their use.

Categories of indexes

Prism indexes can be divided into the following categories:

Appearance on the FIND Menu

Here is an example of a FIND menu, showing how different kinds of search types are labeled:

 Orders                        Search                        07/26/90 11:28

 --------------------------------------------------------------------------

 Choose a type of search by typing the name or number for each type of
 information you have, e.g. ACCOUNT or 1

 TYPE OF SEARCH   DESCRIPTION                           EXAMPLE
   1.  ACCOUNT    Account number                        424-35
   2.  TTYPE      Transaction type                      order
   3.  MYDEPT     Current records for your dept         --

 The following may not be combined with other indexes.
   4.  ORDCOUNT   Accounts with outstanding orders      3

 The following may only be used to qualify an existing search.
   5.  ORDSTATUS  Order status (O, F, or A)             O

MYDEPT is a value-supplied search type, as indicated by the absence of a sample search value on the FIND menu. To use it, you simply type FIND MYDEPT, without supplying a search value, since the application supplies the search value behind the scenes. [See 2.4 for more about value-supplied search types.]

ORDCOUNT is a stand-alone search type, and STATUS is a qualifying search type, as indicated by the headings on the FIND menu.

13.4.1  Stand-Alone Search Types

As mentioned earlier, you may specify that a search type may not be combined with other search types, i.e. that it must "stand alone". Stand-alone search types appear in a separate section of the FIND menu. [See 13.4.]

Purpose

Why would you install a non-combinable search type? The main reason is that the search type retrieves a stack instead of a normal search result. (A group of records accessed by key through Global FOR sequential processing is one example of a stack.) SPIRES does not allow stacks and search results to be combined into a single entity, so a stack-retrieving search type must be separated from the standard result-retrieving search types. (The only exception: a stack created from a normal search result with the SEQUENCE command may be combined with other search results, though the effect of sequencing will be lost.)

Stand-alone search types almost always use protocol steps.

Installing a Stand-Alone Search Type

A stand-alone search type is installed with XSETUP INDEXES (or ADD PROFILE for a new application) in much the same way as a regular search type. To designate it as stand-alone, answer 'yes' to this question:

Enter 'Yes' to declare or modify special features for this index: Yes

and on the screen that follows, choose "Stand-alone":

2_  <-- Indicate how this index is used by choosing one category
    1. Regular search type
    2. Stand-alone search type
    3. Qualifying search type

13.4.2  Secondary Search Types (obsolete)

Secondary search types are no longer supported in Prism (as of July 1992).

13.4.3  Qualifying Search Types

A qualifying search type never initiates a Prism search, but instead is used to qualify or refine a search result that has already been retrieved. A qualifying search type is not tied to any particular index -- it can be used to qualify the search result retrieved by any primary search type (except a "stand-alone") in the file.

Qualifying search types appear in a separately labeled section of the FIND menu. [See 13.4.] Prism ensures that a qualifying search type cannot start a new search (after FIND) or expand an existing one (with OR) but instead is used only to restrict an existing search result.

A qualifying search type might equate to SPIRES global qualifiers, although this is not a requirement. Or you might use non-index processing, such as ALSO, in a qualifying search type. (A regular SPIRES index could be installed as a qualifying search type, too.)

Installing a Qualifying Search Type

A qualifying search type is installed much like a primary search type. To designate it as such, answer 'yes' to this question:

Enter 'Yes' to declare or modify special features for this index: Yes

and on the screen that follows, choose "Qualifying":

3_  <-- Indicate how this index is used by choosing one category
    1. Regular search type
    2. Stand-alone search type
    3. Qualifying search type

14  Modifying Option Text

Customizing Option Text for Your Application

MOD OPTIONS

This optional chapter discusses the MOD OPTIONS form in Prism Profile, whose purpose is to let you customize some of the generic option messages accompanying your application in Prism (e.g., at the bottom of the screen in Guided Mode). In a few cases, using this form to change option text (such as explanations of OK and SEND) will also affect the message line in Command Mode.

Customizing options text may help direct your end-users to important features of your application that the standard option text might cause them to overlook.

Benefits from MOD OPTIONS

MOD OPTIONS can be useful whenever a particular task or activity can be stated in narrowly-focussed terms. For example, suppose your application contains a single entry form that always accomplishes the task of adding an address to a file. Then instead of the standard option text for the ENTRY command, which mentions data but doesn't specify what kind of data, you might want to customize your option text to specify that the data always involves addresses:

Instead of this....

You might want this:

Likewise, if your application contained a single report, whose purpose was to create mailing labels you might customize the options text describing the REPORT command.

You might change this...

to this:

SHOW OPTIONS Display

Changing option text in MOD OPTIONS affects not only the standard interface in Guided Mode, but also affects the complete listing of options and descriptions that end-users see online by typing the command OPTIONS (alias SHOW OPTIONS).

Some Restrictions

Note that you cannot modify the Prism commands themselves, only their descriptions. As a system-wide standard, the command names must stay the same for all Prism applications, so that end-users who need to use more than one application don't need to memorize additional commands and variants ad infinitum.

Also note that with MOD OPTIONS you can customize some of the data entry option text that appears during data entry (e.g., the text describing the OK command), and this text can be specific to a particular entry form -- but it cannot be tied to a particular screen within the entry form. Thus, if you have a four-page entry form with a slightly different task on each screen, your text describing the "OK" option would have to apply to all of the pages after the first one. It couldn't focus on a particular screen. If you use custom control of data entry, your PERFORM PRISM SCREEN commands may include parameters to control the options text on a screen-by-screen basis. [See 12.1.3.]

List of Option Descriptions That You Can Modify

Here is a list of the different option text messages that MOD OPTIONS lets you customize. The different messages are grouped together according to whether the message would appear:

In the series of paired lines below, the top line shows the standard Prism message; the bottom line shows by way of periods how much space you have to customize a message:

Additional Notes:

The periods in the charts above indicate the maximum length of the customized option text. The "Type: <command> to " part of the text cannot be modified. Prism automatically supplies the period at the end of each customized option.

15  PERFORM PRISM SERVICE SUFIN GETAUTH

PERFORM PRISM SERVICE SUFIN GETAUTH is a tool to create an authorized view of the currently selected file, by setting a search modifier based on the user's "read" authority for University fund accounts.

Syntax

SUFIN GETAUTH performs a search, stores a temporary result, and sets a search modifier to AND or AND NOT that stored result, depending on the user's authority. Upon successful completion of the call, $STATUS is set to 'OK', 'NOAUTHORITY', or 'NORESULT'.

  ALL                SALARY
  ENDROUTE           SPOPROJ
  EQINV              STORES
  EXPENSE            SUFFUNDS
  FORMS              XPOPROJ
  JOURNALS           ZUFACCTS
  PAYROLL            ZUFFUNDS
  READ               ZUFJNLS
  REQS

$STATUS Values

The $STATUS variable is set to 'NORESULT' if authority was found for the SYSTEMID/USERID pair, but no records were found in the caller's subfile to match that authority. NORESULT indicates that there are no records in the currently selected file that this user is authorized to see. In this case, no search modifier is set.

A special case of $STATUS = 'OK' and no search modifier set can occur if the user has no restrictions for the current system.

If a SYSTEMID/USERID pairing results in no authority being found, then no search modifier is set and $STATUS = 'NOAUTHORITY'.

16  Secondary Files for Linking

Normally, a Prism application installed with ADD PROFILE appears on the SELECT menu in Prism to at least one person (according to the access rules that you specify).

Secondary files, on the other hand, do not appear on the SELECT menu but instead are accessible behind the scenes only. For instance, your primary Prism application might need to link to a second file in order to look up and retrieve information from the second file. Secondary files do not need the components normally installed for Prism applications (displays, helps, etc.)

Primary Files vs. Secondary Files in Prism

   Primary File                             Secondary File
   --------------------------------         -----------------------------
   Visible on Prism menu --                 Invisible to users --
   a primary file is                        a secondary file is only
   accessible through SELECT                accessible to authorized
   command to all authorized                accounts and files via
   accounts                                 PERFORM PRISM LINK

   Needs indexes, help records,             Doesn't need visible
   a display format, etc.                   features such as helps

   Installed through ADD PROFILE            Installed through ADD LINK

   Modified via MOD PROFILE                 Modified via MOD PROFILE

Though you can sometimes use SPIRES path processing commands in a protocol step to access other files, installing a secondary file lets you control access to it more securely -- you can use the PROGRAM = PRISM statement (as described below) to guarantee that other applications can link to your file only in Prism, and only through the PERFORM PRISM LINK command.

Steps for Installing a Secondary File

Modifying the SUBFILE Section for a Secondary File

Just as you did for your primary file, add a SUBFILE-NAME in the form "Prism <file-id>", where "file-id" is that of the secondary file. Also add ACCOUNTS and PROGRAM statements as shown below.

E.g., for a secondary file with a file-id of LINKDEV:

If you are using File Definer to create your SPIRES file, the input line defining the Prism view of the file might look like this:

Because security for access to the secondary file is best determined in Prism Profile, your SPIRES subfile section should almost certainly use ACCOUNTS = PUBLIC. The PROGRAM = PRISM statement ensures that this subfile view is available only in Prism and not in SPIRES.

Special Case: Entry Form for a Secondary File

There is one situation where you would need to install a "normal" application component for a secondary file. A routing application may link to a secondary file in order to route a form. If this is the case, and if the routing application supports "modification-during-examination" then the secondary file will need to have an entry form installed for use as the "approval entry form". [See the Routing Applications manual for complete explanations.]

For this reason, the XSETUP FORMS command is allowed for a secondary file.

16.1  Installing a Secondary File: ADD LINK Entry Form

First page

The first page of ADD LINK asks questions familiar from ADD PROFILE, concerning the application's name and the person(s) responsible for it:

 _____________________________________________________________________________
 Prism Profile              Entry Form: ADD LINK                10/15/87 11:14
 Profile, page 1
 -----------------------------------------------------------------------------
 Enter the file's internal Prism identifying code (e.g. PUBEVENT).
 File-ID: ________________

 Enter the SPIRES file-name for this subfile (e.g. GQ.DOC.PUBLIC.EVENTS).
 SPIRES file-name: ______________________

 Enter the name and phone number of the person responsible for this
 application: __________________________________________________________

 Enter the electronic mail account to which Prism communications
 will be mailed: gg.uuu____________________________________________

 Indicate accounts, groups or access lists to maintain profile records:
 gg.uuu......................................................................

 _____________________________________________________________________________

Access to link file

The second page of ADD LINK is slightly tricky: here you give access to your file to specific Prism developers (including anyone who can select these developers' files) and to specific Prism applications:

 _____________________________________________________________________________
 Prism Profile              Entry Form: ADD LINK                10/15/87 11:16
 <fileid>: Profile, page 2
 -----------------------------------------------------------------------------
 Indicate owner accounts of applications that may access this file.
 gg.uuu......................................................................
 ............................................................................
 ............................................................................
 ............................................................................
 ............................................................................
 ............................................................................
 ............................................................................
 ............................................................................
 Indicate Prism File-Ids that may access this file:
 ................ ................ ................ ................
 ................ ................ ................ ................
 ................ ................ ................ ................
 ................ ................ ................ ................
 ................ ................ ................ ................
 ................ ................ ................ ................
 _____________________________________________________________________________

It's important to note that this page widens access to your secondary file, rather than restricting it. People given access by account can link even if you don't also give their applications access by name.

16.2  Using a Secondary File

PERFORM PRISM LINK and PERFORM PRISM UNLINK

Once the secondary file is installed, any account or application authorized through ADD LINK can link to it using the PERFORM PRISM LINK and PERFORM PRISM UNLINK commands in a protocol. [See 12.1.4 for a full description of PERFORM PRISM LINK.]

Modifying or Removing a Secondary File

If you need later to modify the description of your secondary file, you can use XSETUP PROFILE, just as you would for a primary file. [See 8.]

If you decide later to remove your secondary file, you can use REM PROFILE, just as for a primary file. [See 8.6.] Remember to notify the people linking to your file, since their applications may stop working when you remove your secondary file.

17  Appendix: Variables in Prism

The variables listed below are useful for communicating information from your application to Prism or vice-versa. Functions they support include:

 - Conditional returns from your code ($STATUS)
 - WARN-level reprompts during input ($STATUS)
 - Passing commands back to Prism for execution ($NEXTCMD)
 - Accessing status information from Prism ($SCRNSTAT, etc.)

All the variables listed are of type STRING and can be used either in formats (by way of a UPROC) or in protocols. Except for $DESTINATION ($DEST), the variable names cannot be abbreviated.

You can set the value for some of these variables yourself. Values for the other variables are set internally, but can be read by your code.

       Variables You Can Set     Variables Set by Prism

       $MSGLINE [255]            $DESTINATION [16]   $PRISMID [16]
       $NEXTCMD [255]            $DESTVAL [64]       $RECID [240]
       $FIELDVAL [255]           $EVENTZONE [16]     $REPTNAME [16]
       $STATUS [16]              $FORMNAME [16]      $SCRNSTAT [16]
       $CGINAME [16]             $LASTCMD [24]       $SRCHTYPE [16]
       $PARM *                   $MAINCMD [24]       $SRCHVAL [255]
                                 $UNIVEMAIL [64]     $PROXYEMAIL [64] +
                                 $UNIVID [32]        $PROXYID [16]    +
                                 $UNIVNAME [64]      $PROXYNAME [64]  +
                                 $UNIVPHONE [36]     $PROXYPHONE [36] +

The maximum size of these variables is shown in brackets. Note that several of these variables may be used by non-Prism applications, such as the "suspires" web interface application.

17.1  $DEBUG

(Maximum Length 1 Character)

The $DEBUG flag-type variable is set to true when DEBUG is in effect for you in Prism. Thus its value is true when both of the following conditions are true: 1) you have issued the SET DEBUG command (or another debugging command such as SET FTRACE that implicitly performs a SET DEBUG command); and 2) an application is selected to which you have authorized access as a developer.

$DEBUG can be very useful when you want your application to behave slightly differently in debugging mode -- for instance, when you want to save certain values while debugging that you wouldn't save during an ordinary session. [See 7 for more information on debugging tools in Prism.]

$DEBUG is also the name of a control word for help records, which has somewhat different uses. [See 6.3.12.]

17.2  $DESTINATION (alias $DEST), $DESTVAL

($DEST: Maximum Length 16 characters; $DESTVAL: 64 characters)

$DEST and $DESTVAL indicate the output destination that the end-user requested when filling out Prism's PRINT screen. $DEST will contain a word indicating a "generic" destination, while $DESTVAL will contain the specific output destination, e.g. a specific printer name.

When a user completes the PRINT screen, $PARM is also assigned values reflecting the options chosen for the destination. For example, when $DEST is 'PRINTER' and $DESTVAL is a specific printer name, the $PARM variable contains the printing options entered by the user.

These variables will be essential if you dispatch report output yourself instead of having Prism dispatch the output. [See 10.4 for a description of dispatching output yourself.]

Note that a $DEST value of SCREEN, described separately below, is useful even for Prism-dispatched reports -- it lets you distinguish the online Prism environment from other output "destinations" such as the printed page.

Values of $DEST and $DESTVAL and $PARM may be:

 $DEST       $DESTVAL                 $PARM examples
 ---------   ----------------------   ---------------------------------

 PRINTER     FORSYTHE                 DEST=FORSYTHE,COPIES=2,FORMS=3HOL

 PRINTER     DTRLW                    DEST=DTRLW,LANDSCAPE

 ATTACHED    [null]                   TITLE='Summary Report'

 EMAIL       GQ.JPR                   GQ.JPR, TITLE='Errors in Prismdoc'
             SPIRES@SLACVM            SPIRES@SLACVM

 FILE        WYL.GQ.LTM.DATA TEMP     WYL.GQ.LTM.DATA TEMP
             PRISM#DATA ACC GQ.PUB    PRISM#DATA ACC GQ.PUB
             PRISM#DATA               PRISM#DATA REPLACE
             ACTIVE                   ACTIVE CLEAR

$DESTINATION = SCREEN

$DESTINATION is set to SCREEN when Prism is negotiating an online display. This value can be useful when you want a report to behave one way during an online DISPLAY, and another slightly different way in offline printing. For instance, you might use ruling font characters in the online display, but remove them from the printed output where their appearance would be inappropriate.

17.2a  $EVENTZONE

(Maximum Length 16 characters)

When a choice, trigger, or button "event" occurs, $EVENTZONE contains the name of the zone that triggered the event.

One situation where you might find it necessary to test $EVENTZONE is if you are using Prism's stem-matching capabilities for zone names, to accommodate "multiply-occurring zones". [See 12A.4A for an example of this technique.]

17.2b  $FIELDVAL

(Maximum Length 255 characters)

When the f2=*Choices key is pressed or data is entered into a trigger field, $FIELDVAL contains the value that was present in the field.

In a choice event

For f2=*Choices, it contains the value in the field where the cursor was positioned. If the cursor was not in an input field, the value is taken from the first unprotected field within the active zone following the cursor position.

During a choice event, if the REPLACE option was included on your PERFORM PRISM CHOOSE command, then the user's choice is placed into $FIELDVAL. The INPUT option on PERFORM PRISM CHOOSE defines which element or array is used for the values going into $FIELDVAL. $FIELDVAL is then used to place a value into the field on the main screen from which the CHOICES command was issued. [See 12A.10.]

You may SET FIELDVAL yourself to control what value is carried back to the main screen. The user's choice from PERFORM PRISM CHOOSE is also placed in $PARM. You might choose to manipulate $PARM and then SET FIELDVAL near the end of the protocol for your choice event.

In trigger events

For trigger events, you may SET FIELDVAL " " explicitly, in order to reset the trigger field to blank when the user returns to the main screen after a trigger box. Or you may set FIELDVAL to any other value appropriate for the trigger field at the conclusion of the trigger event.

Cursor positioning

You may imbed cursor positioning control sequences in your SET FIELDVAL command to place values in multiple fields or otherwise control where the cursor is positioned as a value is placed. [See 12A.15 for examples.]

17.3  $FORMNAME

(Maximum Length 16 characters)

This variable names the currently selected entry form. Its value is null outside of data entry.

17.4  $LASTCMD and $MAINCMD

The variables $LASTCMD and $MAINCMD contain the commands the end-user has last issued. They contain the command verb only, not the complete command string (with options).

$LASTCMD contains the latest command issued by the end-user. It is reset every time the end-user is prompted and has issued a command to Prism.

$MAINCMD is not reset every time the end-user issues a command. Instead, $MAINCMD "remembers" the last command that initiated a multi-part end-user request such as doing an entry transaction. The following commands are currently included in $MAINCMD since they can lead to menus or input screens:

  SELECT, ENTRY, REPORT, FIND, AND, NOT, OR, DISPLAY, SORT,
  SETUP, GET, CREATE, PRINT, DISPLAY REPORT, REVIEW

Note that $LASTCMD is valuable in distinguishing relatively local command actions, such as OK vs. PREVIOUS, while $MAINCMD can be used to distinguish the larger process in effect, such as CREATE vs. GET. (Both $MAINCMD and $LASTCMD would contain the same value at the start of a larger process.)

The value in $MAINCMD and $LASTCMD will be a full command verb, in upper case. For DISPLAY REPORT, the value will be DISPLAY REPORT. Where Prism allows command alternatives, the implied command will be stored in $LASTCMD. For example:

   Command       is equivalent to      $LASTCMD
   -------       ----------------      --------
   n             DISPLAY n             DISPLAY
   FULL          DISPLAY FULL          DISPLAY
   BRIEF         DISPLAY BRIEF         DISPLAY
   OPTIONS       SHOW OPTIONS          SHOW
   DUMP          IN ACTIVE SHOW        SHOW
   EXPLAIN       HELP                  HELP
   AND NOT       NOT                   NOT

The RETURN Key and $LASTCMD

$LASTCMD and the RETURN or ENTER key interact differently in different situations. When an end-user has configured his RETURN key to mean OK (with SETUP PRISM) and is paging forward through entry screens or parameter-input screens, the RETURN key is essentially an alternate form of the OK command, so the value of $LASTCMD is OK. Anywhere else, however, a user's pressing RETURN/ENTER will place no value into $LASTCMD, i.e., $LASTCMD will be a null string.

$LASTCMD and $MAINCMD in Searching

In a simple search, $LASTCMD and $MAINCMD both are set to "FIND". In a compound search or an iterative search, $LASTCMD will reflect the Boolean operator for the search value currently being processed. In general, in protocol steps related to searching, it is most useful to test for $LASTCMD if you need to take action based on the kind of search operation being done.

   find status archived

       $MAINCMD = FIND
       $LASTCMD = FIND

   find status archived and date 1992

       $MAINCMD = FIND
       $LASTCMD = FIND while STATUS ARCHIVED is processed
       $LASTCMD = AND  while DATE 1992 is processed

   and approver biddle

       $MAINCMD = AND
       $LASTCMD = AND

17.5  $MSGLINE

(Maximum Length 255 characters)

The $MSGLINE variable lets applications establish a message to be written in the reverse video message area. $MSGLINE covers special situations that Prism cannot foresee, for which the general Prism messages might be insufficient. In situations where the $STATUS variable must be set to STOP, you might want to provide a special message to end-users through $MSGLINE.

After SET STATUS 'STOP' the value for $MSGLINE is displayed in a box on the screen, along with a generic Prism message indicating that a command was not processed. [See 9.2.5.] Otherwise, it replaces the normal message in the message line of Prism's display.

When $MSGLINE is displayed on the message line, there is room for 78 characters; when it is used after SET STATUS 'STOP', up to 256 characters may be displayed.

After SET STATUS 'SYSERROR' the value for $MSGLINE is disregarded.

17.6  $NEXTCMD

(Maximum Length 255 characters)

Use the $NEXTCMD variable to pass a command or command chain to Prism for processing. Note that the command or command chain in $NEXTCMD will only be processed at the successful completion of the current "command cycle". (A "command cycle" is, generally speaking, any process initiated by a command that involves multiple interactions with the end-user before the command;s intended function can be completed. Any command that invokes menus, parm screens or input screens begins a command cycle.)

For instance, you might pass a DISPLAY command for Prism to issue at the end of an entry form "command cycle", but you would not pass a command such as GET or SEND, because those commands would disrupt the entry "command cycle".

17.6a  [This section is not applicable to Stanford application developers]

17.7  $PARM

(Maximum length 32,000 characters; maximum 256 characters when set by SET PARM Uproc during format execution)

Besides its uses in SPIRES, the $PARM variable is used in a variety of ways by Prism: in print processing; when a "secondary" search type is used; in choices events (boxes); with PERFORM PRISM PROMPT VALUE; during ID/PIN prompting; and for cursor positioning.

$PARM is reset by certain commands, such as SET FORMAT and SELECT. Take care to save off its value before issuing a command that might change that value.

$PARM in Print Processing

When a user fills in the Prism PRINT screen, $PARM, $DEST, and $DESTVAL are assigned values reflecting the options chosen on that screen. If you decide to dispatch report output yourself in a protocol step, you will need to determine the values of these variables in order to construct the appropriate command for dispatching the report output. [See 17.2 for a description of $DEST and $DESTVAL.]

Some possible values for $PARM in association with $DEST are shown below:

 $DEST       $DESTVAL                 $PARM examples
 ---------   ----------------------   ---------------------------------

 PRINTER     FORSYTHE                 DEST=FORSYTHE,COPIES=2,FORMS=3HOL

 PRINTER     DTRLW                    DEST=DTRLW,LANDSCAPE

 ATTACHED    [null]                   TITLE='Summary Report'

 EMAIL       GQ.JPR                   GQ.JPR, TITLE='Errors in Prismdoc'
             SPIRES@SLACVM            SPIRES@SLACVM

 FILE        WYL.GQ.LTM.DATA TEMP     WYL.GQ.LTM.DATA TEMP
             PRISM#DATA ACC GQ.PUB    PRISM#DATA ACC GQ.PUB
             PRISM#DATA               PRISM#DATA REPLACE
             ACTIVE                   ACTIVE CLEAR

$PARM in Choice Events (Boxes)

When the user makes a choice from a choice box, the chosen value is placed into $PARM (and also in $FIELDVAL if the REPLACE option was used on PERFORM PRISM CHOOSE). The INPUT option on PERFORM PRISM CHOOSE defines which element or array is used for the values going into $PARM and $FIELDVAL. [See 12a.10, 17.2B.]

$PARM and PERFORM PRISM PROMPT VALUE

When you use PERFORM PRISM PROMPT VALUE, the value that the user enters on the resulting screen is saved in $PARM. [See 12a.11.]

Cursor Positioning

In a protocol or a format, you may SET PARM to control cursor positioning:

[See 12a.17.]

$PARM During ID/PIN Prompting

After a successful PERFORM PRISM LOOKUP NAME or PERFORM PRISM PROMPT NAME command, $PARM will contain a University ID and name, concatenated with a slash. Typically, the ID portion of $PARM would be extracted for use in a subsequent PERFORM PRISM PROMPT PIN command. [See 25.3.2 for details and examples.]

17.8  $PRISMID

(Maximum Length 16 characters)

The $PRISMID variable holds the fileid ("Prismid"), from 1 to 16 characters, of the Prism file that the user has currently selected. Note that if one Prism application calls another one (for instance, with PERFORM PRISM LINK) the value of $PRISMID still reflects the calling application, which is what the user sees as the selected file.

17.9  $PROXYID, $PROXYNAME, $PROXYPHONE, $PROXYEMAIL

These variables contain the ID, name, phone number, and email address of the person or work group for whom the current user is acting, if ID/PIN prompting has happened and the user has filled in the "Acting for" field to specify that he is acting as a "proxy".

Details about identifying users by ID and PIN and proxy identification are in a later chapter. [See 25, 25.6.]

17.10  $RECID

(Maximum Length 240 characters)

The $RECID variable holds the value of the key of the current record as known to Prism. For instance, after a command such as PERFORM PRISM OPEN, RECORD = '123' the value of $RECID would be 123.

Single record displays, the REVIEW command, and entry transactions are among activities that set (or reset) $RECID.

Using $RECID Instead of $KEY

Note that $RECID is in some ways similar to the SPIRES variable $KEY, but you should use $RECID, not $KEY, to keep track of the key of your record in Prism. (This is because the value of $KEY might be reset within a transaction in your file -- e.g., if an end-user requested help.)

When $RECID is Set (or Reset)

Note that the $RECID variable can have only a single value at a given time on each path that you have made known to Prism. (To make a path known to Prism, use the PERFORM PRISM LINK command -- do not use SPIRES path processing commands.) [See 12.1.4.] For example, if during data entry your code opens more than one record, $RECID is reset each time a new record is open, and represents the latest opened record.

After command (1), $RECID is A12345. After command (2), $RECID is reset to A99999 and the earlier value is lost unless you saved it in the meantime in your own variable.

$RECID and Secondary Files

$RECID is set specifically for each path that your code opens in Prism using PERFORM PRISM LINK -- for example, if your application links to a "secondary file" and opens a record in that file, $RECID will be set to the newly opened record in the secondary file. When you UNLINK from that secondary file, the value of $RECID reverts to the most recently opened record in your primary file.

17.10a  $DISNUM

(Maximum Length 16 characters)

The $DISNUM variable holds the number of the current record as known to Prism. Multiple record displays are among the activities that set $DISNUM.

Using $DISNUM Instead of $RECNO

Note that $DISNUM is in some ways similar to the SPIRES variable $RECNO, but $DISNUM is only modified by PRISM PERFORM or Folio processing. Outside of Prism/Folio, $DISNUM may be used for your own purposes.

17.11  $REPTNAME

(Maximum Length 16 characters)

This variable names the currently selected report. Its value is null outside of Report Activity.

17.12  $SCRNSTAT

(Maximum Length 16 characters)

Prism sets this variable as the status of the current input screen. Sometimes the value of $SCRNSTAT may be set in response to a value you have earlier given to $STATUS (e.g., SET STATUS = 'WARN' might lead to a $SCRNSTAT value of WARN) but you never set $SCRNSTAT yourself. Here are the possible values:

17.13  $SRCHTYPE

(Maximum length: 16 characters)

The $SRCHTYPE variable contains the name of the search type (index) being processed. For example, if the current search is FIND STATUS SENIOR, then $SRCHTYPE contains the value "STATUS".

17.14  $SRCHVAL

(Maximum length: 255 characters)

The variable $SRCHVAL is used by Prism to store the value that the end-user of your application has entered for a primary search type during the current Prism search. For instance, if the current search is FIND STATUS SENIOR, then $SRCHVAL contains the value "SENIOR".

In a protocol processing step for that search type, your protocol code can access $SRCHVAL to see what value the end-user has supplied, or can issue a customized search behind the scenes, using the value of $SRCHVAL in a PERFORM PRISM command, e.g.:

[See 13 for more examples.]

The $PARM variable operates somewhat similarly to $SRCHVAL during searching, but stores a value that was input for a secondary search type.

For the sake of consistency with earlier versions of Prism, the $ASK variable is set to the same value as $SRCHVAL; however, since the value of $ASK is frequently reset, you should definitely rely on $SRCHVAL, not on $ASK, to determine a current search value.

17.15  $STATUS

(Maximum Length 16 Characters)

The $STATUS variable tells Prism to alter normal processing of the current command sequence in your application's format or protocol. ($STATUS is cleared when your format or protocol is first invoked.) Many of these $STATUS values indicate a condition other than a normal, successful end to processing. Here are possible values for $STATUS:

Within an event, if your application sets $STATUS to STOP or SYSERROR or if an unexpected error occurs (such as a PERFORM PRISM syntax error), the main transaction (not just the event) will be terminated. Choice events are an exception, however. If an error occurs in a choice event, even if you set $STATUS to STOP or SYSERROR, the event will stop but the main transaction will not stop. Prism gives a message "Error processing CHOICES command" in this case.

When you set STATUS, make sure it is the last thing you do before returning. [See 11.3.2 for setting status during data entry, 9.2.5 for setting status from within a protocol.]

REPROMPT, REDISPLAY, REPEAT, and RESTART Status

You SET STATUS to one of these values in order to redisplay a Prism screen. What is the difference between these four $STATUS values? Here is some summary information to help explain the differences.

REPROMPT

 - Reprompts the screen.
 - Makes the message line display bright and yellow.
 - Turns on the ?ERROR help context and positions the cursor at EROW/ECOL.
 - A default message about  errors  is  provided:  "Errors  found;  type  HELP  <error
 code> below for more information"
 - Remembers changed-field information.
 - Does not reset the scope of UNDO.

REDISPLAY

 - Reprompts the screen like REPROMPT but does not turn on error condition (so does not do any
 of the other things listed above)

REPEAT

 - Goes through the .OUT frame again.
 - Re-initializes changed-field information.
 - No default message; ?ERROR help context is not set.
 - Cursor is placed at position 1,1 (so it goes to the first field on the screen).
 - Does not reset the scope of UNDO.

RESTART

 - Exactly the same as REPEAT, except that it resets the scope of UNDO.

Refer to the chart explaining Prism screen processing for further information about how these $STATUS values are used. [See 12a.1.]

$STATUS During ID/PIN Prompting

The $STATUS variable is also set by the PERFORM PRISM LOOKUP NAME command:

Details about PERFORM PRISM LOOKUP NAME are in a later chapter. [See 25.3.2.]

And after a PERFORM PRISM LOOKUP PROXY command, $STATUS will have one of these values:

17.16  $UNIVID, $UNIVNAME, $UNIVPHONE, $UNIVEMAIL

These variables contain the ID, name, phone number, and email address of the current user, if he has gone through an ID/PIN prompt to identify himself.

This group of variables is also set when a temporary employee identifies himself by giving his name and confirmation code.

Details about identifying users by ID and PIN are in a later chapter. [See 25.]

18  Appendix: Checklist of PERFORM PRISM Commands

The Basics for Data Entry

Basics

Events and Boxes in Screen Processing

Events and boxes

Specialized Techniques for Screen Processing and Flow

Special techniques

General Tools

General

For Control of the Searching Environment

Searching

ID/PIN Identification

ID/PIN

Forms Routing

Routing

19  Appendix: Restrictions on Protocol Code

20  Appendix: Checklist of Help Records

The following is a summary of the minimum set of help records needed for Prism applications. "R" means that the record is required. To see this chart online in SPIRES, EXPLAIN HELP RECORDS, CHECKLIST.

[See 6 for general information about help records, 10.7 to read about helps for reports, 9.1.1 to read about helps for entry forms and screens.]

Helps for Basic Installation

     ?WELCOME                            Welcome screen for your file (R)

     <file-name> FILE                    Description of your file (R)

     <indexterm> INDEX                   Help for each index (R)

     <display-name> DISPLAY              Help for each display (R)

     ?DISPLAY/<display-name>             Context help for displays

Helps for Reports

     ?INTRO/REPORT/<report-name>         Intro screen for report (R)

     <report-name> REPORT                General information on the report (R)

     ?REPORT/<report-name>               Context help for report

Helps for Entry Forms and Other Screens

     ?INTRO/FORM/<form-name>             Intro screen for entry form (R)

     <form-name> FORM                    General information on the form (R)

     ?INPUT/FORM/<form-name>/<step-id>   Context help for each input screen
                               (*)       in a form (strongly recommended)

     ?ERROR                              Single record explaining all
                                         error codes for all input screens (R)

     ?INPUT/FILE/<step-id>               Context help for input screens
                   (*)                   associated with file selection

     ?INPUT/REPORT/<report-name>/<step-id>   Context help for input screens
                                   (*)       associated with the named report

(*) "Step-id" is the identifier of the screen, also known as "screen-id". It is the value used as follows in the protocol code generating the screens. This applies both to regular screens and to boxes overlaid on top of screens.

  PERFORM PRISM SCREEN screen-id ID=id    (if ID is present, use that for
                                           your helps, otherwise screen-id)
  PERFORM PRISM CHOOSE ID=screen-id

  PERFORM PRISM PROMPT TEXT ID=screen-id

  PERFORM PRISM PROMPT VALUE ID=screen-id

For an entry form installed with "automatic control", step-id is the value you enter in XSETUP FORMS to identify the "screen step" -- i.e. the name of the format frame called by Prism to generate the screen.

21  Appendix: Checklist of Protocol Names

Protocol code to support Prism applications is stored inside Procs within protocols in the PRISM PROTO subfile in SPIRES.

The protocol's key is listed on the left; some possible uses of the protocol code are listed on the right.

Key                           Example                 Possible Uses
___                           _______                 _____________

* FILE                        * FILE                  Hidden search;
                                                      search steps
                                                      (protocol steps for
                                                      an index);
                                                      other tasks related
                                                      to file-selection or
                                                      file-exit.

* REPORT/<report-name>        * REPORT/LABELS         Hidden search;
                                                      statistics; other
                                                      tasks to support
                                                      reporting.

 * FORM/<form-name>           * FORM/MOD PROFILE      Hidden search;
                                                      statistics; custom
                                                      data entry; other
                                                      tasks to support
                                                      data entry.

(Note: <report-name> and <form-name> are 12 characters maximum.)

[See 9 for more information on protocol processing steps.]

22  Appendix: The Prism Log

This appendix discusses command logging in Prism, and in particular discusses the following topics:

Benefits of Checking the Log

Checking the log for your application provides the following important benefits, among others:

 - It provides the SPIRES error numbers for any errors that occur while  your  application  is
 being used.
 - It can help you measure the efficiency of your application  --  e.g.,  the  amount  of  CPU
 consumed in a typical use of a report or entry form.

Logging Resource Use

The entries below suggest some ways you can measure your application's use of system resources. (By the way, although log entries include date and time, we've deleted that information below, in order to emphasize other parts of the log. Also, the figures shown below are fictitious.)

SEL, CLR, SEN, DIS Entries

Note the three letter code appearing in roughly the middle of every entry, SEL, CLR, SEN, DIS, etc.:

 - A "SEL" log entry is generated every time someone selects  your  application,  so
 counting  these entries tells you the total number of times your file was selected within a
 given period.
 - A  "CLR"  log  entry  is  generated  every  time   somebody   either   de-selects
 ("clears")  your  file or uses the PAUSE command to interrupt their Prism session
 while selecting your file.  Since Prism initializes the count for each CLR entry,  you  can
 use  it  to  determine  how  your  application  is  using  system resources.  Adding up the
 "CLR" entries in a day's log gives you a day's totals in resource use.
 - A "SEN" log entry is generated after  every  successful  data  entry  transaction
 (every  "SEND")  in  your  application.   This  entry provides important resource
 measurements for a particular entry form.
 - A "DIS" entry is created after the "CLR" entry for each display used in
 the file during that session.  The entries tell how many times the  display  was  requested
 and how many records were processed using the display.

Logging Errors

Errors in the log are marked by the tag "ERR:" as below. (For a fuller explanation of these tags, see further below.) Errors indicating that a basic task or command has failed are marked by a leading hyphen in front of the message that the end-user would see online:

Detailed Description of Log

 GO.BLI*2T 10/19/86 10:36:34 TESTCATG......../CS1 SEA: St=0,Res=22, FIND ...
   |    |     |        |       |              |             |
  (A)  (B)   (C)      (D)     (E)            (F)           (G)

(A) -- account (including number for multiple logon account after asterisk)

(B) -- version (P=Production, T=Test, N=Preprod, O=Old)

(C) -- date

(D) -- time

(E) -- file-id of selected file (padded with periods if necessary to make up the 16-character maximum)

(F) -- represents mode (G = Guided, C = Command), activity (S = Search or none, R = Report, E = Entry), and path (0 = no file selected, 1 = primary file, 2 through 9 = secondary file)

(G) -- the different entries in (G) are described in the next few pages.

22.1  Explanation of Log Entries

WEL: <username and ID> (Project xxx, <termtype:termsize>, <Samson and DOS

 

version>

SES: #n, Line nnn, <session identifiers>

The WEL and SES log entries together indicate the start of a Prism session. The SES entry contains identifiers such as the Milten internal session tag, the WYLBUR/TESTWYL indicator, front-end port identifiers and Internet address ID. If the user has started a session in which he has identified himself by University ID, his name and ID ($UnivName and $UnivID) are included in the WEL entry. Otherwise the name associated with the logged-on account is shown.

CMD: <command> (not kept in stored log)

Tells what command the user issued. The command is preceded by "Fn=" if a function key was used to issue the command. The log entry will indicate if the user was "timed out" before the command was completed. If the command was automatically supplied by Prism, the word "Supplied" appears as part of the entry. For instance, if you asked for an automatic GET to be issued after a search result of one record.

MEN: <MenuName>, Response: <command> (not kept in stored log)

Similar to CMD above, except that the user is viewing a menu (e.g., for form-selection or report-selection).

SCR: (Screen <screen-id>)

Records the screen that the user visited.

MSG: (Command: <user command>) <Prism message>

Shows the message given when a command syntax error occurs.

BEG: CPU=__,Min=__,I/O=__

The end-user has issued the BEGIN command to begin a brand new Prism session. The CPU, elapsed time, and I/O shown are cumulative from the initial Welcome to Prism. Elapsed time is labeled with either "Min= " or "Sec= '.

END: CPU=__,Min=__,I/O=__

The user is ending his or her Prism session via the END command or one of its synonyms. The CPU, elapsed time, and I/O shown are cumulative from the initial Welcome to Prism.

PAU: CPU=__,Min=__,I/O=__

The user has issued the PAUSE command. Statistics are recorded here in case the user does not return to Prism. The CPU, elapsed times, and I/O shown are cumulative from the initial Welcome to Prism.

SEL: <filename>, (Contact: <contact-account>, CPU=__,Min=__,I/O=__)

The end-user has issued the SELECT command and successfully selected a file. The log displays the file's name, as it appears on the Select menu, as well as the contact account of the person responsible for the application.

CLR: CPU=__,Min=__,I/O=__, (<file name>)

The end-user has either de-selected your application or issued the PAUSE command. In either case, the statistics shown for CPU, elapsed time, and I/O are cumulative from the point when the user first saw the Welcome to Prism screen.

DIS: <DisplayName> Cmds:___, Records:___

After a CLR log entry, one or more DIS entries are generated to give information about the displays used during the session. The entry includes the display name and a count of how many times the display was requested and how many records were processed using the display.

SEA: St=n,Res=nnn,CPU=__,Min=__,I/O=__, <search>

After the end-user performs any search, including one with a zero result, "St" above will display the value for $SRCHSTAT, normally a zero. "Res" will display the current result count. For more information on the SPIRES variable $SRCHSTAT (not to be confused with $SRCHVAL), see the document "SPIRES Protocols".

ENT: <FormName> (CPU=__,I/O=__,Sec=__)

Indicates successful selection of named form. The statistics apply to setting the entry form only (plus processing initial parm screens), not using the entry form.

REP: <ReportName> (CPU=__,I/O=__,Sec=__)

Indicates successful selection of named report. The statistics apply to setting the report only (plus processing initial parm screens), not using the report.

DRP: <ReportName>, Rec=n,CPU=__,I/O=__,Min=__ (<report type>)

Indicates a DISPLAY REPORT command, and shows the number of records processed as well as CPU and elapsed time. The "report type" will be either "Developer report" or "Personal report". For personal reports, the log entry will also indicate whether the report was processed via direct record access, a display set, or a SPISORT set.

ERR: <message>: Snnn, (PSnnn), Enn, nnn

After any system error. The message depends on the error and matches the error message shown to the user within Prism. The final four numbers are values of the SPIRES system variables $SNUM, $PSNUM, $ENUM, and $MNUM. ($PSNUM only appears when it has a value.) For instance:

(This example shows how useful $PSNUM can be: the explanation for S280 tells you to check the previous diagnostic for more information -- and that diagnostic is available through $PSNUM.)

HEL: (<context>) Term <user's term> (<help record key>)

A HEL log entry is generated for any successful or unsuccessful HELP command issued by a user. The "context" gives information about what the user was doing at the time of the HELP command. For an unsuccessful HELP command, the log entry reads "No help for <term>".

SEN and CAN

These entries occur when a SEND or CANCEL command is issued for an entry transaction. Both include the following information:

The value of "Cmd" will be either CREATE or GET. In addition, "Scrn" records how many screens were involved and how often they were seen (the two numbers would be equal if there were no reprompts). "Add", "Upd" and "Rem" tell how many actual add, update, and/or remove requests were performed in SPIRES during the transaction.

ADD: Record <record ID>

UPD: Record <record ID>

REM: Record <record ID>

These entries mark respectively the add, update or remove of a record in SPIRES.

SOR: <field-list> (Seq <element-list>)

Indicates the user is sorting the search result using the fields listed. (In parentheses the log lists the SPIRES elements corresponding to the fields.)

SET: <object-type> (CPU=__,I/O=__,Sec=__)

UPD: Record <key>

The SET log entry records resources used in a SETUP transaction. "object-type" indicates what type of SETUP was done: SEARCH, SORT, REPORT, TASK, FIELD, PRISM. The UPD entry shows the key of the definition record (e.g., the Personal Report definition) that was updated (not applicable for SETUP SORT or SETUP PRISM).

XST: <object-type> (CPU=__,I/O=__,Sec=__)

UPD: Record <key>

The XST log entry records resources used in an XSETUP transaction. "object-type" indicates what type of XSETUP was done: PROFILE, FORMS, REPORTS, etc. The UPD entry shows the key of the record (e.g., the Prism Profile) that was updated.

PRI: what,WHEN=n,CPU=__,Min=__,I/O=__,Lines=n,

 

TO=[dest|FORSYTHE|ATTACHED],OPT='options'

MAI: what,WHEN=n,CPU=__,Min=__,I/O=__,Lines=n, TO=address,OPT='options'

SAV: what,WHEN=n,CPU=__,Min=__,I/O=__,Lines=n, TO=filename,OPT='options'

Indicates a PRINT (or MAIL or SAVE) request from the Prism PRINT screen. "What" is either "REPORT", a display-name or a help record. (The log will go on to name the report or display but not the help record.) WHEN values correspond to the print options screen: 1=now, 2=overnight, 3=non-peak.

Entries for elapsed time

The log entries for SEL, BEG, END, PAU, CLR, SEA, SEN, SOR, PRI, MAI, and SAV include an indication of the CPU time, I/O, and elapsed time used for the commands. The elapsed time portion of the entry is labeled either "Min= " or "Sec= " depending on the unit of measurement used.

22.2  Writing Commands to the Log

PERFORM PRISM LOG

The PERFORM PRISM LOG command causes an additional entry to be written to the Prism log for your application, besides the normal entries logging your end-users' sessions. It can help you preserve more complete information and/or error diagnostics on Prism transactions than standard logging provides.

You do not need to write special log entries for most Prism transactions. PERFORM PRISM LOG is for special cases -- it might be useful, for instance, in a Prism application performing a behind-the-scenes transaction in a SPIRES file that is not installed in Prism.

The syntax for PERFORM PRISM LOG is:

The MESSAGE (or MSG) option causes Prism to write the text you specify into the log. For instance, after a successfully added record behind the scenes:

The ERROR option causes the specified text to be written to the log, but in addition Prism appends the current values of the SPIRES variables $SNUM, $ENUM, and $MNUM to the log entry. For instance:

Prism treats error entries created with PERFORM PRISM LOG the same way that it treats error entries that it logs on its own -- for instance, they cause an error notification to be sent to the application's contact account.

23  Appendix: Change Control Procedures

Prism system installation is phased to ensure that all new features have been thoroughly tested before they are made available to production applications. The Prism change control procedures closely parallel those used for installing changes in SPIRES.

The purpose of change control

The point of the change control procedures is to protect your application from unexpected changes in the way Prism operates; and to provide a clear-cut method for you to test new Prism features without jeopardizing your production application.

The Prism interface will always operate in several different "versions". The thoroughly tested "Production" version is changed only for emergency bug fixes, during the period between new Prism releases. Other versions, such as "Test", may be used to test how new Prism features will affect your application.

Versions of Prism

Here are the versions of Prism, listed in order from the newest and least tested to the oldest system.

Each of these versions are described further in the upcoming paragraphs.

Accessing versions of Prism

The PRISM command takes you to the production version of Prism. To access other versions, add the version to the PRISM command, in parentheses:

The "version" can be PRODUCTION, TEST, PREPRODUCTION, or OLD, and all these values can be shortened to a single character except PREPRODUCTION, which requires 3 characters.

23.1  The Different Versions of Prism

Here is detailed information about each version. Once again, the versions are listed in order from the most recent to the oldest.

Development

The Development version is where Prism changes are first introduced for internal testing by SDC staff.

In function Prism(D) corresponds to the the GQ.TES system in SPIRES and, in fact, runs in GQ.TES SPIRES so that problems at both the SPIRES level and the Prism level can be investigated. Unlike later versions of Prism, Development is not separately "linked". (A "linked" program runs in an unchanging copy of SPIRES, whereas GQ.TES is updated and enhanced daily.) This could conceivably lead to memory management problems for long sessions that select different files. Development is rebuilt as often there are new changes ready for others to see, so it could conceivably change on a daily basis, as we install enhancements.

Test

The Test version is built as often as needed (in some cases as often as once a week) from the Development version described above. It will be a separately linked processor, running in a stable version of SPIRES -- usually production SPIRES, but occasionally GG.TES SPIRES when new SPIRES features are needed. The Test version of Prism should always be stable enough for applications developers to use for their own testing, or to take advantage of bug fixes and new features. The Test version should not be used for production applications or in critical situations. Thus Prism end-users should never be directed to use PRISM(T) for their work.

As with the GG.TES version of SPIRES, you should exercise this system as much as you can in order to make sure the version is stable before it is shifted to Pre-production and Production.

Preprod

At least one week (and usually two weeks) before any new release of a production version of Prism, the existing, problem-free Test system is frozen and made available in a Preproduction version. Like the GQ.PRD version of SPIRES created before a new SPIRES release, Preproduction Prism should be used for critical applications testing prior to a new Prism. After the testing period, which usually lasts two weeks, the Preproduction version becomes the new Production version of Prism and the previous Production version is stored elsewhere as a backup system, as described further below.

Note that the Preproduction version is only available during the period just before a new Production Prism, unlike the other versions listed here, which are available on an ongoing basis.

At the same time that the Preproduction version of Prism is installed, a notice will be sent out to anyone responsible for a critical application. (A "critical" application is any application that members of the Stanford community depend upon to get their work done.) It's important that developers responsible for critical applications test any new Prism features thoroughly before this version of Prism becomes Production. In fact, every Prism developer is urged to test this version as thoroughly as possible, within its short window of availability.

Production

The Production version of Prism is simply the Preproduction version upgraded to Production status after the critical application testing period. Since it will have passed through all the stages of testing described above, it should be extremely stable -- so this is the version in which production Prism applications should run. All the same people who received notice of a new Preproduction system will likewise receive notice of the new Production version.

Emergency Changes

Despite rigorous testing, in rare cases a problem may escape detection before it has entered the Production version. Emergency fixes will be dealt with as they arise, and in extreme cases will be applied directly to the Production version; less critical fixes will be moved rapidly through the development/test/production cycle. Anyone on the preceding notifications list would also be notified of emergency changes.

Old version of Prism

Each time a new Production version is released, the previous Production version is renamed, and made available as the OLD version of Prism. You may never need the Old version at all, but in special situations it can be used to diagnose the history of a problem with a Production application; it can also serve as a backup system if something goes wrong with the current Production Prism. As the previous Production Prism migrates to become the Old version, the previous Old version will be discarded.

24  Appendix: Categories of Files in Prism

ADD PROFILE prompts you for the category or categories appropriate for your Prism application, and MOD PROFILE lets you change these categories if you want. Below are the categories currently in use at Stanford, along with brief descriptions. Your application will appear on the SELECT menu under the category or categories you name. You may list your file in several categories, if appropriate.

 FINANCIAL              Files relating to finance and accounting
 STUDENT/ACADEMIC       Student and academic records
 PERSONNEL              Personnel information
 FACILITIES             Physical facilities
 MAIL/COMMUNICATION     Mail and communications
 ONLINE FORMS           Applications that create and route forms
 MISCELLANEOUS          Files not fitting in the other categories
 APPLICATION DEV.       Files to help Prism application developers

These explanations are available within Prism Profile as well, when you type HELP CATEGORIES.

An additional category, CLASS APPLICATIONS, includes applications sponsored by the CLASS program (Cooperative for Linked Administrative Systems at Stanford). You must contact Data and Technology Resources staff to have an application designated as a CLASS application.

25  Appendix: University IDs, PINs, Electronic Signatures

This chapter covers several topics related to identifying users of your application and looking up and validating names:

 - An overview of  how  University  IDs  and  PINs  are  used  in  online  systems.   [See  25.1.]
 - A simple technique to create a standard identification screen (with  PERFORM  PRISM  PROMPT
 NAME PIN).  [See 25.3.1.]
 - How to identify users if you create a custom  identification  screen  (with  PERFORM  PRISM
 LOOKUP  NAME  and  PERFORM  PRISM  PROMPT  PIN).   [See  25.3.2,  25.3.3.]
 - Specific coding recommendations and sample protocol code  for  applications  using  PERFORM
 PRISM  LOOKUP  NAME,  including ways to ensure that your user identification protocol steps
 will work reliably when executed as part of a Prism task.  [See 25.4.]
 - How to look up information associated with a University ID, using system variables such  as
 $UNIVID  or  $UNIVNAME  or  using  the $LOOKSYS function to look in the University ID file.
 [See 25.5.]
 - Proxy identification and work groups (applicable to forms routing applications).   [See  25.6.]
 - Temporary IDs -- how they differ from regular IDs and what your application needs  to  know
 about them.  [See 25.7.]
 - What to know about users who enter Prism without having a Forsythe computer account.   [See
 25.8.]

Identifying Users and Looking Up Names in the University ID File

IDs and PINs

People affiliated with Stanford are assigned 8-character Stanford ID numbers. These numbers are printed on staff and student ID cards. As the need arises, a person may also be assigned a PIN (Personal Identification Number). Authorized staff in Human Resources and the Data Center inform people (staff and faculty) of their initial PIN assignment and advise the recipients to choose a new PIN known only to themselves before the ID and PIN is used for the first time. Anyone can change their PIN by using the MOD PIN entry form in the Personal Profile file in Prism.

PINs for students are assigned by the Registrar's Office. Students use ID/PIN identification in Axess, which is a student information system available through Folio. Students (and others) may use the SET PIN command in Folio in order to change their PIN.

University ID numbers, while unique to an individual, are not considered private numbers. PINs are, by University policy, supposed to be confidential and known only to the ID holder. See Administrative Guide Memos #36 and #64. (PINs are encrypted and stored separately from the University ID database.) The combination of an ID and its associated PIN constitutes a secure and authorized identification of a person. In the context of a Prism transaction involving University forms, when a person identifies himself by ID and PIN, this constitutes an "electronic signature".

25.1  How Are IDs and PINs Used in Stanford Computer Systems?

Here are some examples of how IDs and PINs are used in computer systems at Stanford.

Forms routing applications

In Prism, IDs and PINs were first used in applications whose purpose is to create transactions based on University forms and requiring signature approval (purchase requisitions, journal entries, personnel actions, etc.). "Forms routing" applications make use of a Prism facility for creating a routing list for an electronic form transaction and routing it for electronic signature.

[The specialized tools for building routing applications are described in a separate manual called How to Install a Routing Application in Prism.]

Forms routing applications usually require ID/PIN identification of the originator (creator) of a form transaction.

When names are entered on the routing list for a forms transaction, Prism verifies that each name matches a University ID in the database, and also that the ID has a PIN. If necessary, "name resolution" occurs -- that is, if several names associated with University IDs can be construed to match the name given by the form originator, he must choose the right one. [See 25.2 for details of the name matching process.] Prism stores the routing list as a list of IDs. Your application can look at the routing list and check an authority file or do other data integrity checks to make sure that the form is routed to the right person.

People approving forms transactions must give their ID and PIN in order to affix their electronic signature to the transaction. Forms approval is done in the Forms Action file in Prism.

Verifying Stanford affiliation

Your application may wish to look up names either to identify the current user, or to verify that a name entered by the current user as a data element in the transaction is for a valid Stanford affiliate.

There are a couple of variations:

 - You can prompt the user for his name or University ID and  then  his  PIN.   This  securely
 identifies the current user of your application.
 - You can look up a name to see if it can be matched with  a  currently  active  ID,  without
 prompting  for  PIN.  This  is appropriate when you're asking a user for a name not his own
 that needs to be validated. Or if you don't want to require people to have  a  PIN  to  use
 your  application,  you could prompt for the user's own name, validate it, but skip the PIN
 prompt.

Note that if you skip the PIN prompt, there is nothing to prevent someone from typing the name of any Stanford affiliate and claiming to be that person.

 - You can specify certain segments of the University ID database for the name lookup  --  IDs
 that  have PINs (and are thus eligible to have forms routed to them), temporary IDs, or IDs
 for work groups.  [See 25.7 for an explanation  of  temporary  IDs,  25.6   for  information  about  work  groups,  25.8.]

University IDs for Access to Your Application

You may control access to components of your application (indexes, reports, entry forms, displays, reporting fields) by means of University IDs, if you wish. And you may use IDs to control who can select your file in Prism. [See 4.1.2a.] This is an alternative to using Spires accounts (which may change over time for any given individual) to control access.

To do this, you must create a SPIRES access list containing University IDs. [See 4.] or [EXPLAIN ACCESS LISTS, FOR SUBFILE SELECTION.] Then, in the places in Prism Profile where you are asked for accounts or access lists, you may name this ID-based access list. In order for this to work, you must identify the user of your application by University ID (that is, $UNIVID must be set).

25.2  Name Matching Details

This section explains how Prism does name matching when it looks up names in University ID file. This applies to identification processes that you might build into your Prism application with commands such as PERFORM PRISM PROMPT NAME or PERFORM PRISM LOOKUP NAME. It also applies to name lookups on the routing screen, and name lookups during identification processes in EMS (when forms are signed via EMS).

SPIRES name matching

Prism's name matching is based on the normal SPIRES personal name algorithm, with a few variations. The flexibility that SPIRES' name matching offers (which was originally designed for bibliographic information retrieval applications) is in retrieving names that MIGHT be the one you are looking for. The method for accomplishing this is that forenames in search values are compared to forenames in the index. They are counted as a match if they match through the length of the shorter string. The surnames have to match exactly, unless explicit truncation via # is allowed. (EXPLAIN PERSONAL NAME for more details.)

For example:

      you enter                 matches on
      ---------                 ----------
      philip roth               philip roth
                                philip g roth
                                g philip roth
                                p m roth
                                timothy p roth
                                phil george roth
                                philippa ann roth

How is Prism different?

Prism introduces the concept of "weak match" and "strong match" of names.

A strong match is either:

 - An exact match between the search value and the index value (for forenames)
 - Search value is a substring of the index value (for forenames)

For example, GREG SMITH is a strong match to GREG SMITH and GREGORY SMITH.

A weak match is counted when:

 - The index value is a substring of the search value (GREG to G, PAULA to PAUL)

For example, GREG SMITH is a weak match to G SMITH, PETER G SMITH, etc. PAULA is a weak match to PAUL and P. GREGORY is a weak match to GREG and G.

There are two behaviors involving weak and strong matches:

Single weak match

a) Single weak match verification (introduced around December 1990)

When Prism finds only a single "weak match" to the name entered, it presents a box asking you to verify that the name found is the one intended. For example:

    Enter your Name or University ID: jimmie_sinclair____________

   *--------------------------------------------------------------------*
   | JIMMIE SINCLAIR was not found in the directory of University IDs.  |
   | The following is a close match:                                    |
   |                                                                    |
   |    Sinclair, J L (Lynne Sinclair, Data Center)                     |
   |                                                                    |
   | Is this the one you want?                                          |
   |                                                                    |
   |                       f4=No f5=Yes                                 |
   *--------------------------------------------------------------------*

Single strong match

b) Single strong match takes precedence (introduced June 1993)

The problem that this tries to solve is a situation where there is an exact match between a search value and an index value, but also one or more weak matches. In this case, Prism presented a name resolution menu that to the casual observer doesn't make much sense. For example:

   *--------------------------------------------------------------------*
   | There are 2 names like BOB PHILLIPS.                               |
   |                                                                    |
   | _ <-- Choose a name by entering a number from the list below.      |
   |      1. Phillips, Robert W (Bob Phillips, Data Center)             |
   |      2. Phillips, Susan B (Networking/Communication Sys)           |
   |                          f5=OK                       f9=Cancel Box |
   *--------------------------------------------------------------------*

The new behavior added in June 1993 is that if there is a single strong match, plus one or more weak matches, the strong match will take precedence and no name resolution menu will be presented. In the example above, if "Bob Phillips" is entered, it will match exactly on name #1 above and you will not get that menu.

Here are some other examples of name resolution menus that will no longer be presented under this new rule.

   There are 3 names like ANNE HARRINGTON.
     1. Harrington, Barbara A
     2. Harrington, Frances A (Anne Harrington, Business Info Sys
     3. Harrington, Melissa Ann (Student)

        now:  ANNE HARRINGTON matches exactly with #2

   ....................................................................
   There are 2 names like PAULA SCHARTZ.
     1. Schwartz, Edward Paul (Student)
     2. Schwartz, Paula M (ps, Business Info Sys Applications)

        now: PAULA is weak match to PAUL; the strong match to PAULA is used.

In summary, name resolution menus are presented in these cases:

 - there are multiple strong matches (with or without weak matches)
 - there are multiple weak matches

but name resolution menus are not presented if:

 - there is a single strong match and single/multiple weak match(es)
 - there is a single  weak  match  (but  you  get  "weak  match  verification"  box)

Multiple forenames

If multiple forenames are in the search value, there must be multiple names in the index value, in the same order, in order to match at all. (This is parallel to the SPIRES name searching rules.) Each forename is evaluated separately to determine whether there is a strong or weak match. Any strong match in the forenames will cause the name as a whole to be considered a strong match.

Examples of name resolution menus

Some examples of cases where you do still get name resolution menus:

   There are 3 names like ANN HARRINGTON.
     1. Harrington, Barbara A
     2. Harrington, Frances A (Anne Harrington, Business Info Sys
     3. Harrington, Melissa Ann (Student)

        (ANN is a strong match to both ANN and ANNE.)

   ....................................................................
   There are 3 names like GREG SMITH.
     1. Smith, Gregory M (Greg Smith, Data Center)
     2. Smith, Gregory Robert
     3. Smith, Peter G (Psychology)

        (GREG is strong match to both GREGORYs, even though there's
         an exact match in #1.)

   ....................................................................
   There are 4 names like B PHILLIPS.
     1. Phillips, Barbara Yvonne
     2. Phillips, Cindy Belle
     3. Phillips, Robert W (Bob Phillips, Data Center)
     4. Phillips, Susan B (Networking/Communication Sys)

        (B is a stong match to BARBARA, BELLE, BOB, and B.)

25.3  Techniques for Identifying Your Current Application User Securely

To identify a person securely, your application prompts the user to enter his name or Stanford ID number and then to enter his PIN (Personal Identification Number). When a name is entered, your application instructs Prism to search the database of University IDs. If multiple names are found that match the name given by the user, he is prompted to choose the right name. When the PIN is entered, Prism verifies that the PIN typed by the user matches the encrypted PIN stored for that ID.

The following PERFORM PRISM commands help you determine a person's University ID and to prompt for and validate a PIN:

 - PERFORM PRISM PROMPT NAME, PIN: This command creates a standard screen prompting for a name
 and PIN, without your having to write a SPIRES format.  You may also omit  the  PIN  prompt
 from  the  standard identification screen, if it is sufficient for your application to look
 up a name in the University ID file.
 - PERFORM PRISM LOOKUP NAME: This command looks up a name  in  the  University  ID  database.
 Options  on  the  command  let you include name resolution in the process or determine what
 types of IDs are looked up (for example, all active IDs or just IDs that have been assigned
 PINs).
 - PERFORM PRISM PROMPT PIN: This command prompts for the user's PIN, once an  ID  lookup  has
 been successful.
 - PERFORM PRISM LOOKUP PROXY: Used in forms  routing  applications,  this  command  lets  you
 determine  whether one person has been authorized to sign forms or take action on behalf of
 another.  [See 25.6 for an explanation.]

There are two methods to do this user identification:

 - The simplest is to use PERFORM PRISM PROMPT NAME, PIN to invoke the  standard  identification
 screen,  either  when  your file is first selected, or perhaps when a report or entry form is
 chosen.
 - Alternatively, you can create your own screen, on which you ask for  the  user's  name.  Then
 your  protocol  code can use PERFORM PRISM LOOKUP NAME to match the name with a valid ID, and
 then PERFORM PRISM PROMPT PIN to prompt for the PIN.

25.3.1  Using the PERFORM PRISM PROMPT NAME Screen

Here is an example of the identification process. These two screens are generated by the PERFORM PRISM PROMPT NAME, PIN command:

NSI Gr.Appl                                                  10/17/91 16:41
Personal Identification
---------------------------------------------------------------------------

                     Enter your Name or University ID:

                     Lindsey_Clayton__________________

Type: OK to continue file selection.       CANCEL to cancel file selection.
      UNDO to discard changes to page.
YOUR RESPONSE:
f1=Help                         f5=OK         f7=Undo f8=Cancel

Prism prompts a name in the entry field, based on either the WYLBUR account name or if present, the current value of $UNIVNAME.

After an OK command, the PIN prompt occurs in a box overlaid on top of the main screen:

NSI Gr.Appl                                                  10/17/91 16:41
Personal Identification
---------------------------------------------------------------------------

                     Enter your Name or University ID:

                     Lindsey_Clayton__________________

      *---------------------------------------------------------------*
      | (Lindsey Clayton) Enter your PIN: *********                   |
      *---------------------------------------------------------------*

-Enter your PIN above, then type OK below to continue
Type OK below to validate your PIN.
Type CANCEL to cancel file selection.
YOUR RESPONSE:
f1=Help                         f5=OK                 f8=Cancel

The protocol

This simple protocol will provide this identification screen at the time your file is selected:

 * FILE

 declare noparms

 ++identify
   perform prism prompt name, pin tempok
   return

The DECLARE NOPARMS statement tells Prism that there are no variables to be stored for use in Prism tasks. (Without a DECLARE statement of some form, the SETUP TASK command could not be used in the application.) [See 10.8.]

The TEMPOK option allows people with temporary IDs to identify themselves. [See 25.7.]

Installing the protocol step

The only other step required is to specify in XSETUP PROFILE that you have a processing step at file-select time:

Enter 'Yes' to see screens to add, modify, or delete processing steps.
 - when the subfile is selected or cleared: Yes

Then, enter the step id (corresponding to the proc label in the protocol):

Processing steps for when file is selected:

 STEP#    STEP ID           TYPE   TITLE/COMMENT
     1    IDENTIFY_           P    Identification______
     2    ________            _    ____________________
     3    ________            _    ____________________

(To install this identification parm screen when a report or entry form is selected, put the PERFORM PRISM command in a REPORT/report-name or FORM/form-name protocol and install the processing step in XSETUP REPORT or XSETUP FORM.)

Standard Identification Screen Without the PIN Prompt

You can use PERFORM PRISM PROMPT NAME without the PIN prompt (i.e. without the PIN option on the command) in order to invoke the standard identification screen for the purposes of looking up the name in the University ID file only. In this case, Prism will look up the name and prompt the user if multiple matches are found, but no PIN prompt will follow. The only way the user can proceed from this screen is to enter or choose a name found in the University ID file.

Note that this interaction without the PIN prompt does not securely identify the user, since all that's needed to get past the screen is to know the name of someone in Stanford's University ID file.

Complete Syntax of PERFORM PRISM PROMPT NAME

Syntax

  PERFORM PRISM PROMPT NAME [PIN]
                            [PROXY]
                            [PREVIOUS = 'command']
                            [ID = screen-id]
                            [TITLE = 'screen title']
                            [TEMPOK]
                            [TEXT = 'text']
                            [SEARCH = 'population, population, ...']

Variables Set After PERFORM PRISM PROMPT NAME

With PIN option

When PERFORM PRISM PROMPT NAME, PIN is successful, Prism sets the variable $UNIVID to the University ID of the currently logged-on user, where you can access it if needed. The user's full name, phone number, and electronic mail address are returned in the variables $UNIVNAME, $UNIVPHONE, and $UNIVEMAIL, respectively.

Without PIN option

If the PIN prompt is not used, none of the identification variables $UNIVID, $UNIVNAME, $UNIVPHONE, $UNIVEMAIL are set, cleared, or changed.

The $PARM variable will contain the University ID and name, concatenated with a slash, as below:

  01234567/John Smith

  T0000123/Mary Brown        (a temporary ID)

  STORES/University Stores   (a work group)

The $STATUS variable may contain the following values if the name entered is not unique or not found in the University ID file.

  $STATUS value    Explanation
  -------------    ------------------------------------------
  'NOTFOUND'       The name or ID entered was not found
                   in the directory.

  'MULTIPLE'       The value was not unique (and name
                   resolution did not occur). This would
                   happen if the user issues the CANCEL BOX
                   command from the name-resolution box
                   without making a selection.

Proxy

If the PROXY option (and the PIN option) is used, then the $PROXYID variable is set to the University ID of the person for whom the logged-on user is acting, and $PROXYNAME, $PROXYPHONE, and $PROXYEMAIL contain the person's name, phone number, and email address. [See 25.6 for more about proxy identification.]

25.3.2  Custom Identification Screens

Using PERFORM PRISM LOOKUP NAME and PERFORM PRISM PROMPT PIN

You may need to create your own parm screen on which you prompt for a person's name and also for other information needed for your application. In this case, you can write format frames as usual for the parm screen and then use the PERFORM PRISM LOOKUP NAME and PERFORM PRISM PROMPT PIN commands in the protocol associated with that parm screen.

PERFORM PRISM LOOKUP NAME looks up an input string that you provide (either a name or an ID) and verifies that the value is found in the University ID directory.

Details of the syntax are below. See also the later section that has a few examples of protocol code for user identification and name lookups. [See 25.4.]

Syntax of PERFORM PRISM LOOKUP NAME

Syntax

  PERFORM PRISM LOOKUP NAME = 'input string'
                       [RESOLVE]
                       [SEARCH = 'population, population, ...']
                       [TEMPOK]
                       [UNIVID]
                       [PROXYID]
                       [GROUPS]

NAME = 'input string'

The value to be looked up must be either a name or a University ID.

RESOLVE

Although RESOLVE is optional, it's recommended that you include it. RESOLVE tells Prism that if multiple matches are found in the University ID directory for the input string, the user should be prompted to select a specific name from a menu of choices.

If you use RESOLVE, it's also recommended that you use the UNIVID option (see explanation below).

SEARCH = 'population ...'

By default (i.e. if you omit the SEARCH option) Prism searches all active IDs that have PINs (excluding temporary IDs).

Instead, you may specify explicit segments of the University ID population that should be searched. Possible populations are:

Note that name lookups from the routing screen happen within the SIGNERS population. Name lookups from the standard identification screen generated by PERFORM PRISM PROMPT NAME, PIN happen within the PINS population (unless the SEARCH option is used to specify otherwise).

SEARCH=TEMPS is used by Prism

The SEARCH=TEMPS option was implemented for Prism's own use in allowing access to Prism services by temporary employees, and it's unlikely that you would need to use the SEARCH=TEMPS option in your own application code.

Temporary employees are instructed to type "temp" as their name when identifying themselves on Prism screens. In your LOOKUP NAME command, if "temp" is the string being looked up, Prism intercepts the lookup and branches to a routine that prompts additional input fields to identify a person with a temporary ID.

TEMPOK

The TEMPOK option is a "switch" that instructs Prism to take this special action when the name "temp" is encountered in a LOOKUP NAME command. Your code doesn't have to do anything special -- it just has to tell Prism that it's ok to do so. In the absence of a TEMPOK option, the string "temp" in your LOOKUP will produce a message telling the user that the file is not available for temporary employees.

This switch was implemented so that an application can explicitly allow or disallow access by temporary employees. The intent is that temps should be excluded only rarely, but the switch is a safeguard in case your application is not prepared to deal with the form of IDs assigned to temporary employees (IDs that begin with a "T" instead of being all numeric).

GROUPS Option

The GROUPS option (PERFORM PRISM LOOKUP NAME ... GROUPS) tells Prism to search among work group names as well as the default ID population (or the ID population you specify with the SEARCH option). [See 25.6 for a definition of a work group.] The GROUPS option is used in routing applications, in particular when you want to provide an "Acting for" field on your identification screen, for the user to indicate that he is working on behalf of another person or as part of a work group.

Summary of ID searches

Here is a graphic representation of the different populations of the University ID file that you may search with PERFORM PRISM LOOKUP NAME:

        normal, active IDs
     ------------------------------      ----------    ---------------
    | ACTIVES                      |    |          |  | inactive IDs  |
    |   (all active IDs)           |    | TEMPS    |  |               |
    |                              |    | (active) |  |               |
    |   ------------------------   |    |          |   ---------------
    |  | PINS                   |  |     ----------
    |  |   (IDs with PINs)      |  |
    |  |                        |  |
    |  |   ------------------   |  |          ---------------
    |  |  | SIGNERS          |  |  |         | GROUPS        |
    |  |  |   (enabled for   |  |  |         | (work groups) |
    |  |  |    routing)      |  |  |          ---------------
    |  |   ------------------   |  |
    |  |                        |  |            GROUPS option simply
    |   ------------------------   |             adds "work groups"
     ------------------------------              to whatever
                                                 population is
                                                 being searched

 TEMPS have IDs that start with "T".

 Although inactive IDs are not searchable with LOOKUP NAME,
 you may still use $LOOKSYS for those IDs to retrieve the
 associated name, etc.

UNIVID Option

The UNIVID option causes name resolution to be bypassed if the current value of $UNIVNAME matches exactly the input string being passed in the NAME parm of the PERFORM PRISM LOOKUP NAME command being executed. If you use the RESOLVE option, it's recommended that you also use UNIVID.

UNIVID is useful when you are using LOOKUP NAME to identify the current user, but is not appropriate when you are using it to look up names otherwise (e.g. to validate a name listed by the current user when you ask for a supervisor's or approver's name).

Bypass extra name resolutions

The UNIVID option makes your LOOKUP NAME command a little smarter, in that it eliminates unnecessary name resolution screens during the second and subsequent times that a person identifies himself in a Prism session. When a person first identifies himself, $UNIVID, $UNIVNAME, etc. are set, and those variables retain their values even if the user moves to a different file. On the second identification, it is highly likely that the name the user types will match the $UNIVNAME value set earlier, and that it is safe to assume it is the same person identifying himself. Name resolution menus are bypassed, and you can proceed to prompt for the PIN. (You still should prompt for a PIN, by policy, even if you make these assumptions about how the user's name and $UNIVNAME compare.)

Prompt $UNIVNAME in your name field

One thing that helps this work smoothly is if you prompt a value in your "Name" field on your identification screen, when possible. The first time identification happens, you can prompt a name from the user's WYLBUR account name. The next times, when $UNIVNAME is set, you can prompt the $UNIVNAME value. If you do this, the user can simply issue the OK command to proceed, without having to type a name.

If you prompt the WYLBUR account name, be sure to parse the value to omit extraneous strings like phone numbers. Later in this chapter, in the sample protocol code, there is some code that you can use to accomplish this. [See 25.4.]

Note that Prism uses these techniques -- bypassing name resolution the second time around, and prompting $UNIVNAME or the WYLBUR account name -- when you use PERFORM PRISM PROMPT NAME (the standard identification screen). In this sense, the UNIVID option makes LOOKUP NAME behave like PROMPT NAME.

Name resolution in Prism tasks

Another reason to use the UNIVID option is to make your protocol code work reliably when it is executed in the batch, as part of a Prism task definition. Name resolution screens cannot happen in a task, since screen prompts don't happen when your protocol runs in the batch. [See 10.8 for more about protocol code used in tasks.]

PROXYID Option

PROXYID is similar to UNIVID, except it applies to name lookups for "proxy" identification. [See 25.6.]

The PROXYID option causes name resolution to be bypassed if the current value of $PROXYNAME matches exactly the input string being passed in the NAME parm of the PERFORM PRISM LOOKUP NAME command being executed. As for UNIVID, it's recommended that if you use the RESOLVE option during a name lookup for proxy identification, you should use the PROXYID option too.

Variables Set By PERFORM PRISM LOOKUP NAME

$STATUS

After PERFORM PRISM LOOKUP NAME, the $STATUS variable is set to null if a name was found successfully. There are two ways this can happen: if the lookup finds a single match in the directory; or, if multiple names were found and the user chose a single name during name resolution. (Name resolution occurs if you included the RESOLVE option on PERFORM PRISM LOOKUP NAME.)

$PARM

In both cases, the $PARM variable contains the University ID and name, concatenated with a slash, as below:

  01234567/John Smith

  T0000123/Mary Brown        (a temporary ID)

  STORES/University Stores   (a work group)

If the command fails, $STATUS can tell you why:

  $STATUS value    Explanation
  -------------    -----------------------------------
  'NOTFOUND'       The name or ID in the input string
                   was not found in the directory

  'MULTIPLE'       The value was not unique (and name
                   resolution did not occur)

A $STATUS value of MULTIPLE occurs in two situations. The first case is when the PERFORM PRISM LOOKUP NAME command does not include a RESOLVE option and the input string is not unique. The second situation is when the user issues the CANCEL BOX command from the name-resolution box without making a selection.

$UNIVID is not set

Note that PERFORM PRISM LOOKUP NAME does not set the $UNIVID or $PROXYID variable. $UNIVID (and associated variables) is not set until a successful PIN prompt occurs.

25.3.3  Asking for the PIN: PERFORM PRISM PROMPT PIN

After prompting the current user for his name or University ID and looking it up with PERFORM PRISM LOOKUP NAME, use PERFORM PRISM PROMPT PIN to prompt him for his PIN.

Syntax

  PERFORM PRISM PROMPT PIN [UNIVID=n] [PREVIOUS='command']

Variables Set After PERFORM PRISM PROMPT PIN

Immediately before the PIN prompt, Prism clears any previously set $UNIVID or $PROXYID (and associated variables like $UNIVNAME). Then, if the PIN prompt is successful, $UNIVID is set to the University ID of the currently logged-on user. The user's full name, phone number, and electronic mail address are returned in the variables $UNIVNAME, $UNIVPHONE, and $UNIVEMAIL, respectively.

$PROXY variables

Note that if you are doing proxy identification, you should prompt for the PIN before doing the PERFORM PRISM LOOKUP PROXY. Procedurally, the reasoning for this is that you should identify the user before displaying possibly confidential information such as who can sign for whom. Technically, the reason is that although PERFORM PRISM LOOKUP PROXY sets $PROXYID $PROXYNAME, $PROXYPHONE, and $PROXYEMAIL, if you subsequently prompt for a PIN, the $PROXY variables will be cleared by Prism. [See 25.6 for more about proxy identification.]

Details of PIN Prompting

During PIN prompting, Prism protects any unprotected field on your screen and uses the lower part of the data area of the screen for the PIN prompt. The end-user has four chances to enter the valid PIN; after three invalid attempts, Prism issues a warning, and after a fourth invalid attempt terminates the Prism session. There's also an automatic timeout after two minutes of inactivity during PIN prompting.

25.4  Sample Protocol Code for Identifying Users

These examples illustrate how to use PERFORM PRISM LOOKUP NAME and PERFORM PRISM PROMPT PIN (along with PERFORM PRISM SCREEN and a format) to identify users of your application on an identification screen of your own design.

Remember that if you can use Prism's standard identification screen, generated by PERFORM PRISM PROMPT NAME, PIN, your protocol can be much simpler. [See 25.3.1.]

Example 1

This is a fairly simple identification protocol. Its features are:

 - A value is prompted for the user in the name field on the identification screen.
 - Name resolution is supported, and the DECLARE PARMS statement and the UNIVID  option  on  the
 LOOKUP will let the protocol work in Prism tasks.
 - The application allows access by temporary IDs (the TEMPOK option).
 - It uses the same MN and NN error codes  and  messages  as  Prism's  identification  routines.

Error handling in this example is done in the protocol with the PERFORM PRISM SET ERROR command, for the cases where PERFORM PRISM LOOKUP NAME returns a $STATUS of NOTFOUND or MULTIPLE. [See 12a.13.] Alternatively, the format could set the appropriate error codes and reprompt the screen.

This protocol also uses PERFORM PRISM COPY to refresh the value in the name field with the official name found by the lookup. This requires a zone definition in the format (see sample below). [See 12a.3, 12a.14.]

Format to go with the protocol

Here is a simple format frame that will work with this protocol; use it as a pattern for your code.

Example 2

The second example is an extension of the first one. This example is for an identification screen that prompts for proxy identification as well as for the current user's name. That is, it has an "Acting for" field as well as a "Name" field. It uses two LOOKUP NAME commands to verify the two names, and a LOOKUP PROXY command to verify that a proper proxy relationship exists between the two.

Other Coding Recommendations

If you store IDs in your database, store them as strings, not as integers. While many IDs are numeric, IDs for temporary employees start with "T" and IDs for work groups may be alphanumeric.

You do not need to do any re-validation of IDs that Prism returns to you; you should rely on Prism and SPIRES to ensure the integrity of the IDs.

Remember that your identification screens are parm screens that need a DECLARE PARMS or DECLARE NOPARMS statement in order to make the SETUP TASK command available in your application. [See 10.8 for more information about this.]

25.5  Looking Up Information Associated with a University ID

When a user identifies himself by giving a valid PIN, $UNIVID and its associated variables are set. These variables apply to the currently-identified user.

$UNIVID -- string, 8 characters

Variables for current user

This SPIRES variable holds the University ID of an end-user after prompting for University ID and PIN has been successful.

$UNIVNAME -- string, 64 characters

After successful prompting of University ID and PIN, $UNIVNAME contains the name (in firstname-lastname order, e.g., "John Smith") corresponding to the $UNIVID that has been established. The name comes from the "signs-as" element in the directory, if one exists -- if not, the "official" name is used.

$UNIVEMAIL -- string, 64 characters

The electronic mail address (as recorded in Personal Profile) for the holder of the current $UNIVID

$UNIVPHONE -- string, 36 characters

The phone number of the holder of the current $UNIVID.

$PROXYID -- string, 8 to 16 characters

Variables for current proxy

If the user indicated that he is "Acting for" another person or for a work group, then $PROXYID contains the University ID of the person or work group for whom the current user is acting. IDs for work groups may be up to 16 characters long.

The standard identification screen generated by PERFORM PRISM PROMPT NAME has an "Acting for" field if the PROXY option is used on the PERFORM command. When you have your own custom identification screen, $PROXYID is set after a successful PIN prompt and a successful PERFORM PRISM LOOKUP PROXY command.

$PROXYNAME -- string, 64 characters

If $PROXYID is set, then $PROXYNAME holds the name associated with the proxy ID.

$PROXYEMAIL -- string, 64 characters

The electronic mail address for the holder of the current $PROXYID.

$PROXYPHONE -- string, 36 characters

The phone number of the holder of the current $PROXYID.

Using $LOOKSYS

Looking up ID information

If your application stores University IDs as data elements for a transaction, you may wish to look up the current name, phone number, etc. for that ID for use later in displays or input screens. The $LOOKSYS function and system proc let you lookup into the University ID directory for the following information. $LOOKSYS is also used in routing applications to look up information about routed forms, such as the routing status or the list of approvers.

For more details about these elements, or if you have other lookup needs, contact a Prism/SPIRES consultant in the Data Center.

Example: Looking Up the Name for an ID

Syntax of $LOOKSYS

Here is the syntax of $LOOKSYS as a function:

  $LOOKSYS(filecode,record-key,elem-name)

and as a system proc:

  $LOOKSYS(filecode,elem-name,err)

The "filecode" is always UNIVID when looking up University ID information. The "record-key" is the ID you're looking up.

Example

For example, to look up the name associated with ID 09999798:

++GetName
Let Name = $LOOKSYS(UNIVID,09999798,USE.NAME)

25.6  Proxy Identification and Work Groups

This section is applicable to identification screens in routing applications. For additional information about work groups and proxy identification, see the "Routing Applications" manual.

Proxy identification

Prism's forms routing system allows one person to sign or act for another person, if the proper authorization exists. Prism's Personal Profile file lets one person "delegate" permission to another person to sign or take action on his behalf (the DELEGATE entry form). The "delegatee" is said to be the "proxy" for the "delegator".

     Mary Smith says ...          <-- the delegator

     John Doe can act for me      <-- the delegatee (the proxy)

On your identification screens, you may wish to let the person not only identify who he is, but also to say who he is acting for. Your application must then look up both names and also verify that the "delegation" has been recorded in the Personal Profile file.

In addition, for transactions involving expenditure of funds, signature authorization is recorded in the SUFIN Authority file. Your application would presumably include SUFIN Authority checks at some point in the transaction in this case.

Work groups

In addition, Prism lets system administrators define "work groups". A work group is a defined group of people who are all equally empowered to take action on a form.

The "Acting for" Field on Identification Screens

On identification screens, the "Acting for" field is where a person says that he is acting as a proxy for someone else, or that he is acting as a representative of a work group.

On the standard screen

If you use the standard identification screen produced by PERFORM PRISM PROMPT NAME, you can include the PROXY option to create an "Acting for" field and to cause Prism to check the two names to see that the proper relationship exists. (Note that Prism does not check SUFIN Authority; your application is responsible for that check, if applicable.)

NSI Gr.Appl                                                  10/17/91 16:41
Personal Identification
---------------------------------------------------------------------------

                     Enter your Name or University ID:

                     Lindsey_Clayton__________________

               Acting for: ________________________________

Type: OK to continue file selection.       CANCEL to cancel file selection.
      UNDO to discard changes to page.
YOUR RESPONSE:
f1=Help                         f5=OK         f7=Undo f8=Cancel

PERFORM PRISM LOOKUP PROXY

On custom screens

If you have created a custom identification screen, include an "Acting for" field, use PERFORM PRISM LOOKUP NAME to look up both IDs, prompt for the PIN, and then use the PERFORM PRISM LOOKUP PROXY command to check for a valid proxy relationship.

The protocol examples in an earlier section illustrated the use of this command in context. [See 25.4.] Here is the formal syntax of PERFORM PRISM LOOKUP PROXY.

Syntax

  PERFORM PRISM LOOKUP PROXY id1 FOR id2 [FORM = file-id/form-name]

The FORM option is required in virtually all cases, although technically it is optional. There are instances when Prism's general routing code uses the command without a FORM option, but applications would generally always be looking up delegation for their specific form.

$STATUS and $PROXYID

After PERFORM PRISM LOOKUP PROXY, the $STATUS variable will be either null (a valid proxy relationship exists) or NOPROXY (id1 is not authorized to act for id2). If a valid proxy relationship exists, the $PROXYID, $PROXYNAME, $PROXYPHONE, and $PROXYEMAIL variables will be set.

Note that you should prompt for the PIN for the current user before the LOOKUP PROXY command, because Prism clears any existing $UNIVID and $PROXYID setting immediately prior to the PIN prompt.

25.7  Temporary IDs: Application Considerations

A distinct identification process has been devised for use by temporary employees who need to work in Prism applications that prompt for ID and PIN. This applies to people hired from temporary agencies like Adia (not to official University employees hired for a fixed term and paid through payroll).

A department administrator can register the temporary employee by using the TEMP ACCESS entry form in Prism's Personal Profile file. The registration form asks for deparmental affiliation, name, email address for mail related to Prism forms, an expiration date for the registration, and a "confirmation code". This confirmation code is requested when the temporary employee identifies himself, as a minimal level of validation. The code is not confidential -- the supervisor and employee both know it.

How temps are identified

Temporary employees are instructed to enter the word "temp" when asked for their name on identification screens. If the application has enabled access by temporary employees, Prism recognizes the string "temp" and branches to a routine that prompts additional input fields to identify the temporary employee:

Faculty/Staff Directory                                       10/22/91 09:02

----------------------------------------------------------------------------

                      Enter your Name or University ID:

                      temp_____________________________

                Acting for: ________________________________

Type: OK to continue file selection.       CANCEL to cancel file selection.
      UNDO to discard changes to page.
YOUR RESPONSE:
f1=Help                         f5=OK         f7=Undo f8=Cancel
Faculty/Staff Directory                                       10/22/91 09:02

----------------------------------------------------------------------------
  *------------------------------------------------------------------------*
  | By typing TEMP, you have indicated that you are working as a temporary |
  | employee at Stanford, and have been registered for on-line work by     |
  | your supervisor.  To continue your work in this file, enter your name  |
  | and, when requested, the confirmation code your supervisor gave you.   |
  |                                                                        |
  |    Enter your name: _________________________________                  |
  |                                                                        |
  |                                                                        |
  |                                                                        |
  |                            f5=OK                         f9=Cancel Box |
  *------------------------------------------------------------------------*

Type: OK to continue file selection.       CANCEL to cancel file selection.
      UNDO to discard changes to page.
YOUR RESPONSE:
f1=Help                         f5=OK         f7=Undo f8=Cancel
Faculty/Staff Directory                                       10/22/91 09:02

----------------------------------------------------------------------------
  *------------------------------------------------------------------------*
  | By typing TEMP, you have indicated that you are working as a temporary |
  | employee at Stanford, and have been registered for on-line work by     |
  | your supervisor.  To continue your work in this file, enter your name  |
  | and, when requested, the confirmation code your supervisor gave you.   |
  |                                                                        |
  |    Enter your name: Maryann_Doe______________________                  |
  |                                                                        |
  |    Enter your confirmation code: ( ************ )                      |
  |                                                                        |
  |                  f4=Previous f5=OK                       f9=Cancel Box |
  *------------------------------------------------------------------------*

Type: OK to continue file selection.        UNDO to discard changes to page.
      PREVIOUS to return to prior page.     CANCEL to cancel file selection.
YOUR RESPONSE:
f1=Help                         f5=OK         f7=Undo f8=Cancel

Applications must allow temp access

It is the TEMPOK option on either the PERFORM PRISM PROMPT NAME or PERFORM PRISM LOOKUP NAME command that allows temps to identify themselves in your application as illustrated here. In the absence of TEMPOK, if "temp" is encountered, Prism gives a message indicating that the file does not allow access by temporary employees. [See 25.3.1, 25.3.2.]

IDs start with T

When temps are registered, they are assigned IDs that begin with "T". When Prism looks up a temp's name, it looks only in the set of IDs for temporary employees. When the name and confirmation code are validated, $UNIVID and associated variables are set, just as in the identification process for regular Stanford affiliates.

If you store IDs in transaction records, you can use $LOOKSYS to look up the associated name, department, etc. just as for regular IDs, even if the temp's registration has expired.

If a temporary employee works for several different departments or at different periods, separate registrations would be created. So any single person hired as a temp might have several temporary IDs assigned. Transactions created under the different IDs are not linked in any way.

People with temporary IDs can originate forms in routing applications, but they cannot be entered on routing lists. Prism edits the routing list to ensure this. Temps also cannot approve a form while creating it; the "Approve" field next to the originator's name is disabled for temps.

25.8  General Access to Prism: Application Considerations

In late 1991 a new facility was added to allow people to use Prism without having a Forsythe computer account. The purpose was to accommodate people needing to do Prism work on a very occasional, infrequent basis, who otherwise would not need a Forsythe account. For example, it might be used by a research assistant who occasionally needs to create a purchase requisition or a faculty member who would like to change his Faculty/Staff Directory entry. This method of access is not intended as a substitute for having a Forsythe account, but simply to open up access to Forsythe services to a wider community, where appropriate.

General access to Prism

The term being used for this way of using Prism is "general access to Prism" -- this term is used in a few places in system messages and help screens.

The way it works is that a person may connect to Forsythe, and then type "prism" at the "Account?" prompt. The person is then prompted for his name or University ID and his PIN.

$UNIVID is set

A person entering Prism this way is identified by University ID, and the $UNIVID variable (and its associated variables) are set.

HQ.PRM session

The Prism session runs on account HQ.PRM (a multiple logon account). Prism sets the account name for that session to the name in the $UNIVNAME variable. So this name would appear in SUGGEST messages or log entries or error reports originating from this session.

Some commands not available

When a person uses Prism this way, all public files are available, of course. However, some Prism commands are not available: SETUP REPORT, SETUP SEARCH, SETUP TASK, TASK, PAUSE, LOCK. These users are not allowed to create Personal Reports, Personal Searches, or tasks because Prism currently stores those definitions under WYLBUR account. (If Prism makes a transition to storing them under University ID instead of WYLBUR account, then those commands could be made available under general access.)

On the PRINT screen, HQ.PRM sessions are forbidden to print to Forsythe or to save files on Forsythe. They can download to a micro file, however. One minor consideration to keep in mind is that if your public application offers reports that generate output directly to Forsythe (e.g. a report to make mailing labels) these users might not know how to find the output.

Some "public" reports, entry forms, or even whole applications, may make little sense when used via general access to Prism, e.g. Screen Definer. However, currently the only way to exclude general access users is to check specifically for HQ.PRM sessions and take special action (such as blocking selection of a report or entry form).


INDEX


$ALIAS CONTROL WORD IN HELP RECORDS   6.3.1
$AREANAME VARIABLE   12a.14.1
$AREANAME VARIABLE, WITH $ZONEDEF FUNCTION   12a.3
$BIND CONTROL WORD IN HELP RECORDS   6.3.6
$BOX CONTROL WORD IN HELP RECORDS   6.3.2
$CATEGORY CONTROL WORD IN HELP RECORDS   6.3.5
$COMMENT CONTROL WORD IN HELP RECORDS   6.3.7
$CONTEXT CONTROL WORD IN HELP RECORDS   6.3.10
$CRTCNT VARIABLE   12.1.6
$DEBUG VARIABLE   17.1
$DEST VARIABLE   17.2
$DESTINATION VARIABLE   17.2
$DESTVAL VARIABLE   17.2
$DISNUM VARIABLE   17.10a
$ELEMINFO CONTROL WORD IN HELP RECORDS   6.3.4
$EVENTZONE VARIABLE   12a.4a
                      17.2a
                      12a.2
$FIELDVAL VARIABLE   17.2b
                     12a.10
                     17.7
$FIELDVAL VARIABLE, CURSOR POSITIONING   12a.17
$FORMNAME VARIABLE   17.3
$FRAME CONTROL WORD IN HELP RECORDS   6.3.9
$GETAREA FUNCTION, AND PRISM ZONES   12a.3
$GETAREA FUNCTION, TO READ PRISM SCREENS   12a.14.1
$HEADER CONTROL WORD IN HELP RECORDS   6.3.11
$INDEXINFO CONTROL WORD IN HELP RECORDS   6.3.4
$LASTCMD VARIABLE   17.4
                    13.2
$LINE CONTROL WORD IN HELP RECORDS   6.3.3
$LOOKSYS FUNCTION, UNIVERSITY ID ELEMENTS   25.5
$LOOKSYS PROC, UNIVERSITY ID ELEMENTS   25.5
$MAINCMD VARIABLE   17.4
$MSGLINE VARIABLE   17.5
                    9.2.5
$NEXTCMD VARIABLE   17.6
$PARM VARIABLE   25.3.2
                 17.2b
                 12a.11
                 12a.10
                 17.2
                 13.2
$PARM VARIABLE IN PRISM APPLICATIONS   17.7
$PRELOAD CONTROL WORD FOR PRISM PROTOCOLS   9.2.2
$PRISM CONTROL WORD IN HELP RECORDS   6.4.2
$PRISMID VARIABLE   17.8
$PRISMINFO FUNCTION   7.6
$PROXYEMAIL VARIABLE   25.3.3
                       25.3.1
                       25.5
$PROXYID VARIABLE   25.3.3
                    25.3.1
                    25.5
                    25.6
$PROXYNAME VARIABLE   25.3.3
                      25.3.2
                      25.3.1
                      25.5
$PROXYPHONE VARIABLE   25.3.3
                       25.3.1
                       25.5
$PUTAREA FUNCTION, TO WRITE TO PRISM SCREENS   12a.14.1
$RECID VARIABLE   17.10
$RECNO IN DISPLAY FORMATS   3.3
                            3.2
$REPORT FOR PRISM REPORTS   10.5
$REPTNAME VARIABLE   17.11
$SCRNAREA VARIABLE   12a.14.1
                     12a.3
$SCRNAREA VARIABLE, AND TASKS   12a.14
$SCRNSTAT VARIABLE   17.12
$SETAREA FUNCTION, AND PRISM SCREENS   12a.14.1
$SRCHTYPE VARIABLE   17.13
                     13.2
$SRCHVAL VARIABLE   17.14
                    13.2
$STATUS VARIABLE   25.3.2
                   17.15
                   12a.1
                   25.6
$SUBJECT CONTROL WORD IN HELP RECORDS   6.3.7
$UNIVEMAIL VARIABLE   25.3.3
                      25.3.1
                      25.5
$UNIVID VARIABLE   25.3.3
                   25.3.2
                   25.3.1
                   25.5
$UNIVID VARIABLE, AND DECLARE PARMS   10.8
$UNIVNAME VARIABLE   25.3.3
                     25.3.2
                     25.3.1
                     25.5
$UNIVPHONE VARIABLE   25.3.3
                      25.3.1
                      25.5
$XBIND CONTROL WORD IN HELP RECORDS   6.3.6
$XFILE CONTROL WORD IN HELP RECORDS   6.3.8
$ZONEDEF FUNCTION   12a.14
                    12a.3
ACCESS LISTS   8.4
               4
ACCESS LISTS, IN PRISM   4
ACCESS LISTS, WITH UNIVERSITY IDS   4.1.2a
                                    25.1
ACCOUNTS STATEMENT IN SPIRES   2.1
ACCOUNTS STATEMENT IN SPIRES, FOR SECONDARY FILES   16
ACCOUNTS, ADDING TO YOUR PROFILE   8.4
ACCOUNTS, SPECIFIED AS AN ACCESS LIST   4
ACTING FOR, ON IDENTIFICATION SCREENS   25.3.1
                                        25.6
ACTIVE FILE, AND PROCESSING STEPS   10.3
                                    9.2.4
ACTIVE FILE, AND SPIRES COMMAND   7.5
ADD LINK FORM   16.1
ADD PROFILE FORM   4.1
ADDITIONAL DISPLAYS   3.4
ADDITIONAL DISPLAYS, IN PLACE OF REPORTS   10
ALSO PROCESSING   13.2
ASSIGN CURRENT RECORD   12.1.2
ASSIGN SEARCH FOR PRISM   13.2.2
AUTOMATIC CONTROL OF ENTRY   12.1.1
                             11.4
AUTOMATIC SEARCHES   13.1
BINDING HELP RECORDS   6.3.6
BOXES   12a.1
BOXES, CODING   12a.17
BOXES, CODING CHECKLIST   12a.7
BOXES, DECLARING EVENTS   12a.2
BOXES, DEFINING ZONES   12a.3
BOXES, DEFINITION OF TYPES   12a.5
BOXES, EXAMPLES   12a.5.1
BOXES, FUNCTION KEYS TO ENABLE   12a.6.2
BOXES, FUNCTION KEYS, SPACE REQUIRED   12a.9
BOXES, GUIDELINES   12a.6
BOXES, GUIDELINES FOR FIELD LABELS   12a.6.1
BOXES, GUIDELINES FOR USE   12a.6.3
BOXES, PROTOCOL CODE   12a.8
BOXES, SIZE AND PLACEMENT   12a.9
BOXES, TIPS AND TRICKS   12a.17
BRIEF DISPLAY   3.2
BUTTONS   12a.4
BUTTONS, CONDITIONAL   12a.4
BUTTONS, ENABLING   12a.2
BUTTONS, GUIDELINES FOR LABELS   12a.6.1
BUTTONS, MULTIPLE OCCURRENCES   12a.4a
CANCEL COMMAND   12.1.3
CATEGORIES OF FILES   24
CATEGORIES OF HELP RECORDS   6.3.5
CHANGE CONTROL PROCEDURES   23
CHECK FIELDS REPORT   8.3
                      5.5
CHECK INDEX REPORT   8.3
CHECKLIST FOR PRISM APPLICATIONS, CODING BOXES   12a.7
CHECKLIST FOR PRISM APPLICATIONS, CONTROL WORDS FOR HELPS   6.3.13
CHECKLIST FOR PRISM APPLICATIONS, DEBUGGING COMMANDS   7.11
CHECKLIST FOR PRISM APPLICATIONS, HELP RECORDS   20
                                                 6.1
CHECKLIST FOR PRISM APPLICATIONS, PERFORM PRISM COMMANDS   18
CHECKLIST FOR PRISM APPLICATIONS, PROTOCOL NAMES   21
CHECKLIST FOR PRISM APPLICATIONS, VARIABLES   17
CHOICE BOXES   12a.17
               12a.5
CHOICE BOXES, CODING   12a.10
CHOICE BOXES, CODING CHECKLIST   12a.7
CHOICE BOXES, FIELD LABELS   12a.6.1
CHOICE BOXES, GUIDELINES   12a.6.3
CHOICE BOXES, PROTOCOL CODE   12a.8
                              12a.2
CHOICE LISTS   12a.10
CHOICES FUNCTION KEY   12a.10
                       12a.2
CHOOSE LISTS   12a.10
CLEAR DEBUG COMMAND   7.1
CLEAR ECHO COMMAND   7.3
CLEAR FTRACE COMMAND   7.4.3
CLEAR NOCOMPXEQ COMMAND   7.3
CLEAR PTRACE COMMAND   7.4.6
CLEAR STOP COMMAND   7.2
CLEAR STRACE COMMAND   7.4.2
CLEAR TLOG COMMAND   7.4.5
CLEAR TLOG DATA COMMAND   7.4.5
CLEAR TRACE COMMAND   7.4.1
CLEAR XTRACE COMMAND   7.4.4
CLOSING A RECORD IN CUSTOM DATA ENTRY   12.1.1
COLOR STANDARDS ON AN ENTRY FORM   11.3
COMPILED PROTOCOLS, AND SET ECHO   7.3
COMPILED PROTOCOLS, IN PRISM APPLICATIONS   9.2.3
CONFIRMATION SCREEN AFTER SEND   12.1.3
CONTEXT HELP   10.7
               9.1.1
               6.4.4
               6.4.3
               6.1
CONTEXT HELPS FOR PRISM SCREENS AND BOXES   20
CONTROL WORDS FOR HELP RECORDS, $ALIAS   6.3.1
CONTROL WORDS FOR HELP RECORDS, $BIND   6.3.6
CONTROL WORDS FOR HELP RECORDS, $BOX   6.3.2
CONTROL WORDS FOR HELP RECORDS, $CATEGORY   11.6
                                            10.7
                                            6.4.4
                                            6.4.3
                                            6.4.2
                                            6.3.5
CONTROL WORDS FOR HELP RECORDS, $COMMENT   6.3.7
CONTROL WORDS FOR HELP RECORDS, $CONTEXT   6.3.10
CONTROL WORDS FOR HELP RECORDS, $DEBUG   6.3.12
CONTROL WORDS FOR HELP RECORDS, $ELEMINFO   6.3.4
CONTROL WORDS FOR HELP RECORDS, $FRAME   6.3.9
CONTROL WORDS FOR HELP RECORDS, $HEADER   6.3.11
CONTROL WORDS FOR HELP RECORDS, $INDEXINFO   6.3.4
CONTROL WORDS FOR HELP RECORDS, $LINE   6.3.3
CONTROL WORDS FOR HELP RECORDS, $PAGE   6.3.12
                                        6.2.1
CONTROL WORDS FOR HELP RECORDS, $PRISM   6.3.12
                                         6.4.2
CONTROL WORDS FOR HELP RECORDS, $SUBJECT   6.3.7
CONTROL WORDS FOR HELP RECORDS, $XBIND   6.3.6
CONTROL WORDS FOR HELP RECORDS, $XFILE   8.6
                                         9.1.1
                                         6.4.3
                                         6.3.8
CONTROL WORDS FOR HELP RECORDS, CHECKLIST   6.3.13
COPYING TO AND FROM PRISM SCREENS, WITH FUNCTIONS   12a.14.1
COPYING TO AND FROM PRISM SCREENS, WITH PERFORM PRISM COPY   12a.14
CRT AREA   12a.3
CURRENT RECORD   12.2
                 12.1.2
CURSOR POSITION, CONTROLLING   12a.17
CURSOR POSITION, IN $FIELDVAL   12a.17
CURSOR POSITION, IN ZONES   12a.3
CUSTOM CONTROL OF DATA ENTRY   12.1
CUSTOM CONTROL OF DATA ENTRY, AND PROTOCOL CODE   12
CUSTOM CONTROL OF DATA ENTRY, COMPARED TO AUTOMATIC CONTROL   12
                                                              11.1
CUSTOM CONTROL OF DATA ENTRY, DERIVING NEW RECORDS   12.1.1
CUSTOM CONTROL OF DATA ENTRY, INSTALLATION   12
CUSTOM CONTROL OF DATA ENTRY, LINKING TO A SECOND FILE   12.1.4
CUSTOM CONTROL OF DATA ENTRY, PERFORM PRISM COMMANDS   12.1
CUSTOM CONTROL OF DATA ENTRY, POST-SEND CONFIRMATION SCREEN   12.1.3
CUSTOM CONTROL OF DATA ENTRY, SCREEN INVOCATION   12.1.3
CUSTOM CONTROL OF REPORTING, DISPATCHING OUTPUT   10.4
CUSTOM CONTROL OF SEARCHING, ZERO RESULTS   17.15
DATA ENTRY, AUTOMATIC CONTROL VS. CUSTOM CONTROL   12
                                                   11.1
DATA ENTRY, CONTEXT HELP   11.6
                           9.1.1
DATA ENTRY, DERIVING RECORDS   12.1.1
DATA ENTRY, ERROR HANDLING   12a.13
                             11.3.2a
                             11.3.2
DATA ENTRY, HELP RECORDS   11.6
DATA ENTRY, HIDDEN SEARCH   13.1
DATA ENTRY, MOD FORMS   11.5
DATA ENTRY, POST-SEND CONFIRMATION SCREEN   12.1.3
DATA ENTRY, PROCESSING STEPS   12
                               11.4
                               9
DATA ENTRY, RECORD LOCKING   12.2
DATA ENTRY, REMOVING RECORDS   12.1.5
                               11.3.4
DATA ENTRY, REVIEW AFTER SEND   12.2
                                11.3.1
DATA ENTRY, SPIRES FORMATS   11.3
DATA ENTRY, STANDARDS FOR DISPLAY ATTRIBUTES   11.3
DATA ENTRY, TRANSACTION GROUPS   12.2
DATA ENTRY, WRAPPING TEXT   11.3.3
DEBUGGING COMMANDS, CHECKLIST   7.11
DEBUGGING COMMANDS, CLEAR DEBUG   7.1
DEBUGGING COMMANDS, CLEAR ECHO   7.3
DEBUGGING COMMANDS, CLEAR FTRACE   7.4.3
DEBUGGING COMMANDS, CLEAR NOCOMPXEQ   7.3
DEBUGGING COMMANDS, CLEAR PTRACE   7.4.6
DEBUGGING COMMANDS, CLEAR STRACE   7.4.2
DEBUGGING COMMANDS, CLEAR TLOG   7.4.5
DEBUGGING COMMANDS, CLEAR TRACE   7.4.1
DEBUGGING COMMANDS, CLEAR XTRACE   7.4.4
DEBUGGING COMMANDS, DUMP SCREEN   7.9
DEBUGGING COMMANDS, EXPLAIN   7.1
DEBUGGING COMMANDS, FOR PERSONAL SEARCHES AND PERSONAL REPORTS   7.10
DEBUGGING COMMANDS, FOR TRACING   7.4
DEBUGGING COMMANDS, GRANT PRIVILEGES   7.4.7
DEBUGGING COMMANDS, SET COMPXEQ   7.3
DEBUGGING COMMANDS, SET DEBUG   7.1
DEBUGGING COMMANDS, SET ECHO   7.3
DEBUGGING COMMANDS, SET FTRACE   7.4.3
DEBUGGING COMMANDS, SET NOCOMPXEQ   7.3
DEBUGGING COMMANDS, SET NOECHO   7.3
DEBUGGING COMMANDS, SET PTRACE   7.4.6
DEBUGGING COMMANDS, SET STOP   7.2
DEBUGGING COMMANDS, SET STRACE   7.4.2
DEBUGGING COMMANDS, SET TLOG   7.4.5
DEBUGGING COMMANDS, SET TRACE   7.4.1
DEBUGGING COMMANDS, SET XTRACE   7.4.4
DEBUGGING COMMANDS, SHOW ELEMENTS/SHOW INDEXES   7.6
DEBUGGING COMMANDS, SHOW EVAL   7.1
DEBUGGING COMMANDS, SHOW FREECORE   7.6
DEBUGGING COMMANDS, SHOW HISTORY   7.6
DEBUGGING COMMANDS, SHOW LOG   7.6
DEBUGGING COMMANDS, SHOW SUBFILE ...   7.6
DEBUGGING COMMANDS, SHOW TLOG DATA   7.4.5
DEBUGGING COMMANDS, SHOW VARIABLES   7.6
DEBUGGING COMMANDS, SHOW VERSION   7.6
DEBUGGING COMMANDS, SPIRES   7.5
DEBUGGING COMMANDS, STATUS GRANT   7.4.7
DECLARE NOPARMS STATEMENT IN PRISM PROTOCOLS   10.8
DECLARE PARMS STATEMENT IN PRISM PROTOCOLS   10.8
DECLARE PRELOAD STATEMENT IN PRISM PROTOCOLS   9.2.2
DECLARE SCREEN IN PRISM PROTOCOLS   12a.2
DEFERRED PRINTING OF REPORTS   10.2
DERIVING NEW RECORDS FROM CURRENT ONES IN DATA ENTRY   12.1.1
DESTINATION FOR PRINT OUTPUT   17.2
DEVICE SERVICES   12a.14.1
                  12a.3
DISABLE A FILE FOR SELECTION   8.5
DISABLE A REPORT OR ENTRY FORM   8.5.1
DISABLING A PRISM APPLICATION   8.5
DISABLING FUNCTION KEYS   12a.16
DISPATCHING REPORT OUTPUT   10.4
                            10.2
DISPLAY ATTRIBUTE STANDARDS   11.3
DISPLAY ATTRIBUTES   12a.14
DISPLAY ATTRIBUTES, FOR TRIGGER FIELDS   12a.4
DISPLAY FORMAT   3.1
DISPLAYS, ADDITIONAL DISPLAYS   10
                                3.4
DISPLAYS, BRIEF DISPLAY   3.2
DISPLAYS, FOR REVIEW   11.3.1
DISPLAYS, FORMAT-NAME   3.1
DISPLAYS, FRAME-DIM   3.1
DISPLAYS, FULL DISPLAY   3.3
DISPLAYS, HELP RECORDS   6.4.4
DISPLAYS, INSTALLING   3.5
DISPLAYS, OVERFLOW   3.3
                     3.2
DOCUMENTATION   1
DUMP SCREEN   7.9
DYNAMIC ELEMENTS FOR REPORTING AND SORTING FIELDS   5.1
EDIT MASKS FOR REPORTING FIELDS   5.2
EFFICIENCY CONSIDERATIONS, CLEAR OPTION ON PERFORM PRISM UNLINK   12.1.4
EFFICIENCY CONSIDERATIONS, COMPILING PROTOCOLS   9.2.3
EFFICIENCY CONSIDERATIONS, IMMEDIATE INDEXING   2.2
EFFICIENCY CONSIDERATIONS, LOGGING   22
EFFICIENCY CONSIDERATIONS, PRELOADING CODE IN PROTOCOLS   9.2.2
EFFICIENCY CONSIDERATIONS, PROTOCOL PROCESSING STEPS   9.2
EFFICIENCY CONSIDERATIONS, SPIRES COMMANDS TO TRACK MEMORY USE   7.6
ELECTRONIC SIGNATURES, OVERVIEW   25.1
ELEMINFO (FROM SPIRES FILEDEF), FOR REPORTING FIELDS   5.4
                                                       5.2
ELEMINFO (FROM SPIRES FILEDEF), IN HELP RECORDS   6.3.4
ENABLING A PRISM APPLICATION AFTER DISABLE   8.5
ENABLING A REPORT OR ENTRY FORM AFTER DISABLE   8.5.1
ENABLING FUNCTION KEYS   12a.16
ENDDECLARE STATEMENT   9.2.2
ENDPROC PROCESSING   12.1.3
ENDPROC PROCESSING, DETAILS   12a.2
ENTRY FORMS (SEE ALSO DATA ENTRY)   11
ENTRY FORMS, DISABLING   8.5.1
ERROR CODES   12a.13
ERROR CODES FOR ENTRY FORMS   11.3.2a
ERROR CODES, EXPLANATIONS   9.1.1
ERROR HELP   9.1.1
ERROR SETTING IN PRISM APPLICATIONS   12a.13
ERRORS DURING INPUT   22.1
                      12.1.3
                      11.3.2
                      9.2.5
                      9.1.1
EVENTS   12a.1
EVENTS, DEFINING ZONES   12a.3
EVENTS, ERROR HANDLING   17.15
EVENTS, IN PRISM PROTOCOLS   12a.2
EVENTS, TIPS AND TRICKS   12a.17
EXPLAIN COMMAND   7.1
FIELDS FOR SORTING AND REPORTING   5
FIELDS FOR SORTING AND REPORTING, AND DYNAMIC ELEMENTS   5.1
FIELDS FOR SORTING AND REPORTING, EDIT MASKS   5.2
FIELDS FOR SORTING AND REPORTING, ELEMINFO   5.2
FIELDS FOR SORTING AND REPORTING, FILTERS   5.4
                                            5.3
                                            5
FIELDS FOR SORTING AND REPORTING, MOD FIELDS   5.4
FIELDS FOR SORTING AND REPORTING, REMOVING FIELDS   5.5
FILE ACCESS   4.1.2a
              8.4
              4
FILE ACCESS, DISABLING   8.5
FILE DEFINITION MODIFICATIONS   16
                                2.2
                                2.1
                                2
FILE NOT AVAILABLE MESSAGE   2.1
FILE PROFILE   1
FILE PROFILE, DEFINED   4
FILE PROFILE, MAXIMUM SIZE   4.2
FILE-ID, AND KEYS OF PROTOCOL RECORDS   9.2.1
FILE-ID, FOR A SECONDARY FILE   16
FILE-ID, IN $PRISMID VARIABLE   17.8
FILE-ID, IN SUBFILE SECTION   2.1
FILE-ID, IN THE DISPLAY FORMAT   3.1
FILE-ID, IN THE LOG   22.1
                      22
FILE-ID, INSTALLED IN ADD PROFILE   4.1
FILE-ID, NEEDED TO SELECT PRISM HELP   6.2.4
FILE-ID, NEEDED TO SELECT PRISM PROTO   9.2.1
FILTERS FOR REPORTING FIELDS   5.4
                               5.3
                               5
FLUSHDATA UPROC   3.3
FLUSHDATA, FOR FULL DISPLAYS   3.3
FLUSHDATA, FOR REPORTS   10.1
FORMAT, FOR DISPLAYS   3.1
FORMAT, FOR ENTRY FORMS   11.3.2a
                          11.3.2
                          11.3.1
                          11.3
FORMAT, FOR HELP TEXT   6.3.9
FORMAT, FOR REMOVE ENTRY FORMS   11.3.4
FORMAT, FOR REPORTS   10.5
                      10.1
FORMS FOR INSTALLING PRISM APPLICATIONS   8
FORMS FOR INSTALLING PRISM APPLICATIONS, ADD LINK   16.1
FORMS FOR INSTALLING PRISM APPLICATIONS, ADD PROFILE   4.1
FORMS FOR INSTALLING PRISM APPLICATIONS, MOD ACCESS   8.4
FORMS FOR INSTALLING PRISM APPLICATIONS, MOD DISPLAYS   3.5
FORMS FOR INSTALLING PRISM APPLICATIONS, MOD FIELDS   5.4
FORMS FOR INSTALLING PRISM APPLICATIONS, MOD FORMS   11.5
FORMS FOR INSTALLING PRISM APPLICATIONS, MOD FORMS, FOR CUSTOM DATA ENTRY   12
FORMS FOR INSTALLING PRISM APPLICATIONS, MOD INDEXES   8.2.1
FORMS FOR INSTALLING PRISM APPLICATIONS, MOD OPTIONS   14
FORMS FOR INSTALLING PRISM APPLICATIONS, MOD PROFILE   16.2
                                                       8.1
FORMS FOR INSTALLING PRISM APPLICATIONS, MOD REPORTS   10.6
FORMS FOR INSTALLING PRISM APPLICATIONS, REM PROFILE   8.6
                                                       16.2
FRAME-DIM IN DISPLAY FORMAT   3.1
FULL DISPLAY   3.3
FULL DISPLAY, FOR REVIEW   11.3.1
FUNCTION KEYS IN BOXES, RECOMMENDATIONS   12a.6.2
FUNCTION KEYS IN BOXES, SPACE REQUIRED   12a.9
FUNCTION KEYS, DISABLING OR ENABLING   12a.16
F2=*CHOICES   12a.10
              12a.2
GENERAL ACCESS TO PRISM   25.8
GENERATING REPORT OUTPUT   10.3
                           10.2
GRANT PRIVILEGES COMMAND   7.4.7
GROUPS OPTION ON PERFORM PRISM LOOKUP NAME   25.3.2
HEADERS DURING DISPLAY, BRIEF HEADERS   3.2
HEADERS DURING DISPLAY, FULL HEADERS   3.3
HELP LIST REPORT   8.3
                   6.1
HELP RECORDS, <DISPLAY-NAME> DISPLAY   6.4.4
HELP RECORDS, <FILE-NAME> FILE   6.4.2
HELP RECORDS, <FORM-NAME> FORM   11.6
HELP RECORDS, <INDEXTERM> INDEX   6.4.3
HELP RECORDS, <REPORT-NAME> REPORT   10.7
HELP RECORDS, ?DISPLAY/<DISPLAY-NAME>   6.4.4
HELP RECORDS, ?ERROR   9.1.1
HELP RECORDS, ?INPUT   9.1.1
HELP RECORDS, ?INTRO/FORM/<FORM-NAME>   11.6
HELP RECORDS, ?INTRO/REPORT/<REPORT-NAME>   10.7
HELP RECORDS, ?REPORT/<REPORT-NAME>   10.7
HELP RECORDS, ?WELCOME   6.4.1
HELP RECORDS, ALIASES   6.3.1
HELP RECORDS, ALTERNATE FILE-ID   4.1.2
                                  6.3.8
HELP RECORDS, CHECKLIST   20
                          6.1
HELP RECORDS, CONTEXT   6.1
HELP RECORDS, CONTROL WORDS   6.3.13
                              6.3
HELP RECORDS, ENHANCEMENTS IN 1988   6.6
HELP RECORDS, ERROR REPORTS   4.1.2
                              6.1
HELP RECORDS, FOR DISPLAYS   6.4.4
HELP RECORDS, FOR ENTRY FORMS   11.6
                                9.1.1
HELP RECORDS, FOR INPUT ERROR   9.1.1
HELP RECORDS, FOR REPORTS   10.7
HELP RECORDS, FOR SEARCH TYPES   6.4.3
HELP RECORDS, GENERAL FORMAT   6.2.1
HELP RECORDS, HELP LIST REPORT   6.1
HELP RECORDS, HELP TOPICS   6.3.5
HELP RECORDS, HOW TO CREATE AND INSTALL   6.2
HELP RECORDS, PRISM HELP SUBFILE   8.6
                                   6.2.4
HELP RECORDS, REQUIRED FOR BASIC APPLICATION   6.1
HELP RECORDS, SUPPLIED BY PRISM   6.1
HELP RECORDS, USING FORMATS   6.3.9
HELP RECORDS, WELCOME SCREEN   6.4.1
HIDDEN SEARCHES   13.1
HOLDATA UPROC   3.3
HOLDATA, FOR FULL DISPLAYS   3.3
HOLDATA, FOR REPORTS IN PRISM   10.1
HQ.PRM SESSIONS   25.8
IDENTIFICATION SCREENS   25.3
IDENTIFICATION SCREENS, SAMPLE PROTOCOLS   25.4
IMMEDIATE INDEXING   11.3.1
                     2.2
INDEX EXITS   13.2
INDEXES (SEE ALSO UNDER SEARCH TYPES)   2.2
INDEXINFO IN HELP RECORDS   6.3.4
INDIRECT SEARCH   2.2
LABEL STATEMENT IN PROTOCOL CODE   9.2.4
LABELS FOR BUTTONS   12a.6.1
LABELS FOR FIELDS WITH CHOICES   12a.6.1
LABELS FOR TRIGGER FIELDS   12a.6.1
LARGE PROFILES   4.2
LINKING TO A SECOND FILE   16
                           12.1.4
                           9.2.6
LOCKING RECORDS   12.2
LOGGING, FORMAT OF PRISM LOG EXPLAINED   22
LOGGING, PERFORM PRISM LOG   22.2
LOOKUP NAME   25.3.2
LOOKUP PROXY   25.6
MAXIMUM PROFILE SIZE   4.2
MESSAGE LEVELS IN PRISM   19
MESSAGE LEVELS IN PRISM, AND CLEAR DEBUG   7.1
MESSAGE LEVELS IN PRISM, AND SET DEBUG   7.8
MESSAGE LEVELS IN PRISM, DURING PROTOCOL EXECUTION   9.2.7
                                                     9.2.5
MESSAGES, CUSTOMIZING PRISM MESSAGES   17.5
                                       14
                                       12.1.3
MESSAGES, ERROR MESSAGES   17.15
                           22.1
                           9.2.5
                           9.1.1
MESSAGES, ERROR MESSAGES, AS THEY APPEAR IN THE LOG   22
MOD ACCESS FORM   8.4
MOD DISPLAYS FORM   3.5
MOD FIELDS FORM   5.4
MOD FORMS FORM   11.5
MOD FORMS FORM, FOR CUSTOM DATA ENTRY   12
MOD INDEXES FORM   8.2.1
MOD OPTIONS FORM   14
                   12.1.3
MOD PROFILE FORM   8.1
MOD PROFILE FORM, FOR SECONDARY FILES   16.2
MOD REPORTS FORM   10.6
MULTI-FILE ACTIVITY   16
                      12.1.4
MULTI-PAGE DISPLAYS OF A SINGLE RECORD   3.3
MULTI-PAGE DISPLAYS OF A SINGLE RECORD, IN REPORTING   10.1
MULTI-RECORD ENTRY FORMS   12
MULTI-RECORD ENTRY FORMS, AND LINKING TO A SECONDARY FILE   12.1.4
MULTI-RECORD ENTRY FORMS, AND PERFORM PRISM OPEN AND CLOSE   12.1.1
MULTI-RECORD ENTRY FORMS, AND RECORD LOCKING   12.2
MULTI-RECORD ENTRY FORMS, AND TRANSACTION GROUPS   12.2
MULTIPLE OCCURRENCES, OF ZONES   12a.4a
MULTIPLY-OCCURRING ZONES   12a.4a
NAME LOOKUP   25.3.2
NAME MATCHING DURING PRISM IDENTIFICATION   25.2
NAME RESOLUTION   25.3.2
NAME RESOLUTION DETAILS   25.2
NAME RESOLUTION, AND TASKS   10.8
NESTED BOXES   12a.6.3
NULL INPUT   11.3.2
OK COMMAND   12.1.3
             11.3.2
             11.3
OK COMMAND, OPTION ON PERFORM PRISM SCREEN   12.1.3
ON COMMAND STATEMENT IN PRISM PROTOCOLS   12a.2
ON EVENT STATEMENT IN PRISM PROTOCOLS   12a.2
OPENING A RECORD IN CUSTOM DATA ENTRY   12.1.1
OPTIONS TEXT, MODIFYING   14
                          12.1.3
OVERFLOW, FOR REVIEW COMMAND AFTER DATA ENTRY   11.3.1
OVERFLOW, IN PRISM REPORTS   10.1
OVERFLOW, IN THE BRIEF DISPLAY   3.2
OVERFLOW, IN THE FULL DISPLAY   3.3
OVERLAY OPTION, ON PERFORM PRISM SCREEN   12.1.6
PARM SCREENS   10.8
PARM SCREENS, FOR IDENTIFICATION   25.3
PATH PROCESSING   9.2.6
PAUSE FROM PRISM TO WYLBUR   12.1.8
PAUSE IN PRISM   12.1.9
PERFORM PRINT FOR PRISM PROTOCOLS   9.2.1
PERFORM PRISM ASSIGN CURRENT   12.1.2
PERFORM PRISM ASSIGN ENDROUTE   12.3
PERFORM PRISM ASSIGN ROUTE   12.3
PERFORM PRISM ASSIGN SEARCH   13.2.2
PERFORM PRISM CHOOSE   12a.10
PERFORM PRISM CLEAR SUBAREA   12a.9
PERFORM PRISM CLOSE   12.1.5
                      12.1.4
                      12.1.1
PERFORM PRISM COMMANDS (SUMMARY)   18
PERFORM PRISM COMMANDS FOR DATA ENTRY (SUMMARY)   12.1
PERFORM PRISM COMMANDS FOR ROUTING (SUMMARY)   12.3
PERFORM PRISM COPY   12a.14
                     12a.3
PERFORM PRISM DISABLE PFKEY   12a.16
PERFORM PRISM DISABLE SELECT   8.5
PERFORM PRISM ENABLE PFKEY   12a.16
PERFORM PRISM ENABLE SELECT   8.5
PERFORM PRISM GENERATE OVERLAY   12.1.6
PERFORM PRISM GET LOCAL   13.2.5
PERFORM PRISM HELP   6.8
PERFORM PRISM INPUT   12.1.7
PERFORM PRISM LINK   16.2
                     16
                     12.1.4
                     12.1.3
                     9.2.6
                     9.2.2
PERFORM PRISM LINK COMMAND   9.2.7
PERFORM PRISM LINK, AND $PRISMID VARIABLE   17.8
PERFORM PRISM LOG   22.2
PERFORM PRISM LOOKUP NAME   25.3.2
PERFORM PRISM LOOKUP NAME, SAMPLE PROTOCOLS   25.4
PERFORM PRISM LOOKUP PROXY   25.6
PERFORM PRISM LOOKUP PROXY, SAMPLE PROTOCOLS   25.4
PERFORM PRISM OPEN   12.1.5
                     12.1.4
                     12.1.1
PERFORM PRISM OUTPUT   12.1.7
PERFORM PRISM PAUSE   12.1.8
PERFORM PRISM PROMPT NAME PIN   25.3.1
PERFORM PRISM PROMPT PIN   25.3.3
PERFORM PRISM PROMPT PIN, SAMPLE PROTOCOLS   25.4
PERFORM PRISM PROMPT TEXT   12a.12
PERFORM PRISM PROMPT VALUE   12a.11
PERFORM PRISM REMOVE   12.1.5
                       12.1.1
PERFORM PRISM RESET UNDO   12a.15
PERFORM PRISM ROUTE   12.3
PERFORM PRISM SCREEN   12.1.3
                       12a.8
                       12a.2
PERFORM PRISM SEARCH   13.2.4
PERFORM PRISM SERVICE SUFIN GETAUTH   15
PERFORM PRISM SET ERROR   12a.13
PERFORM PRISM SET SEARCH   13.2.3
                           13.2
PERFORM PRISM SET SUBAREA   12a.9
PERFORM PRISM SUFIN AUTHORITY   15
PERFORM PRISM UNLINK   16.2
                       12.1.4
PERSONAL REPORTS DEBUGGING   7.10
PERSONAL SEARCHES DEBUGGING   7.10
PFORMAT COMMAND   9.2.1
PHRASE PROCESSING OF SEARCH VALUES   13.2.1
PIN PROMPTING   25.3.3
PINS, CUSTOM IDENTIFICATION SCREENS   25.3.2
PINS, OVERVIEW   25.1
PINS, STANDARD IDENTIFICATION SCREEN   25.3.1
POST-SEARCH PROTOCOL STEPS   13.3
PRE-SEARCH PROTOCOL STEPS   13.3
PRELOADING CODE IN PRISM PROTOCOLS   9.2.2
PREVIOUS COMMAND   12.1.3
                   11.4
                   11.3.2
                   11.3
PREVIOUS COMMAND, OPTION ON PERFORM PRISM SCREEN   12.1.3
PRIMARY VS. SECONDARY FILES   16
PRINT OPTIONS FOR REPORTING   17.2
PRINTER NAMES   17.2
PRINTING REPORTS, PROCESSING STEPS   10.2
PRISM DEFINITIONS SUBFILE   7.10
PRISM HELP SUBFILE   8.6
                     6.2.4
PRISM PROFILE FILE   8
PRISM PROFILE FILE, ADD LINK   16.1
PRISM PROFILE FILE, ADD PROFILE   4.1
PRISM PROFILE FILE, EXPLAINED   4
                                2.1
PRISM PROFILE FILE, MOD ACCESS   8.4
PRISM PROFILE FILE, MOD DISPLAYS   3.5
PRISM PROFILE FILE, MOD FIELDS   5.4
PRISM PROFILE FILE, MOD FORMS   12
                                11.5
PRISM PROFILE FILE, MOD INDEXES   8.2.1
PRISM PROFILE FILE, MOD OPTIONS   14
PRISM PROFILE FILE, MOD PROFILE   12
                                  8.1
PRISM PROFILE FILE, MOD REPORTS   10.6
PRISM PROFILE FILE, REM PROFILE   8.6
                                  12
PRISM PROTO SUBFILE   21
                      8.6
                      9.2.1
                      9.2
PRISM SCREEN PROCESSING   12a.1
PRISM-ID (SEE ALSO FILE-ID)   2.1
PROCESSING STEPS, AFTER DISPLAY REPORT COMMAND   10.2
PROCESSING STEPS, AFTER PRINT COMMAND   10.2
PROCESSING STEPS, AND THE ACTIVE FILE   10.3
                                        9.2.4
PROCESSING STEPS, AT FILE SELECTION   3.6
PROCESSING STEPS, EXPLAINED   9
PROCESSING STEPS, FOR AUTOMATIC CONTROL OF DATA ENTRY   11.4
PROCESSING STEPS, FOR CUSTOM CONTROL OF DATA ENTRY   12
PROCESSING STEPS, FOR REPORTING   10.2
PROCESSING STEPS, FOR SEARCHING   13
PROCESSING STEPS, NAMING CONVENTIONS   11.3
                                       9.2
                                       9.1
PROCS IN PROTOCOL CODE, INSTALLING PROCS IN PRISM PROFILE   4.1
PROFILE, MAXIMUM SIZE   4.2
PROGRAM = PRISM   16
                  12.1.4
                  2.1
PROMPT NAME   25.3.1
PROMPT PIN   25.3.3
PROTOCOL PROCESSING STEP   9.2
PROTOCOL PROCESSING STEP, CHECKLIST OF NAMES   21
PROTOCOL PROCESSING STEP, COMPILING   9.2.3
PROTOCOL PROCESSING STEP, DEBUGGING WITH SET ECHO   7.3
PROTOCOL PROCESSING STEP, DEBUGGING WITH SET STOP   7.2
PROTOCOL PROCESSING STEP, ERROR HANDLING   9.2.5
PROTOCOL PROCESSING STEP, FOR CUSTOM CONTROL OF DATA ENTRY   12
PROTOCOL PROCESSING STEP, FOR CUSTOM SEARCHING   2.4
PROTOCOL PROCESSING STEP, FOR SEARCHING   13
PROTOCOL PROCESSING STEP, INSTALLING IN PRISM PROFILE   9.3
                                                        4.1
PROTOCOL PROCESSING STEP, INSTALLING IN PRISM PROTO   9.2.1
PROTOCOL PROCESSING STEP, LINKING TO SECONDARY FILE   9.2.6
PROTOCOL PROCESSING STEP, PRELOADING CODE   9.2.2
PROTOCOL PROCESSING STEP, PRINTING   9.2.1
PROTOCOL PROCESSING STEP, PROCS AND STEP IDS   9.2.4
PROTOCOL PROCESSING STEP, REMOVING   9.3
PROTOCOL PROCESSING STEP, RESTRICTIONS   19
                                         9.2.7
PROTOCOL PROCESSING STEP, TO CREATE A REPORT   10.5
PROTOCOL PROCESSING STEP, TO DISPATCH PRINTED OUTPUT   10.4
PROTOCOL PROCESSING STEPS, EXPLAINED   9
PROXY IDENTIFICATION   25.6
PROXY IDENTIFICATION, ON STANDARD IDENTIFICATION SCREEN   25.3.1
PUBLISH COMMAND   1
PUTDATA = 4, FOR REPORTS IN PRISM   10.1
PUTDATA = 4, FOR REVIEW COMMAND AFTER DATA ENTRY   11.3.1
QUALIFYING SEARCH TYPES   13.4.3
RECORD LOCKING   12.2
REM PROFILE FORM   8.6
REM PROFILE FORM, FOR SECONDARY FILES   16.2
REMOVING A PRISM APPLICATION   8.6
REMOVING A REPORT   10.6
REMOVING A SEARCH TYPE   8.2.1
REMOVING A SECONDARY FILE PROFILE RECORD   16.2
REMOVING AN ENTRY FORM   11.5
REMOVING FIELDS FOR SORTING OR REPORTING   5.5
REMOVING HELP RECORDS   8.6
                        6.2.4
REMOVING PROCESSING STEPS   9.3
REMOVING PROTOCOL RECORDS   8.6
REMOVING RECORDS IN DATA ENTRY   12.1.5
                                 11.3.4
                                 11.3
REMOVING SPECIAL CONDITIONS   9.3
REPARSE SEARCH REQUEST   13.2.3
                         2.4
REPEAT STATUS IN PRISM SCREEN PROCESSING   17.15
REPORT DEFINER   10.5
REPORTING (PERSONAL REPORTING), INSTALLING FIELDS FOR REPORTING   5
REPORTING (PRE-DEFINED REPORTS), $REPORT   10.5
REPORTING (PRE-DEFINED REPORTS), DECLARE PARMS   10.8
REPORTING (PRE-DEFINED REPORTS), DISABLING A REPORT   8.5.1
REPORTING (PRE-DEFINED REPORTS), DISPATCHING OUTPUT   17.2
                                                      10.4
REPORTING (PRE-DEFINED REPORTS), DISPLAYING REPORTS   17.2
                                                      10.2
                                                      10.1
REPORTING (PRE-DEFINED REPORTS), GENERATING OUTPUT   10.3
REPORTING (PRE-DEFINED REPORTS), HELP RECORDS   10.7
REPORTING (PRE-DEFINED REPORTS), HIDDEN SEARCH   13.1
REPORTING (PRE-DEFINED REPORTS), INSTALLING REPORTS   10.6
REPORTING (PRE-DEFINED REPORTS), NOT DERIVED FROM DATA BASE   10.2
REPORTING (PRE-DEFINED REPORTS), OVERFLOW   10.1
REPORTING (PRE-DEFINED REPORTS), PROCESSING STEPS   10.2
REPORTING (PRE-DEFINED REPORTS), SEQUENCING   10.1
REPORTING (PRE-DEFINED REPORTS), TURNING OFF END-USER SORTING   10.1
REPORTING (PRE-DEFINED REPORTS), USING ADDITIONAL DISPLAYS INSTEAD   10
                                                                      3.4
REPORTING, DISPATCHING OUTPUT   10.2
REPORTING, GENERATING OUTPUT   10.2
REPROMPT STATUS IN PRISM SCREEN PROCESSING   17.15
REPROMPTING THE END-USER   17.15
                           12.1.3
                           11.3.2
REPROMPTING THE END-USER, AFTER AN INPUT ERROR   9.1.1
REPROMPTING THE END-USER, HOW TO AVOID AFTER NULL INPUT   11.3.2
REPROMPTING THE END-USER, IN AN INPUT FORMAT   12.1.3
REPROMPTING THE END-USER, WITH PERFORM PRISM SCREEN   12.1.3
RESET UNDO COMMAND   12a.15
RESOLUTION BOXES   12a.5
RESOLUTION BOXES, CODING CHECKLIST   12a.7
RESOLUTION BOXES, CODING DETAILS   12a.2
RESOLUTION BOXES, GUIDELINES   12a.6.3
RESTART STATUS IN PRISM SCREEN PROCESSING   17.15
REVIEW COMMAND   12.2
                 11.3.1
REVIEW COMMAND, WITH REMOVED RECORDS   12.1.5
ROUTING APPLICATIONS   12.3
                       1
SCREEN DEFINER, AND COLOR STANDARDS   11.3
SCREEN DEFINER, CUSTOMIZING ITS OUTPUT   11.3
SCREEN DEFINER, FOR ENTRY FORMS   11.2
SCREEN PROCESSING EXPLANATION   12a.1
SCREEN PROCESSING STEPS   9.1
SCREEN PROCESSING STEPS, AT FILE-SELECTION   6.4.1
SCREEN PROCESSING STEPS, AT FORM-SELECTION   11.6
SCREEN PROCESSING STEPS, AT REPORT-SELECTION   10.7
SCREEN PROCESSING STEPS, FOR AUTOMATIC CONTROL OF DATA ENTRY   11.4
SCREEN PROCESSING STEPS, MAXIMUM LENGTH   9.1
SCREEN PROCESSING STEPS, NAMING CONVENTIONS   11.3
SCREEN PROCESSING STEPS, POST-SEND CONFIRMATION SCREEN   12.1.3
SCREEN TITLES IN DATA ENTRY   12.1.3
                              11.3
SCREEN-ID   12.1.3
SEARCH PROCESSING   13.2.1
SEARCH RESULT, ASSIGN FOR PRISM   13.2.2
SEARCH STEPS   13
SEARCH STEPS, POST-SEARCH   13.3
SEARCH STEPS, PRE-SEARCH   13.3
SEARCH TYPES, HELP RECORD REQUIRED   6.4.3
SEARCH TYPES, HIDDEN SEARCH   13.1
SEARCH TYPES, INSTALLING IN ADD PROFILE   4.1
SEARCH TYPES, MODIFYING OR INSTALLING WITH XSETUP INDEXES   8.2.1
SEARCH TYPES, NUMBER ALLOWED   2.3
SEARCH TYPES, PROTOCOL STEPS   13
SEARCH TYPES, STAND-ALONE   13.4.1
SEARCH TYPES, STANDARDS   2.3
SEARCH TYPES, SUPPLYING THEIR OWN VALUE   2.4
SEARCH TYPES, TO QUALIFY A PREVIOUS SEARCH   13.4.3
SEARCH TYPES, USING STACKS   13.2.2
SECONDARY FILES   16
                  12.1.4
                  2.1
SECONDARY SEARCH TYPES   13.4.2
SECURITY FOR PRISM APPLICATIONS   16.1
                                  16
                                  12.1.4
                                  2.1
SEGMENTS OF FULL DISPLAY   3.3
SELECT COMMAND, DISABLING AND ENABLING   8.5
SEND COMMAND   12.1.3
               11.3.2
               11.3
SEND COMMAND, OPTION ON PERFORM PRISM SCREEN   12.1.3
SEQUENCING, DEFINING SORTING FIELDS   5
SEQUENCING, RECORDS IN REPORTS   10.1
SEQUENCING, RECORDS IN SEARCH RESULTS   4.1
SET COMMANDS IN P