INDEX
*  SPIRES Device Services
+  PREFACE
+1  Acknowledgments
1  Introduction
1.1  Using Device Services
1.2  Full-Screen Protocol Example
2  System-Defined Uncontained Areas
2.1  The CRT (Cathode Ray Tube) Area
2.2  The FILE Area
2.3  The FIL2 Area
2.4  The HLIO (Host Language IODATA) Area
2.5  The HLCA (Host Language Communications) Area
2.6  The HTML Area
2.7  The MEM (Memory) Area
2.8  The NIO Area
2.9  The NULL (Null) Area
2.10  The SBF (Subfile) Area
2.11  The TER (Terminal) Area
2.12  The ACTIVE Area
2.13  Summary Chart of System-Defined Areas
3  Defining Areas
3.1  The DEFINE AREA Command
3.1.1  IODATA|ODATA|IDATA|NODATA and MSG|NOMSG
3.1.2  BGUNPROTECT|BGPROTECT|PROTECT
3.1.3  The OVERFLOW Option
3.1.4  The DUPLICATE Option
3.2  The REDEFINE AREA Command
3.3  The SET AREA Command
3.4  The SHOW AREA Command
3.5  Area Hierarchies And Overlapping Areas
3.6  Zones
3.7  SHOW DATS command
4  Data Movement
4.1  The "IN areaname" Prefix
4.1.1  The "USING frame" Prefix and XEQ FRAME Command
4.1.1.1  (The NODATA DISPLAY Option)
4.1.2  The Star (*) and Dash (-) Commands
4.1.3  Device Services Areas and Report Formats
4.2  The DUPLICATE AREA Command
4.3  The $GETAREA Function
4.3.1  The SHOW FIELDS Command
4.4  The $PUTAREA Function
4.5  The $SETAREA Function
4.6  The READ, WRITE, and BLANK Commands
4.6.1  The WRITE Command
4.6.2  The READ Command
4.6.3  The BLANK Command
4.6.4  I/O Commands With No Area Specified
4.7  Options for the READ, WRITE, and BLANK Commands
4.7.1  The ATTN Option
4.7.2  The CURSOR Option
4.7.3  The NULL Option
4.7.4  The READ Option
4.7.5  The REPROMPT Option
4.8  The SET NOWRITE and SET NOREAD Commands
4.8.1  Controlling WRITE Actions
4.8.2  Controlling READ Actions
4.9  The ASK AREA Command
4.10  Storing Areas
4.10.1  The STORE AREA Command
4.10.2  The SHOW STORED AREAS Command
4.10.3  The RESTORE AREA Command
4.11  Directing Data to Multiple Areas From a Format
5  Full-Screen Programming
5.1  Introduction
5.1.1  Using the Terminal
5.1.2  The Components of a Full-Screen Application
5.1.3  Device Services Areas and Formats
5.1.3.0  (Placing the Fields Within the Area)
5.2  Designing An Application: An Example
5.2.1  The Data Base and the On-Line Features
5.2.2  Functions and Commands
5.2.3  The Screens
5.3  Displaying Records
5.4  Entering Commands: The COMMAND Area
5.5  Constructing the Protocol
5.5.1  Beginning the Session
5.5.2  Command Processing
5.5.2.1  The DISPLAY command
5.5.2.2  The FIND Command
5.6  Updating Records
5.6.1  Displaying the Record to be Updated
5.6.2  Merging the Record
5.6.3  Handling Error Conditions: The REPROMPT Uproc
5.7  Adding New Records
5.8  Special Topics
5.8.1  INCLOSE Error Processing
5.8.2  Displaying Multi-Screen Records
5.8.3  Updating Multi-Screen Records
5.8.4  Displaying Multi-Record Screens
5.8.5  Updating Multi-Record Screens
5.8.6  Menu-Driven Applications
5.8.7  Help and Explain Facilities
5.8.8  Error Messages for Multiply-Occurring Elements
5.8.9  Combining Full-Screen and Line-by-Line Processing
5.9  A Sample Full-Screen Application
5.9.1  The Protocol
5.9.2  The Vgroup
5.9.3  The Format
5.9.3.1  Frame CMDOUT
5.9.3.2  Frame CMDIN
5.9.3.3  Frame OUT
5.9.3.4  Frame MERGE
5.9.3.5  Frame ADD
5.9.3.6  Frame INPUT
5.9.3.7  Frame Declaration Section
5.9.4  The File Definition
6  Display Attributes and Specific Terminal Characteristics
6.1  General Rules for Specifying Display Attributes
6.1.0  Display Attributes for Specific Types of Fields
6.1.1  The DISPLAY Statement
6.1.2  The SET DISPLAY Uproc
6.1.3  The SET TDISPLAY Uproc
6.1.4  The SET EDISPLAY and SET ELENGTH Uprocs
6.1.5  Using Display Attributes with the TER Area
6.1a  Controlling the Terminal Screen: The SET CRT Command
6.2  Emphasis Attributes
6.3  Color and Alternate Character Set Attributes
6.3.1  The Ruling Font Character Set
6.4  PTUNDERLINE|UNDERLINE|NOUNDERLINE and DISPLAY = UNDER
6.5  PTNUMERIC|NUMERIC|ALPHANUMERIC and DISPLAY = NUMERIC
6.6  Autotab Specification
6.7  Function Key Determination
6.7.1  (Function Keys on VT100-Type Terminals)
6.8  PTDETECT|DETECT|NODETECT and DISPLAY = DETECT
6.9  The IBM 3270 Terminals
6.9.1  Emphasis Levels
6.9.2  Numeric Field Editing
6.9.3  Light-Pen and Cursor Selection Control
6.9.4  Pad Characters: The SET PADCHAR Uproc and PADCHAR Statement
6.10  The Tektronix Terminal
6.10.1  The DIRECT/BUFFER Switch
6.10.2  Emphasis Levels
6.10.3  Alternate Character Sets
6.10.4  Numeric Field Editing
6.11  The Zentec Terminal
7  Using File Devices
7.1  The FILE Area
7.2  The ASSIGN AREA Command
7.3  The CLOSE AREA Command
7.4  Writing to a File Device
7.5  Reading from a File Device
7.6  Submitting a Job Using FILE Areas
7.7  The HTML Area
7.7.1  HTML Display Attributes
7.7.2  UNDERLINE, WRAP, CENTER, NBSP and Hn Attributes
7.7.3  HTML Color Attributes
7.7.4  HREF, NAME, TAG and MAILTO Attributes
7.7.5  IMG and ALT Attributes
7.7.6  RAW Attribute
7.7.7  The $HTML Function
7.7.8  $HTML, TEXT Mode Option
7.7.9  HTML Style Attributes
7.7.10  HTML Xn Attributes
7.7.11  HTML Recommendations
7.8  The NIO Area
8  The Host Language Interface (HLI)
8.1  Areas used with the HLI
8.2  Using the HLI
8.2.1  The SPISET Call
8.2.2  The SPIRES Call
8.2.3  Data Transfer Between SPIRES and the Host Program
8.2.4  Output to HLIPRINT or SYSPRINT
8.2.5  The SET PATH ECHO Command; The $ENVIRON Variable
8.2.6  The SPIXIT Call
8.3  Host Language Interface Error Messages
8.4  Two Examples of Using the HLI from a COBOL Host
8.4.1  COBOL Host Program: STATIC Option Used in Compilation
8.4.2  COBOL Host Program: DYNAM Option Used in Compilation
8.5  Two Examples of Using the HLI from a PL/1 Host
8.5.1  PL/1 Host Program: Single-Path Example
8.5.2  PL/1 Host Program: Multiple-Path Example
8.6  Example using PL360 as the host language
8.7  Example using C as the host language
:  APPENDICES
:A  Appendix A: Size and Attribute Adjustments to Contained Areas
:B  Appendix B: Valid Commands for the "IN areaname" Prefix
:29  SPIRES Documentation

*  SPIRES Device Services

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

+  PREFACE

This manual describes SPIRES Device Services, a component of SPIRES that controls device-dependent I/O in a device-independent fashion. It is available in SPIRES and SPIBILD. Currently, its primary use is in full-screen programming, although it is also used with file devices (i.e, to move data directly from a SPIRES file to a non-SPIRES disk file) and the Host Language Interface.

In order to understand the material in this manual, you should be conversant in all areas of SPIRES. But of particular interest are the following documents:

Chapter 1 of this manual provides a general introduction to the concepts of Device Services, including a small, annotated example of a full-screen application. If you are new to Device Services, you should read this chapter first.

Chapters 2-4 include detailed descriptions of Device Services facilities and commands: system-defined areas, commands for defining your own areas, and commands for manipulating data transfer between the data base, Device Services areas, and the device.

Chapter 5 describes full-screen programming concepts. Drawing on the concepts covered in Chapters 2-4, and using a simple application as a model, this chapter takes you step-by-step through the process of implementing a full-screen application.

Chapter 6 describes terminal-specific characteristics, as they apply to full-screen programming concepts, for each of the terminals that SPIRES currently supports.

Chapter 7 describes the use of file devices. Currently, only ORVYL files are supported by Device Services.

Chapter 8 includes documentation for the Host Language Interface.

See the final appendix of this manual for a list of current SPIRES documentation, and how to keep up with changes made to this manual.

+1  Acknowledgments

Device Services is a major part of the SPIRES system. It has been designed, implemented, and is currently maintained by the Data Resources Group of I.T.S. (in its many incarnations over the years). The original software was designed and implemented by Bob Stainton. It is currently maintained and enhanced by Dick Guertin.

This manual was written by Becky Morton, from an earlier draft by Bob Stainton. Primary reviewers and contributors were John Sack, Dick Guertin, and Lynn McRae. Additional help was provided in the preparation of this document by Sandy Laws and John Klemm.

1  Introduction

SPIRES is able to address a wide spectrum of user and application needs due, in large part, to the flexibility provided by Device Services. With SPIRES Device Services, a programmer can implement an application that is easily adapted to any of a number of devices (i.e., terminals, files, other storage media), or the programmer can create a complement of formats and protocols that will run only on specific equipment, thereby controlling device-specific variables when needed. Where the more powerful capabilities of device-dependent software are not required, the complexity of fitting the specific to the general is hidden by providing defaults that will be appropriate in the majority of cases.

Device Services supports many physical or logical devices that allow for the input, display or manipulation of data. This means that data can be read from or written to an external file, accessed via programs in non-SPIRES languages or placed in temporary storage to be processed by other means, such as terminal hardware.

Devices currently supported by SPIRES Device Services are: line-by-line terminals, full screen terminals, non-SPIRES ORVYL files, WYLBUR data sets, network I/O, output to other subfile, host-language data buffer I/O, program memory workspace, unprocessed data streams, and throwaway data areas. These devices are described in detail in Chapter 2.

1.1  Using Device Services

To understand Device Services, you first need to understand a little about how SPIRES processes information. In the majority of cases, the end-user is communicating with SPIRES via a line-by-line terminal, entering data online and displaying data on the terminal screen. Often, the end-user will specify that data is to be placed in the WYLBUR active file, or will use the active file when adding and modifying records. Moving data between SPIRES and the terminal or active file is usually not controlled by Device Services.

But if you wanted to perform tasks that differ from those tasks involving simple terminal processing or active file I/O, you could specifically address Device Services. That is, you can tell SPIRES, by way of Device Services, exactly where you want the data placed, if, for example, you want the result of a display command to be directed to a disk file or placed on a specific section of a full-screen terminal.

To move data via Device Services, you would more than likely write a protocol incorporating Device Service commands into the record processing command stream. Although most examples will take the form of a protocol, all Device Services commands may be issued directly at the terminal. A simple example is a protocol that retrieves data from a record and displays it on a full-screen terminal. The protocol might be structured something like this:

A - Establish the Environment

    1)  Set up the appropriate environment for the device and
    application, i.e., set the message level, NOECHO, NOSTOP,
    and NOWRITE (a Device Services setting).

    2)  Define "areas" that will be used by Device Services as
    data buffers to hold data that is to be written to the
    screen in a manner specified by the format set in Step 3.

    3)  Select the subfile and set a format.

B - Process Records

    4)  Issue a command or series of commands to retrieve
    records, and move the data into the Device Services areas
    defined in step 2.

    5)  Transfer all of the data in the areas to the screen.

"Record processing" in step 4 covers a wide range of application needs. Because of the variety of the possibilities it is difficult to give a general picture of how Device Service operates, but the movement of data follows the same path: from SPIRES file to area to device and vice versa.

A Device Services "area" is a temporary storage area between the record and the physical device. Data is moved into an area from either a record or a device, and the area is "processed" by either moving the data into a record or transferring the contents of the area to the device. Moving data between a record and an area is controlled primarily by SPIRES display and input commands and formats; data placement specified by the format will occur relative to the dimensions of the area. Data movement between an area and a device is controlled by Device Services.

Areas may form hierarchies; that is, areas may be contained by other areas, and are thus referred to as "uncontained" and "contained". An uncontained area is system-defined and is equivalent to one of the devices mentioned above (i.e, terminals, files, etc.). Contained areas are user-defined and must be placed within one of the system-defined uncontained areas. For example, the full-screen terminal is represented by an uncontained area named CRT. To write on a portion of the screen, you might define an area called SCREEN and place it within the dimensions of CRT. SCREEN would be a contained area which could then be divided into other areas so that data could be placed on different parts of the SCREEN area. Each area would contain "fields", which would be defined by a format and might correspond to record elements or variable values.

Whenever a command is issued that does I/O, SPIRES must know what area is being used to hold the data. Every command has a default area associated with it, but can be preceded by the "IN areaname" prefix to alter the command's default area. You can think of "IN areaname" as being short for "INSIDE areaname", which indicates where the data is coming from or going to, not implying a direction of its movement. Direction is implied by the I/O command; for example, "IN areaname DISPLAY" indicates an output operation, and "IN areaname ADD" indicates an input operation.

The actual physical I/O operations are controlled by the Device Services commands READ, WRITE, and BLANK. The READ command is used to move data from a device into an area. The WRITE command transfers the data to the device from an area. The BLANK command clears all data from an area or a device. In addition, the ASK AREA command performs a combined WRITE and READ operation, prompting the user for a single field of input.

The above is only a brief overview of the processes involved, but you can see that Device Services has very powerful capabilities for controlling the dialogue between SPIRES and the end-user. Although of most use to the programmer of complex applications, it can be used in a number of ways to solve problems of varying complexity.

1.2  Full-Screen Protocol Example

The following protocol works with the public Restaurant subfile. This simple program allows the user to request a particular record and update the PRICE field. It is divided into sections and annotated to illustrate the general steps involved when using Device Services in a full-screen application. Commas follow "IN areaname" and "USING frame" prefixes for clarity -- they are not required. The format definition is also included.

 1. * UPDATE
 2.   ! STORE SETTINGS
 3.   ! SET NOECHO NOSTOP
 4.   SET TERMINAL NOCOMM NOMSG
 5.   SET NOWRITE
 6.   SET MESSAGES 0
 7.
 8.   DEFINE AREA SCREEN  (24,79) ON CRT (1,1)  PROTECT
 9.   DEFINE AREA STATUS  (1,79)  ON CRT (1,1)  PROTECT ALTCHAR=8 EMPHASIS=12
10.   DEFINE AREA COMMAND (1,79)  ON CRT (23,1) BGPROTECT ALTCHAR=32...
                                                    ...EMPHASIS=48
11.   DEFINE AREA MESSAGE (1,79)  ON CRT (24,1) PROTECT ALTCHAR=56 EMPHASIS=24
12.   DEFINE AREA UPDATE  (1,79)  ON CRT (6,1)  BGPROTECT
13.   BLANK CRT INTERNAL
14.
15.   SELECT RESTAURANT
16.   SET FORMAT UPDATE
17.
18.   LET TITLE = 'RESTAURANT PRICE MAINTENANCE'
19.   IN STATUS, SHOW EVAL...
            ...$INSETL($INSETR(#TITLE,' ',($SIZE(#TITLE)+79)/2),' ',79)
20.
21. ++COMMAND
22.   ASK AREA COMMAND (1,1) PROMPT 'RESTAURANT NAME:' ...
                                          ...ATTN = 'JUMP END.SESSION'
23.  /FIND NAME $ASK
24.   BLANK MESSAGE INTERNAL
25.   IF $RESULT = 0 THEN IN MESSAGE, SHOW EVAL 'NO RECORD FOUND FOR ' $ASK
26.                  THEN JUMP COMMAND
27.   IF $RESULT > 1 THEN IN MESSAGE, SHOW EVAL 'MORE THAN ONE FOUND FOR ' $ASK
28.                  THEN JUMP COMMAND
29.   IN UPDATE, USING OUTPUT, TYPE
30.   WRITE UPDATE READ ATTN = 'JUMP END.SESSION'
31.
32. ++UPDATE
33.  /IN UPDATE, USING INPUT, MERGE $KEY
34.   IF $YES THEN IN MESSAGE SHOW EVAL 'UPDATE SUCCESSFUL, PROCEED'
35.           THEN JUMP COMMAND
36.   IN MESSAGE, SHOW EVAL 'UPDATE UNSUCCESSFUL, TRY AGAIN'
37.   WRITE UPDATE REPROMPT ATTN='JUMP END.SESSION'
38.   JUMP UPDATE
39.
40. ++END.SESSION
41.   BLANK CRT INTERNAL
42.   WRITE CRT
43.   SET TERMINAL COMM MSG
44.   SET WRITE
45.   SET MESSAGES 2
46.   RESTORE SETTINGS

Lines 2-6 set up the appropriate protocol and full-screen environment.

Lines 8-12 define the Device Services areas.

Line 13 blanks the screen.

Lines 15-16 select the subfile and set the format.

Lines 18-19 place status information in the area that will appear across the top of the screen.

Lines 21-38 process a single record as follows:

Line 22 presents the screen to the user, prompting the user for input, which is then placed in the variable $ASK.

Line 23 attempts to retrieve a record based on the value entered by the user.

Line 24 clears the MESSAGE area of any data.

Lines 25-28 create a message if the search retrieved zero records or more than one record and the protocol then returns to line 21 to prompt the user for more input.

Line 29 places the record in the area.

Line 30 writes the screen and prompts the user for input. The screen will be read after the user has made changes on the screen and pressed the ENTER key.

Line 33 will attempt to merge the changes into the record.

Line 34 creates a message indicating that the merge was successful and line 35 returns to line 21 to prompt the user for more input.

Lines 36-38 reprompt the user with the same record if the change caused an error, and returns to line 32 to try the MERGE again.

If the user hits ATTN when being prompted for input, lines 40-46 will be executed and the session will end.

The Format

ID = GQ.BEC.PRICE.UPDATE;
MODDATE = MON. MAY 9, 1983;
DEFDATE = THUR. MAY 5, 1983;
FILE = GA.PUB.RESTAURANT;
RECORD-NAME = ID;

FRAME-ID = OUTPUT;
  DIRECTION = OUTPUT;
  FRAME-DIM = 1,79;
  USAGE = NAMED, DISPLAY;
  LABEL = NAME;
    GETELEM;
    TITLE = 'NAME:';
    TSTART = 1,1;
    START = 1,8;
    PUTDATA;
  LABEL = PRICE;
    GETELEM;
    TITLE = 'PRICE:';
    TSTART = 1,40;
    DEFAULT = '(NONE)';
    START = 1,48;
    LENGTH = 6;
    DISPLAY = UNPROTECT,NUMERIC,A40;
    PUTDATA;
FRAME-ID = INPUT;
  DIRECTION = INOUT;
  FRAME-DIM = 1,79;
  USAGE = NAMED, MERGE;
  LABEL = NEW.PRICE;
    ESTART = 1,60;
    ELENGTH = 20;
    START = 1,48;
    LENGTH = 6;
    GETDATA = 5, 7, 8;
    INPROC = $MSG ('BAD DOLLAR VALUE')/ $DOLLAR/ $MSG('PRICE IS TOO
             HIGH')/ $RANGE(0,5000)/ $MSG('PRICE IS TOO LOW ')/
             $RANGE(100,5000);
    PUTELEM = PRICE;

FORMAT-NAME = UPDATE;
  FRAME-NAME = OUTPUT;
    FRAME-TYPE = DATA;
    UPROC = SET PADCHAR '_';
    UPROC = SET PROTECT;
    UPROC = SET TDISPLAY = A8;
    UPROC = SET DISPLAY = A40;
  FRAME-NAME = INPUT;
    FRAME-TYPE = DATA;
    UPROC = SET PADCHAR '_';
     UPROC = SET PROTECT;
     UPROC = SET EDISPLAY = 'A16,E8';

2  System-Defined Uncontained Areas

Uncontained areas are areas that may contain other areas, but that are not contained in any other area themselves. They are the outermost area in a hierarchy of areas, and are pre-defined by the system. Some uncontained areas represent specific hardware devices (e.g., terminals and disk files); others represent an internal space used for processing data within an application. The system-defined areas are:

 CRT      full-screen terminal screen
 FILE     non-SPIRES ORVYL file, OS FILE datasets, Active File
 FIL2     another FILE area, to allow simultaneous file usage
 HLIO     Host Language Interface data buffer
 HLCA     alternate HLI communications area
 HTML     like FILE, but allows device attributes.
 MEM      temporary storage in high speed memory
 NIO      network I/O area (unprocessed data stream)
 NULL     throwaway area
 SBF      output to SPIRES Subfiles
 TER      line-by-line terminal area

and the special area

 ACTIVE   the active file

This chapter describes the characteristics of each of the system-defined areas.

2.1  The CRT (Cathode Ray Tube) Area

The device represented by the CRT area is a full-screen terminal. It is, in effect, the current contents of the display screen. Its dimensions vary from terminal to terminal, but generally are on the order of 24 by 79 characters. (Most terminal screens with a width of 80 characters can only accomodate an area with 79 columns because the first column is needed for system information.) It always represents the terminal to which the user is logged on.

The width of the CRT area may vary from 79 to 131 characters, and is set automatically based on the screen width known to WYLBUR/Milten (via the SET TERMINAL command) when SPIRES is invoked. (Generally, it will be one character less than the width setting, for the reason described in the first paragraph; however, if the actual screen width is larger than 132 characters, the CRT width will still be only 131.)

You cannot use this area unless you are using a terminal supported for full-screen work. Full-screen terminals currently supported by SPIRES are: all Model Terminals (including PC and Mac Samson) and IBM 3278/3279 Terminals. [See 5 for details on using the CRT area.]

DEFINE AREA with an indefinite CRT area

Because the CRT area may vary in size, depending on the user's hardware and software configurations, you may need to specify the size of an area being defined on CRT as an indefinite value. When the command is executed, the current width and height settings for the CRT area could be used for the area being defined. To do this, specify a "0" for the height and/or width of the area being defined by the DEFINE AREA command. [See 3.1.]

For example:

will define the SCREEN area to be the size of the CRT area, whatever it is for the user at the time the command is executed.

2.2  The FILE Area

The FILE area allows read and write access to non-SPIRES ORVYL files, OS FILE datasets, and the Active File. It may have an indefinite length and indefinite width. The default definition is a line-by-line (i.e., one row) area 80 characters wide; data written outside the column dimensions of the area is truncated. The maximum size of a FILE area is determined by its dimensions -- the product of the length and the width cannot exceed 32,760 bytes. (A contained area defined on the FILE area cannot exceed 32,000.)

Any user-defined areas laid on top of FILE can alter both the length (rows) and width (columns) of the FILE area. Whenever an area is defined on FILE, the FILE area and all areas defined on FILE are automatically blanked.

Note that there are two uncontained file areas, FILE and FIL2. Defining areas on FILE does not affect FIL2, and vice versa. Because multiple areas can be defined on FILE, it can support I/O to several physical files. The ASSIGN AREA and CLOSE AREA commands are used to connect a FILE area with a physical file on disk. [See 7.2, 7.3.] If a FILE area is not assigned to a physical file, it can be used as a "scratch pad" area, similar to the MEM area described below. [See 7 for details on using the FILE area.]

2.3  The FIL2 Area

The FIL2 area is simply another FILE area, with independent buffers. All of the characteristics of the FILE area apply to FIL2 as well. The default definition is a line-by-line (i.e., one row) area 80 characters wide; data written outside the column dimensions of the area is truncated. The maximum size of a FIL2 area is determined by its dimensions -- the product of the length and the width cannot exceed 32,760 bytes. (A contained area defined on the FIL2 area cannot exceed 32,000.)

Any user-defined areas laid on top of FIL2 can alter both the length (rows) and width (columns) of the FIL2 area. Whenever an area is defined on FIL2, the FIL2 area and all areas defined on FIL2 are automatically blanked.

Note that there two independent file areas, FILE and FIL2. Because multiple areas can be defined on FIL2, it can support I/O to several physical files. Two separate uncontained areas are provided to double the capacity, essentially giving you up to 64K of space, 32K for each area. The ASSIGN AREA and CLOSE AREA commands are used to connect a FIL2 area with a physical file on disk. [See 7.2, 7.3.] If a FIL2 area is not assigned to a physical file, it can be used as a "scratch pad" area, similar to the MEM area described below. [See 7 for details on using the FILE and FIL2 areas.]

2.4  The HLIO (Host Language IODATA) Area

The device represented by the HLIO area is the communications area for the Host Language Interface, and is used to pass data to and from the host program. This area always has a fixed length capacity of one row by 4108 columns, but smaller column dimensions may be specified by the programmer in the CALL to the Host Language Interface. [See 8 for details on using the Host Language Interface.]

2.5  The HLCA (Host Language Communications) Area

The device represented by the HLCA area is identical to the HLIO area, but with flexible dimensions. The programmer can specify row and column dimensions in a DEFINE AREA command passed in a CALL to the Host Language Interface, making it possible to match the area to already existing fixed-dimensioned formats. Therefore, multiple lines and multiple records can be written to or read from a Host Language program through areas defined on HLCA. Data placed in the HLCA area will be identical to data in the HLIO area but will be split into the number of specified rows. [See 8 for details on using the Host Language Interface.]

If you do not define a larger area on it, the HLCA area only has the dimensions of one row of 16 columns.

2.6  The HTML Area

The HTML area has all the characteristics of the FILE and FIL2 areas allowing output only to non-SPIRES ORVYL files, OS FILE datasets, and the Active File. In addition, HTML areas recognize and process "display attributes", such as color and emphasis, and provides for <HTML>...</HTML> tags. The HTML areas may have an indefinite length and indefinite width. The default definition is a line-by-line (i.e., one row) area 80 characters wide; data written outside the column dimensions of the area is truncated. The maximum size of an HTML area is determined by its dimensions -- the product of the length and the width cannot exceed 32,760 bytes. (A contained area defined on the HTML area cannot exceed 32,000.)

Any user-defined areas laid on top of HTML can alter both the length (rows) and width (columns) of the HTML area. Whenever an area is defined on HTML, the HTML area and all areas defined on HTML are automatically blanked.

The ASSIGN AREA and CLOSE AREA commands are used to connect HTML areas with a physical file on disk, or the Active File. [See 7.2, 7.3.] If an HTML area is not assigned to a physical file, it can be used as a "scratch pad" area, similar to the MEM area described below. [See 7.7 for details on using the HTML area.]

2.7  The MEM (Memory) Area

The device represented by the MEM area is temporary storage in high speed memory. It always has a fixed capacity of 61 rows by 132 columns. The area is most commonly used to write system information (such as the results of SHOW commands) to be used in further processing by the program.

No physical I/O operations are actually performed because there is no corresponding physical device. Access to data in this area is only via formats or the $GETAREA function. [See 4.3.] The contents of the area can be copied to another area with the DUPLICATE AREA command if read or write operations are desired. [See 4.2.]

If the size of the MEM area is too small for your needs, the FILE area can be used in much the same way. [See 7.1.]

2.8  The NIO Area

The NIO area allows read and write access to a Remote Host via ORVYL Network I/O services.

For details on using the NIO area [See 7.8.]

2.9  The NULL (Null) Area

The NULL area represents a non-existent device which may be used to "throw away" output information. It has an indefinite length and width. The READ and WRITE commands [See 4.6.] have no effect with the NULL area.

The NULL area is often used to place data resulting from a command that you do not want to be written to the terminal or the active file. For example, if you had a stack of records and wanted to know the key of the last record, you could issue the following commands:

The $KEY variable would then be set to the key of the last record, but the data of the SHOW KEYS LAST command would be thrown away.

Another common use of the NULL area is to redefine an existing user-defined area ON NULL. This will eliminate the area and all data in it.

2.10  The SBF (Subfile) Area

The SBF area represents a line-by-line area that is only valid for output. See the Formats manual for a complete description. [EXPLAIN SBF AREA.]

2.11  The TER (Terminal) Area

The TER area represents a line-by-line terminal, and is only valid for output. It has an indefinite length capacity. Width is determined by the value of the WYLBUR command SET WIDTH in effect at the time the area is defined (that is, when it is first referenced by a command), if this value is between 32 and 157; otherwise, width is equal to 150. Reissuing the SET WIDTH command will not alter the width of TER. This area always represents the terminal to which the user logged-on.

The TER area is somewhat unique among areas because of the nature of terminal processing. Normal terminal communication does not use Device Services; data is sent directly from the terminal to the SPIRES processor and vice versa. If the TER area is explicitly mentioned in an output command, the information is sent through Device Services before being displayed on the terminal screen. This allows the programmer more control over line-by-line terminal displays. For example, since TER is an indefinite length area, you could define a fixed sized rectangular area on TER, place data into various rows of that area in any order, and then write the entire area as a consecutive set of rows. The first row written could have been the last row to receive data.

2.12  The ACTIVE Area

The ACTIVE area represents the WYLBUR active file. It has an indefinite length and indefinite width.

Like the TER area, the ACTIVE area is unique, and although in form is like other Device Services areas, it does not function like the other areas. If a command is preceded by the IN ACTIVE prefix, the data is not handled by Device Services but is written directly to the active file at the next available line. No other areas can be defined on ACTIVE, and Device Services commands such as READ and WRITE and the $GETAREA, $PUTAREA, and $SETAREA functions cannot be used with ACTIVE.

ACTIVE may be abbreviated to its first three characters.

2.13  Summary Chart of System-Defined Areas

The following chart lists the characteristics of the system-defined areas, and includes the default settings for device attributes and functions.

+---------------------------------------------------------------------------+
| AREA | AVAILABILITY  |        SIZE          |     DEVICE    |   DEFAULT   |
|      |               |                      |   ATTRIBUTES  |  FUNCTIONS  |
|---------------------------------------------------------------------------|
| CRT  |  Online       |  detectable height   |  PTUNDERLINE  |   IODATA    |
|      |  HLI          |  & width of screen,  |  PTNUMERIC    |   MSG       |
|      |               |  typically 24 x 79   |  PROTECT      |             |
|      |               |                      |  DETECT       |             |
|---------------------------------------------------------------------------|
| FILE |  Online       |  indefinite length   |  none allowed |   IODATA    |
|      |  HLI          |  indefinite width    |               |   MSG       |
|      |               |  (default = 80)      |               |             |
|---------------------------------------------------------------------------|
| FIL2 |  Online       |  indefinite length   |  none allowed |   IODATA    |
|      |  HLI          |  indefinite width    |               |   MSG       |
|      |               |  (default = 80)      |               |             |
|---------------------------------------------------------------------------|
| HLIO |  HLI          |  length = 1          |  none allowed |   IODATA    |
|      |               |  max width = 4108    |               |   NOMSG     |
|---------------------------------------------------------------------------|
| HLCA |  HLI          |  indefinite length   |  none allowed |   IODATA    |
|      |               |  indefinite width    |               |   MSG       |
|      |               |  (default = 16)      |               |             |
|---------------------------------------------------------------------------|
| HTML |  Online       |  indefinite length   |  same as TER  |   ODATA     |
|      |  HLI          |  indefinite width    |     plus      |   MSG       |
|      |               |  (default = 80)      |  HTML tags    |             |
|---------------------------------------------------------------------------|
| MEM  |  Online       |  length = 61         |  none allowed |   IODATA    |
|      |  Batch        |  width = 132         |               |   MSG       |
|      |  HLI          |                      |               |             |
|---------------------------------------------------------------------------|
| NIO  |  Online       |  length = 1          |  none allowed |   IODATA    |
|      |  HLI          |  width = 2560        |               |   NOMSG     |
|---------------------------------------------------------------------------|
| NULL |  Online       |  indefinite length   |  none allowed |   IODATA    |
|      |  Batch        |  indefinite width    |               |   MSG       |
|      |  HLI          |  (default = 0)       |               |             |
|---------------------------------------------------------------------------|
| SBF  |  Online       |  length = 1          |  none allowed |   ODATA     |
|      |  HLI          |  width = 2560        |               |   NOMSG     |
|---------------------------------------------------------------------------|
| TER  |  Online       |  indefinite length   |  same as CRT  |   ODATA     |
|      |  HLI          |  width = 150 or      |   excluding   |   MSG       |
|      |               |  SET WIDTH value     |    DETECT     |             |
+---------------------------------------------------------------------------+

3  Defining Areas

An area, in its most general sense, is a rectangular array of characters associated with a specific device, which may or may not have definite dimensions and a finite capacity. An area's purpose is to serve as a temporary storage space for data as it is being transferred between SPIRES and a physical device.

In an application, you may use the system-defined areas described in Chapter 2, or you may define your own areas. Any area that you define must exist within (i.e., be contained by) one of the system-defined areas. Defining your own areas allows you to have multiple areas associated with a single device, thus enabling you to control several data transfers to or from the same device at once. In addition, user-defined areas can overlap one another, allowing you to control the placement of areas in relation to one another.

Each area will contain one or more fields. A field is a consecutive set of characters, all with identical characteristics. A foreground field is a field created by either the $PUTAREA function, [See 4.4.] the PUTDATA statement in a format, or a command that results in a response to the user such as SHOW EVAL or EXPLAIN. (See Appendix B for a list of SHOW commands and other commands that can have an "IN areaname" prefix, and thus place data in an area.) A background field is any other field in the area. The distinction between foreground and background fields is only applicable in full-screen programming.

An area may be assigned a "function" that determines whether it is available for input, output, or system messages; this is done by the DEFINE AREA and SET AREA commands. This again is dependent upon the characteristics of the physical device represented by the area, and if not specifically assigned, will default to the least restrictive function possible for the area. [See 3.1.1.]

The size and placement of an area is specified on the DEFINE AREA command, but can be affected by the characteristics of the area on which it is defined. Some areas have an indefinite length and/or width, which means that the area is capable of holding a variable amount of data, whereas other areas are restricted by the size of the physical device. The size and placement of an area can be altered by defining other areas within the same hierarchy.

The characteristics of a field are determined by the attributes assigned to it through the area definition and the format frame (if any) in use. Only the CRT and TER system-defined areas support attributes. If you assign a device attribute to an area for which the attribute is invalid or meaningless, the assignment will be ignored. If not specifically assigned, default settings will take effect. For example, an area defined on CRT could be assigned a display attribute that determines the characteristics of the field when displayed on the terminal screen (such as the level of brightness), or a field may be assigned protection attributes that determine whether the field may be modified by the user. Such attributes are established by either the DEFINE AREA command, [See 3.1.] the $SETAREA function, [See 4.5.] display Uprocs or the DISPLAY statement in a format, [See 6.] the defaults assigned by the area hierarchy associated with the field, or a combination of these.

This chapter describes the basic commands used to define and manipulate areas and the general rules for overlapping areas or creating an area hierarchy.

Appendix A contains details and examples of how area definitions are affected when areas are defined on one another.

3.1  The DEFINE AREA Command

The DEFINE AREA command is the basic command used to define areas. The syntax is:

  DEFINE AREA areaname1 [(rows,cols)] ON areaname2 [(srow,scol)]

followed by any of the following:

        [IODATA|ODATA|IDATA|NODATA]
        [MSG|NOMSG]
        [BGUNPROTECT|BGPROTECT|PROTECT]
        [OVERFLOW [TO] [NULL|areaname3]]
        [EMPHASIS n|NOEMPHASIS|emphasis-terms]
        [ALTCHAR n|altchar-terms]
        [PTUNDERLINE|UNDERLINE|NOUNDERLINE]
        [PTNUMERIC|NUMERIC|ALPHANUMERIC]
        [PTDETECT|DETECT|NODETECT]
        [DUPLICATE [TO] [NULL|areaname3]]

"Areaname1" is the name of the area being defined. It must contain one to sixteen alphanumeric characters, and may not be a system-defined uncontained area name. If the area named is already defined, it will be redefined by the new DEFINE AREA command and any data in the area will be lost. [See 3.2 for details about the REDEFINE AREA command.] All areas in existence for a given session or batch execution must have unique names.

The "(rows,cols)" parameter specifies the number of rows and columns the area is to occupy. The product of "rows" and "cols" must not exceed 16384 or the area will be truncated. If either dimension is omitted, then an area being newly defined will take that dimension from the containing area. An area being redefined will keep the previously specified dimension. If the area being defined is specified as larger than the containing area, it will be truncated to fit the containing area. For example, if an area is defined as being 75 characters wide, but the area that contains it is only 70 characters wide, the defined area will only be 70 characters wide. [See Appendix A for details about automatic size adjustments.]

"Areaname2" is the name of the area that is to contain the area being defined. It must either be a system-defined area or have been already defined by another DEFINE AREA command. If not, the command fails.

The "(srow,scol)" parameter specifies the coordinates within the containing area where the area being defined begins.

"Srow" may be:

 - Any number indicating the specific row position (maximum 16384).  A value of  "X"
 represents  the  next  row  after  the last area defined for this area, or 1 if this is the
 first.  A * indicates the starting row of the area last defined for this area, or 1 if this
 is the first.
 - "X+increment" or "X-increment" (maximum 16384).
 - "*+increment" or "*-increment" (maximum 16384).
 - CENTER or CE.  The area being defined will be centered vertically inside the area on  which
 it is defined.
 - ALIGN TOP or T.  The first row of the area being defined will be aligned with the  top  row
 of the area on which it is defined.
 - ALIGN BOTTOM or B.  The last row of the area being defined will be aligned with the  bottom
 row of the area on which it is defined.
 - MIDDLE, MID, or M.  The first row of the area being defined will be aligned  with  the  row
 closest to the middle of the area on which it is defined.

"Scol" may be:

 - Any  number  indicating  the  specific  column  position  (maximum  16384).   A  value   of
 "X"  represents  the next column to the right of the last column of the area last
 defined for this area, or 1 if this is the first.  A * indicates the starting column of the
 area last defined for this area, or 1 if this is the first.
 - "X+increment" or "X-increment" (maximum 16384).
 - "*+increment" or "*-increment" (maximum 16384).
 - CENTER or CE.  The area being defined will be centered  horizontally  inside  the  area  on
 which it is defined.
 - ALIGN LEFT or L.  The first column of the area being  defined  will  be  aligned  with  the
 left-most column of the area on which it is defined.
 - ALIGN RIGHT or R.  The last column of the area being  defined  will  be  aligned  with  the
 right-most column of the area on which it is defined.
 - MIDDLE, MID, or M.  The first column of the area being defined will  be  aligned  with  the
 column closest to the middle of the area on which it is defined.

The default "srow" value is X; the default "scol" value is *. The default values, (X,*), will place the new area directly below the one previously defined; values of (*,*) will place the new area on top of it; values of (*,X) will place it to the right of the previously defined area. If an area is defined at a location that does not exist for the containing area (such as row 40 of CRT), the area being defined is effectively null.

If either position is omitted, then newly defined areas are assigned the default positions; otherwise, the previously specified position for the redefined area is reused.

The following commands will create areas on a full-screen terminal as shown in the drawing:

        0  10  20  30  40  50  60  70  80
        +------------------------------+
        |               A              |
      5 |------------------------------|
        |                              |
     10 |                  +-----------|
        |         B        |           |
     15 |                  |     C     |
        |                  |           |
     20 |------------------------------|
        |                              |
        +------------------------------+

Or, as another example:

        0  10  20  30  40  50  60  70  80
        +------------------------------+
        |                      |       |
      5 |       +--------------|       |
        |   A   |              |       |
     10 |       |  B   +----+  |       |
        |       |      | C  |  |       |
     15 |       +--------------|       |
        |                      |       |
     20 |----------------------+       |
        |                              |
        +------------------------------+

Memory space is allocated for an area the first time it is referenced in a command, so it is advisable to define the area as early in a SPIRES session as possible. An area can be partially defined by referencing it in a DEFINE AREA command without having previously defined it. This is only the case when the OVERFLOW [See 3.1.3.] or DUPLICATE [See 3.1.4.] options are used. Partially defined areas are effectively null, but can be subsequently redefined.

An area cannot be "undefined" (unless you EXIT SPIRES). However, if you wish to eliminate an area during a session, you can redefine it (with either the DEFINE AREA command or the REDEFINE AREA command) [See 3.2.] on NULL. This will, in effect, undefine it.

The "function" options (IODATA, ODATA, IDATA, NODATA, MSG, NOMSG), the area protection attributes (BGUNPROTECT, BGPROTECT, PROTECT), and the OVERFLOW and DUPLICATE options are described in the following sections. The other options specify display attributes, and are described in Chapter 6.

3.1.1  IODATA|ODATA|IDATA|NODATA and MSG|NOMSG

The function option of the DEFINE AREA command [See 3.1.] allows you to assign data and message functions to the area. These assignments only allow the area to accept the particular function; they do not cause the area to be used for that function. This is done with the SET AREA command -- after assigning a function to an area, you specify that area to be the default destination or source of data by naming it in the SET AREA command. [See 3.4.] The possible data functions are: IODATA, IDATA, ODATA, NODATA; the message functions are MSG, and NOMSG.

An area assigned the IODATA function may serve as a source of data, as a data destination, or as both. This function is assignable only in situations where "conversation" is possible (e.g., online), and on devices that have both input and output capability. An area assigned the IDATA function serves as an input area for data read from a device with input capability. An area assigned the ODATA function serves as an output area from which data is sent to a device with output capability.

An area assigned the MSG function can serve as an area to which diagnostic messages and informational messages may be sent. The output from the SET ECHO, SET FTRACE, and SHOW FILTERS commands is also sent to the area assigned the MSG function. An area given the MSG function must be contained by an area with output capability; MSG is invalid for the NIO area. [See 4.8.1 for details about writing MSG areas to the device.]

When you first define an area, if you do not assign an area either a data function or a message function, an area will default to IODATA and MSG, the least restrictive functions possible. When an area is first defined, if you specify a data function but no message function, the area assumes the NOMSG function. Likewise, if you specify MSG but no data function, the area assumes the NODATA function. However, if you assign an area the NOMSG function without specifying a data function, the area will assume the IODATA function. If a function is assigned to an area that is contained by an area that has a function that is incompatible, the function assignment will not be accepted. [See Appendix A for details about how attribute assignments can be effected by redefining containing areas.]

If you redefine an area later to change the functions, only the functions that you include on the REDEFINE AREA or DEFINE AREA command will be altered. NODATA and NOMSG are used to change a previous assignment. For example, if an area had been assigned the MSG function, but you wanted to change it to be strictly IDATA, you would specify both NOMSG and IDATA on the defining command. If an area currently has the IODATA function and you wish to change it to be strictly IDATA or ODATA, you must first change it to NODATA (since IODATA already is both IDATA and ODATA) and then assign it the single function. This can be done in one command (e.g., REDEFINE AREA ONE NODATA IDATA).

3.1.2  BGUNPROTECT|BGPROTECT|PROTECT

The protection attribute, specified on the DEFINE AREA command, [See 3.1.1.] is used to establish a default field protection condition for the area. It only applies to TER and CRT and areas defined on them, for use in full-screen applications. By using area protection attributes in conjunction with statements in the format frame, the programmer can carefully control which fields in the area can be altered by the end-user. [See 6 for more details about the display Uprocs and the DISPLAY statement in formats.]

As defined in the introduction to this chapter, fields are either foreground or background. A foreground field is a field created by either the $PUTAREA function, the PUTDATA statement in a format, or any command that takes the "IN areaname" prefix. [See Appendix B.] A background field is any other field in the area.

BGUNPROTECT, "Background Unprotected", (alias PTPROTECT, "Permit to Protect") is the default setting if no protection attribute is declared on the DEFINE AREA command. All background fields are unprotected; foreground fields are unprotected unless the executing format frame protects them.

If BGPROTECT, "Background Protected", (alias PTUNPROTECT, "Permit to Unprotect") is specified, then all background fields are protected; all foreground fields are unprotected, but an executing format frame is permitted to protect them.

If PROTECT is specified, then all fields (background and foreground) in the area are protected. This overrides individual field definitions within a frame as the frame is processed to the area.

Foreground Field Protection Control in Formats

Several Uprocs exist that can be placed in a format to affect field protection. They are:

They establish a default for the entire frame, but can be overridden for an individual label group by including a DISPLAY statement in that label group. The SET PROTECT|UNPROTECT Uproc causes all foreground fields to be protected or unprotected. The SET DISPLAY Uproc affects data fields. The SET TDISPLAY Uproc affects titles. The SET EDISPLAY Uproc affects error messages.

The DISPLAY = PROTECT|UNPROTECT statement is coded for individual label groups and allows a data field or error message field (i.e., a field positioned by START or ESTART, but not TSTART) to be protected or unprotected if the area is assigned the BGUNPROTECT or BGPROTECT attribute. For example, if an area is defined with the BGPROTECT attribute, a label group could specify DISPLAY = UNPROTECT to allow an individual field to be unprotected when UPROC = SET PROTECT is also included.

The general rule to follow when defining field protection is to protect everything by assigning the area the BGPROTECT attribute and including the SET PROTECT Uproc in the format, and unprotecting specific fields as necessary with the DISPLAY = UNPROTECT statement in the label group.

Given the above definitions, the following rules apply:

 - A data field or error message field is protected if:
   1. The area is assigned the PROTECT attribute, or
   2. The DISPLAY = PROTECT statement is included in the
      field's label group, or
   3. The SET PROTECT Uproc is included in the frame declaration
      section and the label group does not include a DISPLAY =
      UNPROTECT statement.
 - A data field or error message field is unprotected if:
   1. The area is not assigned the PROTECT attribute, and either
      a) the frame does not include a SET PROTECT Uproc and the
         field's label group does not include a DISPLAY = PROTECT
         statement, or
      b) the frame does include a SET PROTECT Uproc but the
         label group includes a DISPLAY = UNPROTECT statement.
 - TITLES (those fields positioned by TSTART) are protected if:
   1. The area is assigned the PROTECT attribute, or
   2. The frame includes a SET PROTECT Uproc.
   3. The frame includes a SET TDISPLAY Uproc.

Note that TITLE fields are not affected by the DISPLAY statement; only data fields and error message fields are. All foreground fields (data fields, error message fields, and TITLE fields) are subject to the default set by the SET PROTECT|UNPROTECT Uproc.

Although all combinations of the above statements are possible, you would not necessarily ever want to use them all. For example, you would never want to have unprotected background fields, titles, or error messages, because it would permit the user to type characters anywhere on the screen (and possibly make a real mess of the display). So you would not generally want to define an area with the BGUNPROTECT option or use the SET UNPROTECT Uproc. [See 5 for an example of using the protection attributes in a full-screen application and Appendix A for details about protection attributes for hierarchical and overlapping areas.]

3.1.3  The OVERFLOW Option

The OVERFLOW option of the DEFINE AREA command [See 3.1.] provides for the orderly placement of data into an alternate area when the primary area becomes filled. This facility may be used to construct multi-column text.

The syntax is:

where "areaname3" is the area to which data will overflow. It must be an area that is capable of output (ODATA). If "areaname3" is not already defined, it will be partially defined, but effectively NULL. [See 2.9.]

The default is to allow no overflow, insuring that no data will be lost. OVERFLOW TO NULL will cause overflow data to be thrown away with no indication.

It is not necessary that all overflow areas be on the same uncontained area, but if they are not, the results of the overflow will be unpredictable.

Multiple areas may be chained together with the OVERFLOW option. However, any "looping" of OVERFLOW specifications in which an area overflows to an area that either directly or indirectly via a chain overflows to itself will result in the last OVERFLOW specification in the chain being changed to OVERFLOW TO NULL.

If you redefine an area, its OVERFLOW specification will be eliminated. If the area is part of an overflow chain, the chain will be broken. For example, if area ONE overflows to TWO which overflows to THREE which overflows to FOUR, and you redefine area THREE, the overflow from area THREE to area FOUR will no longer occur unless you include OVERFLOW TO FOUR in the redefinition.

3.1.4  The DUPLICATE Option

The DUPLICATE option of the DEFINE AREA command [See 3.1.] allows the same information to be directed to more than one area at the same time. The syntax is:

where "areaname3" is the area which is to receive the same information which is directed to "areaname1" (as specified on the DEFINE AREA command). "Areaname3" may be any area that is capable of output (ODATA). If "areaname3" has not been already defined, it will be partially defined, but effectively NULL. [See 2.9.]

Only one "areaname3" may be named per area, but it may be the subject of another DUPLICATE option. A second DUPLICATE option for the same "areaname1" cancels a previous one. Like the OVERFLOW option, DUPLICATE must be specified when redefining an area or the duplication is eliminated.

Information formatted for "areaname1" is not reformatted to accommodate different dimensions of "areaname3". Unlike the DUPLICATE AREA command, [See 4.2.] the attributes of the data (i.e., display attributes, UNDERLINE, or protection attributes) are copied to the second area. If the area is duplicated to an area for which the attributes are invalid, the attribute assignments are ignored. In addition, the DUPLICATE option specifies an operation that is to occur every time data is placed in "areaname1", whereas the DUPLICATE AREA command copies the area only when the command is issued.

Also, data sent to "areaname3" because of data being sent to "areaname1" will not cause "areaname3" to be written. Only an explicit WRITE command, or a direct reference to the area if SET WRITE is in effect, will cause it to be written. Likewise, a BLANK request for "areaname1" will not blank "areaname3"; an explicit request to BLANK "areaname3" has to be issued.

3.2  The REDEFINE AREA Command

The REDEFINE AREA command may be used to alter one or more parameters set in a currently defined area without having to reissue the entire command. If the area does not currently exist, the REDEFINE AREA command will define it. All current parameter settings are maintained except those explicitly given in this command, with the exception of OVERFLOW and DUPLICATE specifications, which are always reset. [See 3.1.3, 3.1.4.]

When an area is redefined, the entire uncontained area on which the area resides is first blanked, which clears all data from the area.

The syntax of the REDEFINE AREA command is identical to that of the DEFINE AREA command, except that you do not need to repeat the "ON areaname2" portion of the command. [See 3.1.]

A system-defined uncontained area may not be redefined.

3.3  The SET AREA Command

The SET AREA command is used to change the designation of the default area that is used when no area is specifically named (via the "IN areaname" prefix) in a command that involves input or output. The syntax is:

"Functions" include the data functions (IODATA, ODATA, IDATA, NODATA) and the message functions (MSG, NOMSG). [See 3.1.1.] In general, the area must be valid for each function named, or the entire command will fail. These functions can be assigned to the area via the DEFINE AREA command.

For example, if you were to issue the following command

then CRT would become the default destination for all output data -- any output command (e.g., DISPLAY, TYPE) would send data to the CRT area.

Or, if you issue the following commands:

then all system messages would go to the area named ERRORS and you would be able to control when SPIRES-generated messages were written. (When you alter the default destination for messages, you must have local NOWRITE in effect for that area. Otherwise, the default MSG area will be automatically written. Only the local setting is examined; a global NOWRITE setting does not affect MSG areas.) [See 4.8.1.]

If the area is later redefined so that a function for which it is the default is no longer valid, the default for that function will revert to the default in effect at the start of the session.

Note that an area defined as the default IDATA area will not be used unless a format is set that includes a DIRECTION = INPUT statement and the proper USAGE assigned. Unformatted input will always use the active file. [See 4.1.]

Resetting the Default Area

Only one area at a time can be the default area for any particular function. When you issue the SET AREA command, it cancels any previous assignment for that function.

The SET AREA NULL command is used to restore the default area for a particular function to what it was at the beginning of the session (i.e., when SPIRES or SPIBILD was first called).

The syntax is:

This is useful when you want to restore the original setting for IODATA or, MSG but you do not know the name of the original default area.

3.4  The SHOW AREA Command

The SHOW AREA command lists the hierarchy, definitions, and available functions of all areas that have been defined. The syntax is:

The "areaname" option will cause information to be listed for only the area named, which may be an uncontained area name. If omitted, all user-defined areas will be listed. Note that you cannot specify the name of a partially defined area, but these areas will appear in the list of all defined areas.

The NAMES option will cause only the following information to be listed:

If no parameters are given, the command will list all information about all user-defined areas. To list information about system-defined areas, you must name the area in the SHOW AREA command (e.g., SHOW AREA CRT).

If an area is null (because it is defined at a location that does not exist for the containing area), this will be indicated as follows:

If an area defined on a FILE area has been assigned to a physical file, this will be indicated as follows:

If a SET AREA command has been issued to set the area as the default area for a particular function (e.g., MSG or COMMAND), this will be designated by a single letter following the semi-colon. For example,

indicates that the SYSMSG area has been set as the default area for all messages. Possible default function settings are: I (IDATA), O (ODATA), R I O (IODATA and REPROMPT), M (MSG), and C (COMMAND).

The output of a SHOW AREA command is in a form that may be saved and later input to re-create the area definitions and function defaults which were in effect at the time, provided that the same start-up state is in effect. The "IN areaname" prefix (e.g., IN ACTIVE) may be used with this command to cause the output to be directed to any area and/or device.

Note that the SHOW AREA command shows the true characteristics of an area as the system has interpreted them; this may be different from the characteristics originally specified on the DEFINE AREA command. For example, a request to define an area on CRT with dimensions of (100,100) is reinterpreted by the system to the maximum size of the CRT area.

3.5  Area Hierarchies And Overlapping Areas

Areas may be defined in relationship to other areas in one of two ways. An area can be defined on another area, forming a hierarchy, or two or more areas can be defined to overlap one another on the same containing area.

Take, for example, the following screen:

 +-----------------------------------------+
 |                                         |
 |                                         |
 |             A                           |
 |                                         |
 |                                         |
 |------------------------------+          |
 |                              |          |
 |             B                |          |
 |------------------------+     |          |
 |                        |     |          |
 |                        |     |          |
 |             C          |     |          |
 |                        |     |          |
 +-----------------------------------------+

These areas could be defined in two ways:

or

The first case places all areas on CRT -- these areas are overlapping areas. The second case places A on CRT, B on A, and C on B -- these areas are hierarchical. Whether your areas are overlapping or hierarchical can influence how display attributes are assigned to fields, how data is written to the device in the case of FILE devices, or how areas are written when an overflow occurs. It also makes a difference when areas are redefined -- redefining an area in a hierarchy may affect the actual definitions of other areas in the hierarchy.

Areas are also either "contained" or "containing". The containing area is the area upon which another area is defined. The contained area is the area being defined, the attributes of which are a subset of the containing area's attributes. (Areas can, of course, be both contained and containing when defined hierarchically; the containing area at the top level of the hierarchy will be the uncontained system-defined area representing the device.) The contained area cannot extend beyond the boundaries of the containing area; therefore, (rows,cols) only specifies the maximum size. Position (1,1) in the contained area corresponds to (srow,scol) in the containing area.

Appendix A contains details and examples of how size, placement, and attributes are affected when areas are defined in relationship to one another.

3.6  Zones

Zones are rectangles that you can define on an area and which belong to the area. Unlike areas themselves, zones can be used only for input -- you cannot write data to a zone. They are usually defined in a format, within the screen's output frame definition, using the $ZONEDEF function. Currently, they are used in Prism to identify portions of the user's terminal screen (CRT area) as significant places for user activity.

For instance, the application may define a zone such that if the user has positioned the cursor anywhere within it when the terminal screen is sent to the computer, the application will take some particular action, such as bringing up a box displaying choices the user can select for filling in the field contained by the zone. In other words, the zone provides a way of mapping data and/or meaningful locations on the screen to external Prism events. Specifically, if the user leaves the screen with the cursor in a zone, Prism will go to specific application-provided code for handling the situation. In this case, the $EVENTZONE variable contains the name of the zone that triggered the Prism "event". [See the "Prism Applications" manual to learn how to use zones in Prism.]

How to Define Zones

You define zones with the DEFINE ZONE command or the $ZONEDEF function. The SHOW ZONES command shows you which zones are currently defined. Additionally, you can use several "zcodes" with the $GETAREA function to determine what zone (if any) is associated with a particular location in the area.

The syntax of the $ZONEDEF function is:

and the syntax of the DEFINE ZONE command is:

where:

The $ZONEDEF function normally returns "0" (zero) when it succeeds; in case of error, a negative number will be returned. If the named area doesn't exist, the function returns "-1". If the zone name is null or longer than 16 characters, the function returns "-1".

Here are examples of the $ZONEDEF function and the DEFINE ZONE command:

Both these methods define a zone called Student.Name, 1 row by 50 columns, starting at row 3, column 1 of the Input.Screen area.

SHOW ZONES Command

Whether defined with the $ZONEDEF function or the DEFINE ZONE command, the zones are displayed in the SHOW ZONES command as if they had been defined with the command.

By default, SHOW ZONES displays zone information for all zones currently defined. You can limit the display to the zones of a specific area by naming that area in the ON option. To put the output from the command into an area, use the IN prefix, as in IN ACTIVE SHOW ZONES to put the output into your active file.

In Prism, when a PERFORM PRISM CHOOSE command has been used to generate a choice list in an area (in the main screen or in a Prism "subarea") Prism creates zones on the input fields used in the choice list. These zones have names that begin with "$", and they will be shown in your SHOW ZONES display, along with any zones that your application has defined. For example:

Here, MEALZONE was defined by the Prism application, but $CHOICE was defined by Prism itself.

Using $GETAREA to Find Zone Information

Given a specific column-row location on the area (such as the current cursor position), or the "zone number", you can get information about the zone it is in with the $GETAREA function. Here are the useful forms of the function for zones:

 - ZCOL -- the starting column of the zone
 - ZHEI -- the height of the zone
 - ZLEN -- the length (width) of the zone

Use $AREANAME or $SCRNAREA as the "areaname" when dealing with zones in Prism applications.

For all cases, $GETAREA returns a negative value if an error occurs:

For information about other uses of $GETAREA and full syntax details, see the next chapter. [See 4.3.]

Here are some important details about zones:

 - Because each area may have its own zone table, the same zone name may be  used  in  several
 areas at the same time.
 - Whenever an area is defined or redefined (i.e., with  the  DEFINE  AREA  or  REDEFINE  AREA
 command,  all  zone  information  is erased for all areas associated with uncontained areas
 affected by the define or redefine.
 - The BLANK command will discard the zone information for the specified area.  For  instance,
 BLANK  INPUT.SCREEN  would  discard  all  zones  defined on the INPUT.SCREEN area.  [See 4.6.3.]
 - Whenever an uncontained area is blanked, all zone information for all areas associated with
 that area is erased.  For example, BLANK CRT  will  discard  all  zones  defined  on  areas
 associated with the CRT area.
 - STORE AREA and RESTORE AREA will store and restore zone information as  part  of  the  area
 information.  [See 4.10.1, 4.10.3.]

3.7  SHOW DATS command

The SHOW DATS command is only used by systems programmers to examine a Device ATtributeS chain for areas like CRT.

4  Data Movement

As mentioned in Chapter 1, data is moved between SPIRES and a particular device by Device Services commands via a Device Services area associated with the device. Data is moved into and out of an area primarily by placing the "IN areaname" prefix before a SPIRES command either in a protocol or at the terminal. In addition, the $GETAREA, $PUTAREA, and $SETAREA functions provide status information and other ways of moving data into and out of areas. Transferring data to and from physical devices involves physical I/O operations, and is controlled with the READ, WRITE, and BLANK commands. The ASK AREA command provides a way to write data to the screen in full-screen applications and prompt the user for information.

The following diagram shows very simply how data is passed between SPIRES and the device.

+------+                               +------+                 +------+
|      | IN areaname <output command>  |      | WRITE areaname  |      |
|      |------------------------------>|      |---------------->|      |
|SPIRES|                               | AREA |                 |DEVICE|
|      |<------------------------------|      |<----------------|      |
|      | IN areaname <input command>   |      | READ areaname   |      |
+------+                               +------+                 +------+

When an output command is preceded by the "IN areaname" prefix, the resulting output is placed in the named area; that output is transferred from the area to the device via a WRITE command (whether that command is explicitly issued or happens automatically). The READ command is issued to transfer data from the device to an area; from there it is processed by an input command preceded by the "IN areaname" prefix.

This chapter describes these commands and how to control their actions.

4.1  The "IN areaname" Prefix

The "IN areaname" prefix is used when writing data to an area, or reading data from an area. The syntax is:

Options are:

 - OVERLAY: new data begins at (1,1) in the area; area is not blanked first.
 - CONTINUE: new data begins at (X,1) in the area, immediately following  any  previous  data;
 area is not blanked first.
 - CLR or CLEAR: this is the assumed default if neither OVERLAY or CONTINUE is specified,  and
 only applies to output direction; area is blanked first.
 - CLN or CLEAN: specifies that $RECSEP and ";" lines are not to  be  output  during
 multiple record output commands.  (If used with the BROWSE command, the CLEAN option causes
 SPIRES to not prompt the user "-MORE?", but to place only 10 values in the area.)

Direction is determined by the command following the prefix. Commands such as DISPLAY, TYPE, EXPLAIN, SHOW, and DUPLICATE are associated with the OUTPUT direction. Commands such as MERGE, ADD, and UPDATE are associated with the INPUT direction. When an area is specified for formatted input or output, the area dimensions are used rather than the frame dimensions of the format, so if the data overflows the area dimensions, you will get an S808 error.

For example, you might have the CRT area divided into four areas with the following commands:

You could then direct data to be placed in different parts of the screen by preceding your commands with IN ONE, IN TWO, IN THREE, or IN FOUR, such as IN THREE DISPLAY 15 or IN ONE SHOW SUBFILE INFORMATION. Or you can use data from different parts of the screen to add or update records with commands like IN ONE ADD or IN TWO MERGE 1234.

If the OVERLAY or CONTINUE options are not included with the "IN areaname" prefix for output commands, then the specified area is blanked prior to execution of the command. Blanking an area eliminates all foreground fields in the area leaving only background fields; OVERLAY and CONTINUE do not eliminate any fields already in the area.

If the "IN areaname" prefix does not precede a command that specifies the input or output of data, the default area for the command (which can be set by the SET AREA command) [See 3.3.] will be used.

In online SPIRES, there is no default IDATA or ODATA area; normally the Device Services processor is not activated unless an "IN areaname" prefix is used or the SET AREA command is issued. If an output command is issued and there is no default area for output (ODATA), the resulting data is sent directly to the terminal. [See 2.11.] An input command will attempt to move data from the active file into the data base.

Overlaying Data

When placing data into areas that have some space in common, it is important which area is filled first. If neither the OVERLAY nor CONTINUE option is used on the "IN areaname" prefix, data placed in an area will obliterate any data already placed in an area that occupies a common space. You can thus think of areas as being pieces of opaque paper laid on top of one another.

Let's say we have two areas defined on CRT as follows:

Area ONE occupies the top five rows of the CRT area, area TWO the top 10 rows. So area TWO overlaps entirely area ONE.

Now let's say we have two output data frames, each of which has two label-groups as follows:

Assuming that SET NOWRITE [See 4.8.] is in effect, if we issue the commands

we would get a screen that looks like this:

   1+-------------------------------------------+
   2|                                           |
   3|                                           |
   4|                                           |
   5|                                           |
   6|                                           |
   7|             elem c                        |
   8|                                           |
   9|             elem d                        |
  10+-------------------------------------------+

Area TWO completely overlaid area ONE, thus blanking out the data placed in area ONE by the first command. However, if we use the OVERLAY option after the "IN areaname" prefix or reverse the order of the commands as follows:

then our screen would look like this:

   1+-------------------------------------------+
   2|elem a                                     |
   3|elem b                                     |
   4|                                           |
   5|                                           |
   6|                                           |
   7|             elem c                        |
   8|                                           |
   9|             elem d                        |
  10+-------------------------------------------+

In this case, area TWO was filled first. Area ONE partially overlaid area TWO; it did not overlay the lower portion of area TWO.

4.1.1  The "USING frame" Prefix and XEQ FRAME Command

The "USING frame" prefix and the XEQ FRAME command are most frequently used in full-screen programming. They invoke specific format frames that move data into and out of areas according to the instructions found in the format frame. The direction is determined by the DIRECTION statement in the frame definition.

For example, assuming there is a format frame named OUT with DIRECTION=OUTPUT, a format frame named INP with DIRECTION=INPUT, and a device area named SCREEN, consider the following commands:

This is interpreted as: USING the OUT frame, place data INside the SCREEN area by displaying record 123.

This is interpreted as: USING the INP frame, take the data that is INside the SCREEN area and MERGE it into record 123.

Or,

will invoke the frame INPUTTER to process the data in the SCREEN area.

4.1.1.1  (The NODATA DISPLAY Option)

The NODATA DISPLAY option is added to the "USING frame" prefix when you wish to display a "blank" record. The format frame is executed, but no record is accessed from the data base. This means, of course, that no element values are displayed, but all values specified with a DEFAULT, TITLE, or VALUE statement will appear. The $NODATA flag variable is turned on while this format frame is executing, so you could alter format processing whenever the frame is executing under the NODATA condition.

If a DEFAULT statement is included in a label-group with no value (i.e., "DEFAULT;") the label-group will be executed and a field will be created of the length specified in a LENGTH or MAXROWS statement and filled in with the character set by the PADCHAR Uproc. In full-screen programming, this allows you to create an unprotected field on the screen so that the user can fill in a value for that element.

The NODATA DISPLAY option can also be used during Partial processing to create an empty structure display. The frame specified in the "USING frame" prefix must be a structure frame. See Section 5.8.3 for an example of applying Partial FOR processing to full-screen programming.

4.1.2  The Star (*) and Dash (-) Commands

The star (*) and dash (-) commands can be preceded with the "IN areaname" prefix to cause the comments specified with these commands to be sent to the specified area, which must be capable of receiving output (ODATA). The dash command is only allowed in protocols and is controlled by SET ECHO in XEQ-mode; it is not written to the area unless ECHO is set. The star command is unconditional.

For both commands, the data in the command line following the star or dash is broken into multiple lines if necessary. The default line length is the current value of $LENGTH or 160, whichever is smaller. If the specified area has a column width less than 160, then the line length becomes the area's column width. The data is broken at a blank if possible. The star or dash is not written to the area, only the data that follows.

4.1.3  Device Services Areas and Report Formats

The "IN areaname" prefix can only specify ACTIVE or a FILE area if the output is created by a report format. If you want a report to be sent to other areas, you must use the IN-AREA statement in the format. [See 4.11.]

4.2  The DUPLICATE AREA Command

The DUPLICATE AREA command allows the same data to be copied from one area to another. The syntax is:

The output data currently in "source-area" will be copied to "dest-area". If there is no "IN areaname" prefix, the DUPLICATE command functions with the default ODATA area (normally TER). Note that you can use the ACTIVE area with this command (e.g., IN ACTIVE DUPLICATE AREA source-area).

The ALL option will duplicate all the rows of the area regardless of the position of the last output row. This is important in situations where a large area (we'll call it LARGE) is overlayed at the end by a smaller area; if some data is put into the beginning of the large area, and some data is then been placed into the overlaying, smaller area, then DUPLICATE AREA LARGE will only duplicate the beginning portion of LARGE, and not the overlayed part. To be sure the entire area is duplicated, add the ALL option.

If "source-area" is defined on NULL, the command fails. The maximum line size that can be copied is 256 bytes; lines longer than this are truncated. The two areas may differ in size, but lines of an area will be truncated if "dest-area" is smaller in width than "source-area".

The DUPLICATE AREA command differs from the DUPLICATE option on the DEFINE AREA command [See 3.1.4.] in two ways. First, the DUPLICATE option specifies that the area is to be copied each time data is placed into it, whereas the DUPLICATE AREA command will copy the area only when the command is issued. Second, the DUPLICATE AREA command will only copy the data in "source-area"; attributes of that data (DISPLAY characteristics such as PROTECT, EMPHASIS and ALTCHAR levels, for example) are not copied as they are with the DUPLICATE option.

4.3  The $GETAREA Function

The $GETAREA function provides status information and data from device services areas. The syntax is:

where "code" represents the type of information requested (see below for possible values), and "n1", "n2", and "n3" are integers. If "code" is not included, OPEN is assumed. If no integer values are given, then either 0 or 1 is assumed depending upon the value of "code". $AREA is a valid alias for $GETAREA.

The function returns a value of "-1" if "areaname" is invalid or not found, and a value of "-2" if "code" is invalid.

When using $GETAREA in Prism applications, "areaname" can be $SCRNAREA or $AREANAME, when the $GETAREA function allows operations on contained areas. $AREANAME may be used in formats. It contains the name of the current CRT area and is set by formats when a frame is executed in a device services area. $SCRNAREA is maintained by Prism, and is available in formats and protocols. It contains the name of the currently active area.

Valid "code" values and the information provided by the function are:

In the following examples of $GETAREA, "x" can be one of these four codes:

Also, "n" is set to 1 as a minimum. If "n" fields cannot be found in "areaname", then the function returns a value of zero. Only fields that start in "areaname" are counted.

The following forms of $GETAREA are used with zones, described in detail in the previous chapter. [See 3.6.]

 - ZCOL -- the starting column of the zone
 - ZHEI -- the height of the zone
 - ZLEN -- the length of the zone

The following uses of $GETAREA are used only for the SBF device services area [EXPLAIN SBF AREA.]; other devices return 0:

Here is a simple example of how $GETAREA might be used:

4.3.1  The SHOW FIELDS Command

The command SHOW FIELDS will display basic information about all the fields in an area:

If no area is specified with the FOR option, the command shows information about all fields in the CRT area. The output from the command can be directed to the active file or to other areas with the "IN area" prefix.

The information shown by the SHOW FIELDS command includes a counter/identification number for each field, the same number that would be returned for that field by the $GETAREA command with the ALOC code. Also included is the starting row and column for the field, its length, its display characteristics and the value, if any, that is in the field.

Here's an example showing the first few fields from the data area on the "Select Options" screen in Prism's SETUP REPORT command.

4.4  The $PUTAREA Function

The $PUTAREA function provides a way of writing data to an area via the execution of a system function. [See the "Prism Applications" manual for examples of using $PUTAREA to write data to Prism input screens.] The syntax is:

"Areaname" must be valid for output (ODATA), must not be null, and must be completely defined.

"String" is the data value to be moved into the area; it cannot be null.

"Row" and "column" are optional, and must be within the boundaries of the named area. If neither row nor column are given, then the string is placed in the area as follows: if space remains on the current row, then the string is placed on that row with possible truncation if it does not entirely fit on the remainder of the row; if the row is full, then the next row is used beginning with column 1 (again with possible truncation). If the row is given but the column isn't, then column 1 is used.

The $PUTAREA function returns a negative integer (always "-4") if an error occurs; otherwise, the "string" is placed in the area at the given row and column (with possible truncation). The $PUTAREA function returns the field number, which can then be used in the $SETAREA [See 4.5.] function to set non-default attributes and is identical to the value returned by the $GETAREA function with the ALOC code. [See 4.3.]

If the field (i.e., "string") is being placed within an area for which device attributes are possible (e.g., CRT area, but not FILE area) then the attributes of the new field are set to the default for the area (any fields that occupied the space now containing "string" are eliminated, and the new field takes on the default attributes).

If "areaname" has been defined with the DUPLICATE option on the DEFINE AREA command, then $PUTAREA will also DUPLICATE to the proper area.

4.5  The $SETAREA Function

The $SETAREA function allows the device attributes (e.g., protection, alternate character set number, emphasis level, etc.) for a particular field in an area to be set explicitly to the default for the area or to be set to non-default attributes. [See the "Prism Applications" manual for examples of using $SETAREA (with $PUTAREA) in Prism applications.] The syntax is:

where "fieldnumber" is the same as the ALOC number returned by $GETAREA or the integer value returned by $PUTAREA. [See 4.3, 4.4.]

The "string1,string2,...stringn" parameters define the attributes to be given to the field. The attributes and their abbreviations are:

The valid "altchar-terms" are RED, BLUE, YELLOW, GREEN, CYAN, WHITE, PINK, NOCOLOR and RULING. [See 6.3.] The valid "emphasis-terms" are NORMAL, HIDE, REVERSE, BRIGHT and BLINKING. [See 6.2.] Both ALTCHAR and EMPHASIS must have integer values associated with them to be interpreted properly, unless the terms are used.

The allowed values for "field-term" are REQUIRED, OPTIONAL, ERROR, WARNING, TITLE, TEXT and DATA. These each represent a combination of attributes. For example, REQUIRED means UNPROTECTED, BRIGHT, UNDERLINE, YELLOW. [See 6.1.0 for descriptions of each of them.]

If no "string" parameters are given, then the attributes of the field are reset to the default for the area. If any attributes are given, then all attributes are reset to the default for the area before the newly-specified attributes are applied. The "string" parameter may be a variable representing a series of attributes. For example, if X = 'A3,E16,UND' then

would be equivalent to

The function returns a negative integer (always "-1") if an invalid operation is specified, or if device attributes are not possible for the device.

Note that only foreground fields can have attributes set by $SETAREA. [See 6 for more details about field attributes.]

4.6  The READ, WRITE, and BLANK Commands

The READ, WRITE, and BLANK commands usually initiate physical I/O operations causing data to be moved between areas and external devices. These I/O actions take place automatically in the default Device Services environment, but they can be controlled by setting NOWRITE and NOREAD, in which case read and write operations only occur upon explicit command. [See 4.8.]

4.6.1  The WRITE Command

The WRITE command is used to write data from an area to a device. The syntax is:

where "areaname" is any area capable of output (ODATA). If "areaname" is not included, the default ODATA area is used. [See 4.6.4.]

Data in the area is written to the device that corresponds to the uncontained area on which the area is defined, and the area is "flushed," that is, all the data in the area is copied to the device. An image of the data remains in the area until more data is placed in that area with the "IN areaname" prefix, or a BLANK command is issued. So if you issue multiple WRITE commands, the data in the area would be copied to the device multiple times. If there are multiple areas defined on the CRT, HLIO, HLCA, or NIO areas, a WRITE command will write the entire uncontained area.

A WRITE command resets the "row" pointer to the first row of the area. So use of the CONTINUE option [See 4.1.] after a WRITE command causes data to be placed in the area beginning at the first row.

If the WRITE command is issued without either the READ option or the REPROMPT option [See 4.7.] then any fields marked as "changed" by an input format frame will remain marked.

Areas contained by FILE, MEM, or TER may be written separately; a WRITE command issued for one of them does not automatically write every area defined on the uncontained area. Writing to disk files from the FILE area is always buffered so that actual I/O is optimized, but this extra step is handled completely by Device Services. WRITE commands are ignored for the MEM and NULL areas.

See Section 4.7 for a description of the options for the WRITE command.

4.6.2  The READ Command

The READ command will move data from a device (a terminal screen or disk file, for example) into an area. Its syntax is:

where "areaname" is an area capable of input (IDATA). If "areaname" is not included, the default IDATA area is used. [See 4.6.4.]

When a READ command is issued, all lines of a fixed-dimension area will be read, but only a single line of an indefinite capacity area [See 2.13.] will be read.

In the case of the CRT area, only unprotected fields are read from the device; any changes made by the end-user to protected fields are discarded. With conversational devices (i.e., terminals) a READ command will always cause the area to be written to the device first, and the program will then wait for user input before actually reading the contents of the terminal screen.

For FILE areas, the file is read sequentially, although the amount of data read from a file can be controlled with the CURSOR option. [See 4.7.2.] READ commands are ignored for the MEM, NULL, and TER areas.

See Section 4.7 for a description of the options for the READ command.

4.6.3  The BLANK Command

The BLANK command will clear all data from an area or a device. The syntax is:

EXTERNAL (the default) clears protected fields and unprotected fields from both the external device and its associated areas. For an area defined on FILE, HLCA, or HLIO, this option causes only the area to be cleared; it does not affect the physical file.

INTERNAL clears protected and unprotected fields from the area only, not the device. For an area defined on FILE, HLCA, or HLIO, the EXTERNAL and INTERNAL options have the same effect.

UNPROTECTED causes data to be erased only from unprotected fields in both the area and the external device. This applies only to areas defined on CRT or TER.

A BLANK automatically occurs when an implicit WRITE occurs. [See 4.8.1.] BLANK commands are ignored for the NULL area.

See Section 4.7 for a description of the options for the BLANK command.

4.6.4  I/O Commands With No Area Specified

The READ, WRITE, and BLANK commands may be issued without specifying an area name. A comma must be used to separate any options from the command to prevent the first option from being interpreted as the area name. For example,

The default IDATA area (for READ or BLANK) or ODATA area (for WRITE) is used. These default areas are established by the SET AREA command [See 3.3.] or by the HLI. [See 8.] If no default area is defined, these I/O commands are ignored by SPIRES.

4.7  Options for the READ, WRITE, and BLANK Commands

The READ, WRITE, and BLANK commands may all be followed with the ATTN, CURSOR, and NULL options. The WRITE and BLANK commands may also include the READ option. The WRITE command may also include the REPROMPT option. The following sections describe these options.

4.7.1  The ATTN Option

The ATTN option can be added to the READ, WRITE, and BLANK commands. It is in the form "ATTN = 'statement'" and causes the 'statement' to be executed when the action is terminated by ATTN. (Note that unless the statement is a single word, like RETURN, it must be enclosed in apostrophes.) If the ATTN clause is not present, the system behaves as if a BREAK XEQ has been issued if the ATTN key is pressed. In this case, no test is made to see if any data has been received; all data is considered to be invalid.

For FILE areas assigned to an input file, the ATTN option can be used on the READ command to detect the end of the file. When the end of file is detected, the "statement" in the ATTN option is executed.

4.7.2  The CURSOR Option

The CURSOR option may be added to the READ, WRITE, and BLANK commands. It specifies the placement of the cursor after the I/O operation is performed. Cursor parameters are interpreted on devices that have computer controllable cursors, and when using areas that are of fixed line capacity. The cursor will be placed in the next unprotected position of the area if the specified location is protected. If there are no unprotected fields in the area in which the cursor is positioned, the cursor is placed at the requested position in the protected area. The cursor option has the following forms:

 - CURSOR -- The cursor will be positioned at  (1,1)  of  the  area.   This  is  the  default.
 - CURSOR * -- The cursor will remain where it happens to be at the start of the READ,  WRITE,
 or BLANK action, unless it was in a protected area, in which case it will move to the start
 of the next unprotected field.
 - CURSOR(row,col) -- The cursor will be positioned at the specified row  and  column  of  the
 area.
 - CURSOR areaname2 -- The cursor will be positioned at (1,1)  of  areaname2,  which  must  be
 contained by the original area.
 - CURSOR areaname2(row,col) -- The cursor will be positioned at  the  specified  position  in
 areaname2, which must be contained by the original area.

For FILE areas assigned to an input file, "CURSOR (n)" can be used to read only "n" rows instead of reading the entire file. For example, the following commands will fill only the first five rows of the area with input data from MYFILE:

          DEFINE AREA BOX (10,80) ON FILE
          ASSIGN AREA BOX TO MYFILE INPUT
          READ BOX CURSOR (5)

4.7.3  The NULL Option

The NULL option may be added to the READ, WRITE, and BLANK commands. It is in the form "NULL = 'statement'" and causes the 'statement' to be executed if the READ, WRITE, or BLANK command specifies an area contained by the system area NULL, or if the area has been reduced to zero dimensions because of its placement on higher areas, or if no unprotected data is present. (Note that unless the statement is a single word, like RETURN, it must be enclosed in apostrophes.) If the NULL clause is not present, the action will terminate normally under these conditions.

4.7.4  The READ Option

The WRITE and BLANK commands may also be followed with a READ option. The syntax for this combination is:

where "areaname" is the name of any area that is capable of conversation. The READ phrase indicates a conversational I/O operation, where data is displayed on a device, modified or augmented by the user, and returned to the area that was originally written. Using the READ option is more efficient than issuing a separate READ command, because it involves only one terminal I/O. See the sample application in Chapter 5 to see when this combination is used.

4.7.5  The REPROMPT Option

The REPROMPT option is available on the WRITE command only when the area being written is the CRT area or one defined on the CRT area with IODATA capability.

Its purpose is to rewrite the CRT screen when an error has been detected by an input format frame. REPROMPT is like READ in that it initiates a read operation from the terminal. But unlike READ, "changed" fields are remembered through multiple reprompts.

A reprompt can be done from either 1) the command level, using the REPROMPT option on the WRITE command, or 2) from within a format, via the REPROMPT Uproc. When done from a format, you cannot control cursor positioning; the cursor will be placed at the beginning of the first unprotected field on the CRT area. If you wanted to position the cursor at the first field that contains an error, you must exit the format and issue the WRITE CRT REPROMPT command with the CURSOR option.

Using REPROMPT at the command level involves more code than the REPROMPT Uproc used in a format frame, but offers you two advantages:

 - You can control the positioning of the cursor.
 - Because you leave the format, you can do things on the command level before the  screen  is
 rewritten, such as placing data in another area.

The following protocol code will first write the screen for the user to modify. The areas named UPDATE and COMMAND are defined on CRT. If an error is detected by the format, the protocol will rewrite the screen, positioning the cursor at the appropriate place.

   WRITE CRT, READ CURSOR (5,5) ATTN = 'JUMP ATTN'
   ++UPDATE
   /IN UPDATE, USING MERGE, MERGE $KEY
   IF $ABORT THEN LET MESSAGE = 'ERROR FOUND'
   THEN IN COMMAND, XEQ FRAME COMMAND
   THEN WRITE CRT, REPROMPT CURSOR ($EROW,$ECOL)
   THEN JUMP UPDATE

The format frame named MERGE contains a label-group at the end that contains the statement

so that if an error is detected, the format is exited and execution returns to the protocol, which sets a MESSAGE variable, places data in an area named COMMAND (to display the MESSAGE) and then writes the CRT screen. The protocol then returns to the ++UPDATE label statement and attempts to merge the record again. [See 5 for an example of REPROMPT being used as a Uproc in a format frame as part of a complete full-screen application.]

4.8  The SET NOWRITE and SET NOREAD Commands

By default, READ and WRITE actions occur under certain circumstances. When data is placed in an area, an implicit WRITE command will transfer the data to the external device. Or when an area fills with data, a WRITE will occur. When data is needed in an area by an I/O command, a READ action is generated for some areas.

In some applications, however, this condition is not desirable (e.g., when writing several areas to a CRT screen). You, as the programmer, may want to carefully control when data is moved between device and area. To turn off the default READ and WRITE actions, the commands SET NOREAD and SET NOWRITE are used. When these commands are in effect, data is transferred between area and device only upon an explicit WRITE or READ command.

The syntax is:

SET NOWRITE and SET NOREAD establish a global setting for every area defined. The "IN areaname" prefix can be added to change the setting for a single area, in which case the individual setting will override the global setting. Global NOWRITE does not affect MSG areas. [See 4.8.1.]

4.8.1  Controlling WRITE Actions

When an area becomes filled with data, a WRITE action will occur to clear the area for more data unless NOWRITE is in effect for that area. [See 4.8.] In other words, data will be written to the device when the area (and any overflow areas) becomes filled. When an implicit WRITE occurs -- as the result of an area filling up -- a BLANK will also occur. An explicit WRITE command (one that you actually issue) will not blank the device. For this reason, to have the most control over WRITE actions, you would want to SET NOWRITE and define overflow areas [See 3.1.3.] so that data may not be lost.

Automatic WRITE of an area takes place for an output command when any of the following conditions occurs:

 - the command completes, and the area named in the "IN areaname" prefix  has  local
 SET WRITE in effect, or global SET WRITE is in effect.  If the output command completes and
 local  SET  NOWRITE is in effect, or there is no local setting and global SET NOWRITE is in
 effect, then nothing is written or blanked.
 - the output command attempts to send data to a row beyond the last row of the area named  in
 the "IN areaname" prefix when no overflow area has been defined.
 - the output command attempts to send data to a row beyond the last row of the last  overflow
 area  in  a  chain  of  overflow  areas  leading  from  the  area  named  in  the  "IN
 areaname" prefix.

The area written depends upon overflow areas. If no data has been placed into an overflow area, or no overflow area is defined, then the area named in the "IN areaname" prefix is written. If data has been placed into an overflow area, then the containing area associated with the area named in the "IN areaname" prefix is written. It is assumed all overflow areas are contained within the bounds of the containing area.

An automatic WRITE of the MEM area results in the data being lost. The area is "written" in the sense that the area buffer is flushed, but because there is no physical device for it to be written to, it is simply thrown away.

Areas assigned the MSG function are always written whenever a system message is sent to them unless NOWRITE is in effect for that particular area. Global NOWRITE does not affect MSG areas. Therefore, the only way to prevent messages from writing the area is to issue the command

4.8.2  Controlling READ Actions

For all areas, with the exception of FILE or FIL2, a READ command must be explicitly issued, regardless of a global SET READ. When a READ command is issued, all lines of a fixed-dimension area will be read, but only a single line of an indefinite capacity area [See 2.13.] will be read.

For the FILE or FIL2 areas, if SET READ is in effect, data will be read from the device into an area whenever data is needed by an I/O command. If SET NOREAD is in effect, READ commands must be explicitly issued for FILE or FIL2 areas. File devices are not conversational; therefore, READ and WRITE commands cannot be issued for the same file area unless the file is first closed and then re-opened. [See 7 for details about using the FILE or FIL2 areas.]

4.9  The ASK AREA Command

The ASK AREA command provides a way to prompt the user for information in a full-screen environment. In this way, it is similar to the ASK command in a line-by-line protocol. It is also similar to the WRITE CRT READ command in that it writes the contents of the CRT area to the screen and when the user presses the ENTER key, reads data from the screen. The ASK AREA command creates an unprotected field in the area for the user to enter a response, and may optionally create a protected field contiguous to the response field and containing a specified prompt. When the user presses the ENTER key, the response field is read and its contents placed in the $ASK variable.

The syntax is:

where "area-name" specifies the name of the area within which the fields will appear. It must be an area capable of IODATA, and is typically the CRT area or an area defined on CRT. If the area has field attributes, the prompt and response fields will have these attributes. The prompt field is always protected; the response field is unprotected unless the area is PROTECTED. (But because the response field is intended for the user to type in a response to the prompt, it would not be desirable to use this command in area that is completely protected.) The cursor is positioned at the beginning of the response field. The fields created by this command are completely independent of any fields created by a format executed within the same area. If data is already in the area, the fields created by the ASK AREA command will overlay it.

The "location" is any combination of up to three numbers separated from each other by commas, and optionally surrounded by parentheses. The three integers represent row, column, and length, in that order. If row or column is not included, 1 is assumed. If a length specification is not included, the remainder of the row beginning at the specified column is used. The length value includes both the prompt and the response fields.

UPPER specifies that the user's response is to be converted to upper case before being placed in the $ASK variable.

The PROMPT statement specifies the string to be placed in the prompt field. The prompt is always followed by a single blank; the length of the prompt string plus this blank determines the length of the prompt field. It is always protected. If no PROMPT string is given, the entire length described by the location parameter will be a single unprotected field.

The DEFAULT statement allows you to specify a default value that will appear in the response field and be accepted as the response value if the user presses the ENTER key without typing in a different value. If there is a DEFAULT, and you only type over part of it, the response will be the combination. For example, if the DEFAULT was "None" and you typed "12", the response would be: "12ne", where "No" was replaced by "12".

NOECHO specifies that the user's response is not to be displayed as it is input. Any supplied DEFAULT value is also not displayed, so you must either type nothing to get the DEFAULT, or type over the entire DEFAULT to replace it.

The UPPER, PROMPT, DEFAULT, and NOECHO options may occur in any order following any supplied "location" information.

The ATTN statement works like the ATTN option of the READ command -- it specifies a command to be executed if the ATTN key is pressed in response to the prompt. If included, the ATTN statement must be the last option of the command. If not included, pressing the ATTN key causes a BREAK XEQ command to be executed.

For example, take the following command:

This will create a field in the CRT area 60 characters long, beginning in column 3 of row 2. The string "Input:" followed by a single blank will appear in the first seven characters of the field, and the default value "None" will appear after this, with the cursor positioned in column 8. The user has a total of 53 spaces to type in a different response or can accept the response "None". If the user presses the ATTN key, the command "JUMP END" will be executed and $ASK will be set to null. Otherwise, $ASK will hold the value in the response field.

4.10  Storing Areas

There are several occasions when you have data in an area that you will want to use again later, but do not want to access the data base again to recreate the area's contents, or may not be able to recreate the area's contents. There is a facility that allows you to save the current contents of the area in core so that the contents can be restored to the original area when you want to display it again.

A common application of this is in full-screen programming. Let's say that you have placed a record in the CRT area (or an area defined on CRT) and written it to the screen, and the user has made modifications that resulted in error messages. The user then asks for a help or explain screen. You want to place the help or explain data in the area, write that area to the screen, and then be able to restore the original screen with the user's modifications on it. This can be done with the STORE AREA and RESTORE AREA commands. This section describes how to use these commands, and how to use the SHOW STORED AREAS command to see what areas are currently saved in core.

4.10.1  The STORE AREA Command

The STORE AREA command stores the entire uncontained area associated with the area specified in the command. The syntax is:

where "areaname" is any valid area name. If it is a user-defined area, the system-defined uncontained area upon which it is defined will be stored.

The NAMED option allows you to specify a name for the stored area. Note that this does not rename the area, but only names the stored version of the area. The names of stored areas do not have to be unique. If this option is not included, the stored area will be named using the name of the uncontained area.

Each time you issue the STORE AREA command, the current contents of the uncontained area are stored in core. The data in the area is not simply copied, but is actually moved, and if you do not include the NOUPDATE option, the uncontained area is blanked internally. The NOUPDATE option allows you to copy the contents of the area without blanking the uncontained area.

The new stored version does not replace any previously stored version; it simply pushes another version onto the stack of stored areas, that is, each time the command is issued, a new stored version is created.

You cannot store a FILE area while any assignments exist. All assigned areas must be closed before you can issue the STORE command.

4.10.2  The SHOW STORED AREAS Command

The SHOW STORED AREAS command either issues the message "-No stored areas", or lists the RESTORE AREA commands that would restore all stored areas beginning with the last one placed on the stack.

4.10.3  The RESTORE AREA Command

The RESTORE AREA command takes the most recently stored version of an area and replaces it in the area. It re-creates the area as it was when the STORE AREA command was issued. It also removes that version from the stack of stored areas.

The syntax is:

where "areaname" is the name of the area or the name of the uncontained area on which it is defined. When the command is issued, SPIRES searches the list of stored areas beginning with the last one that was stored, looking for a stored area belonging to the uncontained area. If the NAMED option is given, the stored area must have the given name; otherwise the first (i.e., latest) stored area belonging to the uncontained area is used.

If a version of the area cannot be found in the stack of stored areas, or the uncontained area has changed in size, then the command is terminated. Otherwise, the uncontained area's content is replaced by the stored area information. The stored version of the area is then released.

By using the NOUPDATE option, you can use the RESTORE AREA command to release stored areas from the stack without affecting the current contents of the uncontained area.

If you issue a RESTORE AREA command without specifying a name, the most recently stored area will be retrieved, regardless of its stored name.

For example, consider the following commands:

You now have three copies of the area, each version containing different data. If you then issue the command

you get the second version of CRT because the RESTORE AREA command explicitly requests the stored area named Y, containing record 2. If you then issue the command

you get the last version that was placed on the stack with the name "X" (containing record 3), the first one shown by the SHOW STORED AREAS command above. If you issue another RESTORE AREA CRT NAMED X, you then get the third area in the list, which is the first area stored with the name "X" (containing record 1). Each time a RESTORE AREA command is issued, the version of the area is discarded after it is restored.

You cannot restore a FILE area while any assignments exist. All assigned areas must be closed before you can issue the RESTORE command, unless you are using the RESTORE command with the NOUPDATE option to simply release stored areas from memory.

4.11  Directing Data to Multiple Areas From a Format

You can direct output to Device Services areas from within a format. This allows you to send data to more than one area at a time, and also allows you to send output from report formats to all areas. By putting the IN-AREA statement in either the frame declaration section or a label group that also includes an IND-FRAME statement, you specify the area to which the data from that frame is to be placed.

The IN-AREA statement is in the form

where "areaname" is the desired destination of the data. The area named must be already defined using the DEFINE AREA command. [See 3.1.] You cannot specify ACTIVE in this statement. If you want to use the active file, include the IN ACTIVE prefix on the output command.

For more details about using the IN-AREA statement (particularly as it applies to report formats), see the Formats manual, or EXPLAIN IN-AREA STATEMENT.

Example

The following example shows how you might send data to two areas using a single format. The format SALREP is set up to direct output to two areas by including an IN-AREA statement for each frame. The protocol shows that the areas are to be defined, assigned to a file if necessary, and then written and closed outside of the format's execution.

The Format

ID = GQ.BEC.SALREP;
MODDATE = TUES. JAN. 3, 1984;
DEFDATE = TUES. JAN. 3, 1984;
FILE = GQ.BEC.SALARY;
RECORD-NAME = REC01;
FRAME-ID = DISPLAY;
  DIRECTION = OUTPUT;
  FRAME-DIM = 0,80;
  LABEL = NAME;
    GETELEM;
    START = 1,1;
    PUTDATA;
  LABEL = JOB.TITLE;
    GETELEM;
    START = 2,1;
    PUTDATA;
  LABEL = YEARS.EMP;
    GETELEM;
    START = 2,40;
    INSERT = 'YEARS = ';
    PUTDATA;
FRAME-ID = SALARY;
  DIRECTION = OUTPUT;
  FRAME-DIM = 0,80;
  LABEL = NAME;
    GETELEM;
    START = 1,1;
    PUTDATA;
  LABEL = SALARY;
    GETELEM;
    START = 2,1;
    PUTDATA;
FORMAT-NAME = SALREP;
  FRAME-NAME = DISPLAY;
    FRAME-TYPE = DATA;
    IN-AREA = DISCRT;
  FRAME-NAME = SALARY;
    FRAME-TYPE = DATA;
    IN-AREA = DISFILE;

The Protocol

DEFINE AREA DISCRT (20,60) ON CRT
DEFINE AREA DISFILE (20,80) ON FILE
ASSIGN AREA DISFILE TO SALFILE REPLACE
SET NOWRITE
SELECT SALARY
SET FORMAT SALREP
DISPLAY 1
WRITE DISFILE
CLOSE AREA DISFILE
WRITE CRT

The data from the frame DISPLAY will be sent to the DISCRT area and written to the terminal screen. The data from the frame SALARY will be sent to the FILE area DISFILE and written to the file SALFILE. This is all accomplished with one execution of the format.

5  Full-Screen Programming

5.1  Introduction

In a full-screen application, entire screens full of information are communicated between the terminal and the computer with a single read or write operation. For data entry, instead of collecting lines of data into WYLBUR, transmitting each line with the RETURN key, the user types data in predefined places on the terminal screen. After completing the screen, the user presses a key (either the ENTER key or the RETURN key) and the contents of the terminal's screen go to the computer.

There are several advantages to this kind of data entry. Entry and modification of data is not done with computer software such as WYLBUR, but is done locally at the terminal using the terminal's built-in editing features. The terminal screen can be formatted for simpler, more accurate data entry. For example, certain parts of the screen can be used for titles and messages, and these parts can be protected from being overwritten by the user. Or fields can be emphasized by making them brighter or dimmer than the data being typed by the user, or they can be made to flash. It is also possible to use a special character set called the "ruling font" to draw outlines for forms or boxes on the screen. The programmer's job can be easier, too, especially when writing merge formats for complex records.

This chapter will provide you with an introduction to the facilities available for full-screen programming in SPIRES. It also illustrates their use with a simple application. Note that before you can run a full-screen application, SPIRES must know what kind of terminal you are using. This is done by issuing the SET TERMINAL command before calling SPIRES. See Chapter 6 for more details.

5.1.1  Using the Terminal

In a full-screen application, input is read from the terminal's buffer (memory) instead of the keyboard. The data stored in this buffer is displayed on the CRT screen. All changes are made to the contents of this buffer, using special keys and functions. Thus, editing may be done by the terminal rather than the computer.

The keyboard for each terminal is different, so refer to the operating instruction book for specific information on the use of the keys. But a general description of some of the more standard keys follows:

 - TAB Key.  The TAB key is used to move the cursor to the  next  unprotected  field.   Note
 that  the  TAB key can only move across a row, moving to the next row only after the last
 unprotected field on the current row; it does not move vertically.
 - Cursor Position Keys (Arrows).  The cursor position keys are  used  to  move  the  cursor
 around   the   screen.    The   action   of   moving   the  cursor  with  these  keys  is
 "non-destructive."  This means that data over which the  cursor  moves  is  not
 changed; this is unlike the action of the BACKSPACE and SPACE keys in WYLBUR, which cause
 the erasure of the data over which they space.
 - ENTER Key.  On some terminals, the ENTER key is used to  transmit  the  contents  of  the
 screen  to the computer.  For the most part, terminals not run in Model Terminal mode use
 the ENTER key in this manner.  On Model Terminals, the ENTER key should not be used.  See
 Chapter 6 for more information.
 - RETURN Key.  On Model Terminals, the RETURN key transmits a screen full of information to
 the computer.  On terminals not run in Model Terminal mode, the RETURN key is meaningless
 -- it moves the cursor to the next line, at either column 1, which is  always  protected,
 or the first unprotected field.  See Chapter 6 for more information.

Some terminals (in particular VT100-type terminals) have a keypad to the right of the main keyboard with additional keys that can be used in editing. [See 6.7.1.]

5.1.2  The Components of a Full-Screen Application

A full-screen SPIRES application is made up of several pieces:

 - File Definition-- defines the data to be stored.  The structure of your data base  and  its
 file definition is not dependent upon whether your online functions will be in line-by-line
 mode  or  full-screen mode.  A full-screen application can be written for any existing data
 base.
 - Format -- controls the formatting of data  within  Device  Services  areas.   It  generally
 contains several frames, each of which serves a different purpose, such as command parsing,
 record display, or record input.
 - Protocol -- invokes the format frames, controls the  movement  of  data  to  and  from  the
 screen, and provides an interface with the user.
 - Vgroups -- defines variables that can be  shared  between  the  format  and  the  protocol.

The most important thing to understand is how the various components of the application communicate with one another. The following drawing illustrates how an application works:

                 +------------------------------------------+
                 |                                          |
                 |                 PROTOCOL                 |
                 |                                          |
                 +------------------------------------------+
                      |       |                |
                     4A       |                |
                      |       |                |
    +----+       +--------+   |   +--------+   |   +--------+       +----+
    | FD |<-4B-->|        |<--3---|        |<--2---|        |<--1---|    |
    |    |<-4C---| FORMAT |---5-->|  AREA  |---6-->| SCREEN |---7-->|USER|
    | DB |       |        |       |        |       |        |       |    |
    +----+       +--------+       +--------+       +--------+       +----+
    FD = File Definition
    DB = Data Base

At this point, communication between the format and the protocol can take one of several directions:

After one of the above steps occurs:

Variables

Most of the "work" of a full-screen application is done by the format; that is, the actual manipulation of the data is done within a format frame. The protocol controls the execution of the format frames and issues Device Services commands to move data to and from the terminal screen. But information must be passed between the format and the protocol and that's where global variables come into play. They "carry" pieces of data from one portion of the application to another.

A vgroup definition names and describes a set of variables to be used throughout a session. The definition is added to the system subfile named VGROUPS, and compiled. See Section 4.2.2 in "SPIRES Protocols" for details on defining a vgroup.

Once your vgroup is defined and allocated you can assign values to these variables with the LET command; these values can be used by either the format or the protocol. For example, an executing format frame might set the value of a variable as the result of its execution, and this value might then be picked up by the protocol and used to control further processing by determining a point to branch to. See Section 5.5.2 for complete details on how this works.

5.1.3  Device Services Areas and Formats

Before beginning your design, you need to understand the relationship between formats and device services areas. Generally, a format will place data in an area or read data from an area; the area's name is specified by the "IN areaname" prefix. Certain characteristics are controlled through a combination of format statements and area definitions, so that, for example, a single format frame can be used with different areas to produce different results.

Areas are defined on the CRT area (the terminal screen) for full-screen applications. [See 2.1.] Different areas are defined to contain logical portions of the data being processed. These segments are not individual data items, but groups of data items that make up a logical unit. For example, one area might be defined to be the space on the screen where records will be displayed, and another area might be defined to hold status information and command data. Or you might have two areas defined to hold two different types of record displays. Or different areas might be defined on top of one another (that is, occupying the same physical area of the CRT screen) with different area attributes to be used at different times.

Each area will contain fields that are defined by a format frame. A format frame defines a two-dimensional space into which values will be placed when a record is processed (or from which they will be read by an input frame); the label groups of a frame contain the instructions on how to place (or obtain) the record element values within this space. The boundaries of the format's "data area" are specified by the FRAME-DIM statement. When this frame is written into a device services area, the data is placed in the device services area named in the "IN areaname" prefix, beginning on row 1, column 1, of the area.

For example, "IN SCREEN, USING XYZ, DISPLAY 45" places the specified record in the area named SCREEN according to the format frame XYZ. If SCREEN is defined with this command:

and the XYZ format frame has a "FRAME-DIM = 10,60" statement, element ONE is defined with "START = 1,1", and element TWO with "START = 5,40" and "UPROC = SET ADJUST RIGHT", then element ONE would appear on the CRT on row 5, beginning in column 1, and element TWO would be on row 10, ending in column 60.

The frame dimensions of the format do not have to match the dimensions of the device area, but must be containable by the area. For example, if the area has dimensions of 3 by 80 and the format tries to fill 4 rows or go beyond 80 columns, an error will occur.

You can also run into trouble by setting the frame dimensions higher than needed for the data if you plan on doing multiple record output to areas. When a frame is executed in an area, the space specified by the frame dimensions is taken up in the area buffer. This means that if you want to output multiple records (with a TYPE command, for example) the frame dimensions must be set as close to the actual requirements as can be determined, because each time a record is to be displayed in the area, SPIRES checks to see if the complete format buffer (i.e., the space defined by the frame dimensions) will fit in the space left in the area; if not, the area is flushed.

5.1.3.0  (Placing the Fields Within the Area)

Deciding where to place the fields is largely one of aesthetics and function. How do you want the data to appear to the user? Should certain pieces of data be grouped together on the screen? What order of elements is best for input? For display? You should consider what the user is most likely to be updating and place all these data elements together on the screen. You should also reserve space for error messages near or next to each element field.

The only thing you have to remember when placing the fields within the area is that you must leave one blank space in front of every field to hold the Field Attribute Character (FAC), which SPIRES places in front of each field. This allows SPIRES to hold information about display attributes for each field. This does not need to be done for the first field on every row, because the first physical column of the screen is always reserved by SPIRES to hold FAC information. [See 6 for information about display attributes.]

The following drawing illustrates the layout of a basic screen that might be used for an address file:

     +--------------------------------------------------------------+
     | Status                                                       |
     | Message                                                      |
     | Command                                                      |
     |--------------------------------------------------------------|
     |                                                              |
     |    ___ NAME: _________________________________  ID: _____    |
     |                                                              |
     |    ___ ADDRESS: ______________________________               |
     |                 ______________________________               |
     |                                                              |
     |    ___ CITY: _________________________________               |
     |                                                              |
     |    ___ STATE: _____        ___ ZIP: __________               |
     |                                                              |
     |    ___ PHONE: ________________________________               |
     |                                                              |
     |                                                              |
     |                                                              |
     |                                                              |
     |                                                              |
     |--------------------------------------------------------------|
     | System Messages                                              |
     +--------------------------------------------------------------+

This screen would probably have four areas defined for it:

The top three rows are designated as the COMMAND area. The BGPROTECT attribute specifies that all background fields in the area are to be protected, but allows an executing format to protect or unprotect any foreground fields in the area. The next 20 rows on the screen will be defined as the INPUT area, here again with the BGPROTECT attribute. The DISPLAY area occupies the same 20 rows as INPUT, but is defined with the PROTECT attribute, so that all fields will be protected from user modification. The bottom row is an area named SYSTEM.MES that is given the MSG function so that all system messages can be sent there -- this is particularly useful for debugging the application during development; data cannot be written to this area by a format frame. [See 3.3 for more details about MSG areas.] Remember that this arrangement of areas and fields is not prescriptive; this example is simply a fairly standard, straightforward way of defining a screen.

The placement of data in the COMMAND, INPUT, and DISPLAY areas will be controlled by format frames. The titles (i.e., NAME:, ADDRESS:, etc.) are specified with TITLE or VALUE statements, the position of the data values (i.e., the underscores following the titles) is determined by START and LENGTH statements. The underscores preceding the titles represent fields to contain error statements; these fields are defined by the ESTART and ELENGTH statements and the error values themselves are specified with a $MSG proc in the format or filedef or a SET UCODE Uproc.

5.2  Designing An Application: An Example

Since learning by example is the best method, we have included here a sample application, but the choices made here are by no means the only way to design and implement a full-screen system in SPIRES. Because SPIRES is a generalized system, your application can be structured just about any way you want. There are no requirements that certain areas be used for certain types of display, or that areas be named according to any conventions.

We suggest that for your first application you use the sample protocol included in this chapter and modify it for your own needs. This way, you can learn how things work without having to write the code from scratch. In other words, you can do things before you completely understand how to do them. As a matter of fact, most experienced full-screen programmers work from previous applications, simply modifying them to suit the needs of the new application -- this is the "cook book" approach. Because so much of full-screen programming is formulaic, this approach is time-honored and efficient.

This section describes the decisions that we made about our application before we started coding it. Every application will be different, of course, but the process will always follow the same basic steps as outlined here. For our application, we will be using a subfile of movie reviews, selectable as MOVIES. See section 5.9.4 for the file definition.

5.2.1  The Data Base and the On-Line Features

Deciding just exactly what you want your application to do is probably one of the hardest parts of a project, and, unfortunately, this manual (or any other manual) can't help you with that. You must decide how your data is to be organized, how it is to be presented to the user, and how the screen is to look, that is, what information you want to appear where.

You must also have a clear idea of what the user will be able to do. Will they only be displaying records by key value, or searching indexes? Will they be able to update existing records? And, if so, will they be locating these records by key value or by indexes? How much assistance do they need? What are the capabilities of the terminals to be used (if known), and do you want to use special display characteristics?

Our sample application is going to be simple, but will provide the following functions:

5.2.2  Functions and Commands

Now that we have decided what functions our application is to serve, we are going to design a command language to serve these functions. This language will be the set of instructions that the user will have to manipulate our application. In turn, our code will interpret these commands into SPIRES commands. Our command language will be application-unique, so may include any commands we desire. We may use the same verbs and syntax as any SPIRES (or WYLBUR or MILTEN, etc.) commands, but they will function as we have defined them. All other system commands will be invalid for the user during a session.

Command processing can be done using one of two general methods: an input format frame or the ASK AREA command. With either method, a command is entered by the user in a command field, which is an unprotected field somewhere on the screen. That field is read from the screen, and your application must then parse the command using format code or protocol code, or a combination of both. The parsing process will set certain variables that will then be used by the protocol to execute the command. Our example will use an input format frame to read the command field and parse the command. See Section 5.4 for details about how we implemented our command language.

Given the functions that we defined above, our basic set of commands will be:

     DISPLAY <key>
     FIND <search criteria>
     MODIFY <key>
     CREATE

Other commands (such as END to complete a session and NEXT to move through the search result) will be implemented to facilitate the smooth operation of the above functions.

5.2.3  The Screens

You must next decide how the terminal screens will look. Will all records be displayed similarly, that is, do you need only one design for record displays? Or will the display look different for a record being updated than for one being displayed? Will a single record fit on the terminal screen? Which items of a record will you allow a user to alter?

The easiest way to begin, of course, is to draw a picture of how the screen is to look. This is most easily done on graph paper so that you are able to identify rows and columns when it comes time to code the format frames. Remember to leave one space between adjacent fields for the Field Attribute Character. First, you will want to divide the screen into areas. In our sample application, the screen will be divided as follows:

     +--------------------------------------------------------------+
     |                     COMMAND AREA (2 x 79)                    |
     |--------------------------------------------------------------|
     |                                                              |
     |                                                              |
     |                                                              |
     |                                                              |
     |                                                              |
     |                     RECORD AREA (24 x 79)                    |
     |                     UPDATE AREA (24 x 79)                    |
     |                 (both starting at (1,1) on CRT,              |
     |                   overlapping each other and                 |
     |                       the COMMAND area)                      |
     |                                                              |
     |                                                              |
     |                                                              |
     |                                                              |
     |                                                              |
     |                                                              |
     |                                                              |
     |                                                              |
     |                                                              |
     +--------------------------------------------------------------+

The COMMAND area will occupy the first two rows and will contain status information, messages for the user, and the command field (the space where the user will type in commands). This area is displayed at all times and helps to keep the user oriented by displaying in a MESSAGE field information such as which record is being displayed for modification or how many records are in the search result.

The RECORD and UPDATE areas occupy the same space on the screen. The RECORD area is defined with the PROTECT attribute so that a record can be displayed in this area and be completely protected from user modification. This area will be used when a record is simply being displayed. But if the record is to be displayed so that the user can modify it, you would want to be able to unprotect all or some of the fields, so you would display it in the UPDATE area, which is defined with the BGPROTECT attribute. This way the same format frame can be used to display the record on the screen when it is to be modified. [See 5.3 for a discussion of the "DISPLAY = UNPROTECT" statement.]

The RECORD and UPDATE areas both overlap the COMMAND area. The main reason for this is so that the output frame used to display records can write information (specifically messages) in the two top rows. In effect, our application is allowing the message field of the COMMAND area to be accessible from all frames and areas. This is only necessary because we are using the REPROMPT Uproc in our input format frame. [See 5.6.3.]

After you have decided on the areas, you will divide each area into fields, which are defined by a format's label groups. For example, the COMMAND area will look like this:

     +--------------------------------------------------------------+
     | (FUNCTION)             MOVIE REVIEWS                   (DATE)|
     | (COMMAND)                                           (MESSAGE)|
     +--------------------------------------------------------------+

For the RECORD and UPDATE areas, we have designed a display as follows:

     +--------------------------------------------------------------+
     |                                                              |
     |                                                              |
     |                                                              |
     |                                                              |
     | (TITLE)                                     Released: (DATE) |
     |                                                              |
     |   Starring:                  Directed by:                    |
     |     (STAR)                      (DIRECTOR)                   |
     |     (STAR)                                                   |
     |     (STAR)                                                   |
     |     (STAR)                                                   |
     |     (STAR)                                                   |
     |     (STAR)                                                   |
     |                                    Rated: (RATED)            |
     |    Rating: (RATING)                                          |
     |    (REVIEW)                                                  |
     |       ''                                                     |
     |       ''                                                     |
     |       ''                                                     |
     |       ''                                                     |
     |       ''                                                     |
     |       ''                                                     |
     |                                                              |
     | Reviewed by: (REVIEWED.BY)                                   |
     +--------------------------------------------------------------+

We can then use this template to write the frames to control the display, modification, and creation of records. Our format definition will include an output data frame for displaying records and two input frames, one for modifying records and one for creating records, both of which call the same indirect frame where the actual element processing is done. In addition, we will define both an input and an output XEQ frame to control the command area. The entire format is included in Section 5.9.3; each frame will be discussed separately.

5.3  Displaying Records

The format frame OUT (beginning on line 491 of the format; see Section 5.9.3.3) is the basic frame used for displaying a record, whether it's for simple display, modification, or the creation of a new record. For display, we want all fields to be protected; but for modification, fields must be unprotected so that they can be changed on the screen.

To allow the user to create a new record, we want to display field titles (or some indication of where data is to be typed on the screen), and blank, unprotected fields must be placed on the screen so that the user can type data into them. This is done by issuing the "IN UPDATE, USING OUT NODATA, DISPLAY" command (line 71 of the protocol). The NODATA DISPLAY portion of the command will display a "blank" record; no record is retrieved from the data base, so no GETELEMs occur, but the format frame is executed and all values specified with TITLE, DEFAULT, or VALUE statements will appear on the screen. [See 4.1.1.1.]

Let's look at a representative label group and see what kind of statements are included. The STAR label group begins on line 510 of the format and puts out the six occurrences of the STAR element.

First, of course, you have a GETELEM statement, which retrieves the data value from the record. The TITLE and TSTART statements specify a title and a starting position for it. The DEFAULT statement supplies a value for the element if one does not occur in the record. The DEFAULT statement by itself, that is, without a value specified, will create a field whose size is determined by the LENGTH statement. It will be filled by the character specified by the SET PADCHAR Uproc (line 701). Because of the LOOP statement (line 519), the DEFAULT statement will create blank fields to make a total of 6 fields, so that, for example, if a record contains three occurrences of the STAR element, these will be displayed and three more fields will be created, each consisting of 25 blanks. For simple record display, this is meaningless, but if the record is being displayed for modification, it is important to have these fields on the screen so that the user can type new occurrences into them.

You must remember in full-screen programming to always include a LENGTH statement in each label group and a SET PADCHAR Uproc in the frame declaration section. [See 6.9.4.] These two statements together create the field on the screen within which the value will be placed. Otherwise, the length of the value will determine the length of the field, which during modification will limit the user to a field length equal to the length of the current value. Or, if there is no occurrence of the element, the field will be, in effect, of zero length, which again will not allow the user to modify the field.

The character specified in the SET PADCHAR Uproc can be anything, but is most commonly a blank or an underscore. The same pad character must also be specified for the input frames so that it will be stripped from the values when they are read from the screen. [See 5.6.2.] The pad character for the IBM 3270s cannot be a blank if you want the user to be able to use the INSERT key, but the same effect can be achieved by setting the pad character to the "hex 00" character.

If you are not sure what types of terminals that your users will have, your best bet is to set the pad character to $TERMPAD, a system variable that is hex 00 character for IBM 3270-type terminals, and a blank for all others. [See 6.9.4.]

You can also set a pad character for a single label group by including a PADCHAR statement in the lable group. This overrides the global setting of the SET PADCHAR Uproc for that label group's execution.

Remember that the START positions of a frame are always relative to the area, not the physical CRT screen; so, since column 1 of the physical screen is inaccessible to the programmer, a "START = 3,3" statement indicates the third row and third column of the area, not the third row and third column of the CRT screen.

The PUTDATA statement causes the actual placing of the value, and the LOOP statement insures that all occurrences of the value will be output (or at least blank fields for the maximum number of occurrences allowed).

All other label groups in the OUT frame are basically the same.

This output data frame is just like any frame to write formatted data except for the addition of the LENGTH statement, which works in conjunction with the SET PADCHAR Uproc. These statements need only be included if the output data frame is also to be used for modification and input.

In addition to the SET PADCHAR Uproc described above, there will be other Uprocs in the frame declaration section for this frame that will control the display characteristics for the values. The Uprocs used in our example are:

The SET DISPLAY Uproc sets the attributes for all the data fields (in this case, everything except title fields). The UNPROTECT attribute specifies that all data fields will be unprotected if the area will allow it. So if the frame is used to place data in a protected area, then all data fields output by the format will be protected, that is, the UNPROTECT attribute will be ignored. But if the area is BGUNPROTECT or BGPROTECT, then all the data fields will be unprotected because of the UNPROTECT attribute on the SET DISPLAY Uproc. So in our case, if this frame is used to place data in the RECORD area, all data fields will be protected; if used with the UPDATE area, all the data fields will be unprotected. Also, the A48 attribute specifies that all data fields will appear in yellow if a color terminal is being used.

The SET TDISPLAY Uproc sets the display characteristics for all titles specified by the frame. They will always be protected because of the PROTECT attribute, and will be blue on a color terminal. See Chapter 6 for details about display attributes.

This frame illustrates the relationship between a frame and a device services area, that is, how a single frame can be used to achieve different results by executing it in areas of different attributes. For example, in an area with the PROTECT attribute, the LENGTH statement and the SET PADCHAR Uproc have no useful effect because the user would not be able to type in the field. But if this frame is written into an area with BGPROTECT or BGUNPROTECT specified, these statements become essential and affect how the screen is written.

This frame also illustrates how statements in the format frame only get executed under certain circumstances (e.g., an area definition that allows unprotected fields, or a terminal that has color). Having a single output frame that can serve many purposes also cuts down on code maintenance -- if you move the position of one element, you only have to change the display code once.

(See the Formats Reference Manual for more details about format statements.)

5.4  Entering Commands: The COMMAND Area

Because we are designing and implementing a command language, we must define a command field somewhere on the screen. For our example, we have chosen to define an area at the top of the CRT screen that will contain not only the command field, but also several other fields to display status information and messages. The COMMAND area is controlled by two format frames: one for display and one for command input.

The format frame named CMDOUT (beginning on line 406 of the format) is executed each time you want to place new information in the COMMAND area. It contains a label group for each field to be displayed; in this case, you are displaying the date, the name of the application ("MOVIE REVIEWS"), the name of the command being executed, a message, and the command field.

We want the information fields to be protected from user modification, but the command field to be unprotected so that the user can type commands into a field. So we define the COMMAND area with the BGPROTECT attribute and include a SET PROTECT Uproc in the format frame, which will make all foreground fields protected, but will allow the CMDOUT frame to unprotect individual fields. In the label group that defines the command field (lines 441-446), we include a DISPLAY = UNPROTECT statement.

The user issues a command by typing it into the command field and pressing the RETURN key. This sends all the unprotected data from the screen to the device services areas via the READ option of the WRITE command (line 25 of the protocol); then line 26 of the protocol invokes the input format frame named CMDIN (beginning on line 450 of the format). This frame reads the command field from the device services area named COMMAND, parses the command, and sets certain variables. These variable values will determine how the protocol is to proceed. See Section 5.5.2 for a description of how commands are processed by the CMDIN frame.

5.5  Constructing the Protocol

This section will describe the general functioning of the protocol, including an overview of command processing. It will describe in detail how the DISPLAY and FIND commands function.

We have allocated four variables that will either be displayed in the COMMAND area or used by the protocol to determine how a command is to be processed. These variables might be set and used by an executing format frame or by the protocol, so they must be defined as part of a global vgroup [See 5.9.2.] to make them accessible to both the format and the protocol. They are:

The MESSAGE Variable

The MESSAGE variable will be written on the second row of the COMMAND area. It contains various strings that tell the user something about the command most recently issued or the record being displayed. For example, if the user issues an invalid command, the protocol will set the MESSAGE variable to "INVALID COMMAND -- TRY AGAIN" or if a record from a search result is being displayed, the MESSAGE variable will read "RECORD n OF n".

The FUNCTION Variable

The FUNCTION variable indicates what type of command was issued, thereby controlling what part of the protocol will be executed. It appears on the top row of the screen, and is assigned by the CMDIN frame each time a command is issued.

The COMMAND Variable

The COMMAND variable holds the user's command. When the user types in a command, the CMDIN frame reads the command field and assigns the value to the COMMAND variable, which is then processed by the rest of the frame. After each command is processed, this variable is cleared. When the COMMAND area is written to the terminal, the COMMAND variable value may appear in the command field with the value of a possible next command to assist the user.

The SEARCH Variable

Some command verbs (DISPLAY, FIND, and MODIFY) must be followed by something, either a record key or a search criterion. The SEARCH variable is allocated to hold this value and will be used in the protocol to locate the specified record.

5.5.1  Beginning the Session

The complete protocol can be found in Section 5.9.1. This section will describe the beginning of the protocol.

We first store the current settings of the user (line 2) and then set up the appropriate environment for a full-screen application. This includes setting the SPIRES modes NOECHO and NOSTOP (line 3), the message level (line 4), and the WYLBUR modes NOCOMM and NOMSG (line 5). We also have to set NOWRITE (line 6) so that we can control when data is moved between the screen and an area.

Next we define the device services areas. In this case, we are defining three areas: the COMMAND area, the RECORD area, and the UPDATE area. The COMMAND area has dimensions of (2,79), and so will occupy two complete rows beginning on the CRT area at (1,1), that is, the top two rows of the CRT screen. It will have the default IODATA function, meaning that it can be used for both input and output. It also has the BGPROTECT attribute. This means that all background fields on the area will be protected by default, but an executing frame may change a foreground field to be either unprotected or protected. In addition, we have given it an alternate character set attribute, ALTCHAR 24, which means that everything put in the area will be displayed in pink, but an executing format frame can override this, making a field a different color.

The RECORD area contains 24 rows of 79 columns, also beginning at row 1 of the CRT screen. It, too, will have the IODATA function. But it is assigned the PROTECT attribute, which means that all fields in the area will be protected from user modification no matter what -- an executing format frame cannot override this protection. Even though the RECORD area overlaps the COMMAND area, the command field will be unprotected if the COMMAND area receives data after data is placed in the RECORD area. The order in which overlapping areas are used is important. [See Appendix A.]

The UPDATE area is just like the RECORD area but has the BGPROTECT attribute, so that fields can be unprotected by an executing format frame. Records that are to be modified will be displayed in this area.

Next we select the subfile and set the format (lines 16 and 17), clear the terminal screen (line 18), and set the initial values of the MESSAGE and FUNCTION variables (lines 19 and 20).

To begin a session with the user, we first want to write the COMMAND area to display a welcoming message and allow the user to enter the first command. Line 24 executes the CMDOUT frame in the COMMAND area. Because NOWRITE is in effect, however, this command does not affect the contents of the screen. The area must be written to the screen, and this is done with the WRITE command in line 25.

But line 25 does more than just write the screen. The WRITE command with the READ option will first write the screen and then wait for a response from the user (much like the ASK command in a line-by-line protocol or the ASK AREA command). The cursor will be positioned at the first column of the second row, which is the beginning of the command field. When the user presses the RETURN key (after typing in a command), the entire contents of the screen will be placed in the CRT area. The next command (line 26) reads the data from the COMMAND area (that is, all the data that had been on the top two rows of the screen) by executing the CMDIN input format frame in the COMMAND area.

When the CMDIN frame executes, it parses the user's command and sets the variables that will be used to control further execution. The next section describes how each command is processed.

5.5.2  Command Processing

Commands are read by the CMDIN frame. This frame reads what the user types in the command field and passes information to the protocol instructing it how to process the command.

As described in the preceding section, the WRITE CRT READ command on line 25 will write data to the screen and wait for the user to press the RETURN key, and then the "IN COMMAND, XEQ FRAME CMDIN" command will call the format frame to process the data in the COMMAND area.

The first label group in the CMDIN frame (which begins on line 454) accesses the value in the command field. This field starts on row 2, column 1, of the area for a length of 28 characters and gets whatever data it finds there and assigns this value to the variable COMMAND. It then begins a series of tests, beginning with the $PMATCH function, to determine what command the user issued. Each command will set the value of the variable FUNCTION. If the command was DISPLAY, FIND, or MODIFY it will assign the value of the variable SEARCH to whatever the user typed following the first blank in the command; this is presumably either a record key or a search criterion. When the format frame is finished, control returns to the protocol where the next command is "/JUMP #FUNCTION". The protocol will branch to the label in the protocol with the same name as the FUNCTION variable value to continue processing.

When a DISPLAY command is issued, the protocol will execute a simple output data frame that displays the record in the RECORD area with all elements protected from user modification. If a FIND command is issued, the protocol will first issue the appropriate search request before displaying each record as with the DISPLAY command.

When a MODIFY command is issued, the protocol executes the same output data frame to place the record on the screen, but puts it in the UPDATE area so that all data fields will be unprotected. In addition, the command variable is set to "UPD". When the user modifies the record and presses the RETURN key, a merge frame is executed to complete the update process.

An identical process is used to add a record. The CREATE command will call the same output data frame to display an "empty" record and the command variable will be set to "ADD". When the user presses the RETURN key, an input frame is called and a new record is added.

During either the MODIFY or CREATE process, the user may change his or her mind and type "CANCEL" in the command field (thus overriding the UPD or ADD "command") and the input process will be terminated, so that he or she can then issue a new command.

5.5.2.1  The DISPLAY command

If the command issued by the user is DISPLAY (or DIS) followed by a record key, the CMDIN frame assigns the portion of the command to the right of the first blank to the variable SEARCH. If this value is null, that is, no key was included on the command, the MESSAGE variable will be set to 'COMMAND REQUIRES AN OBJECT' and the FUNCTION variable is set to 'COMMAND' to cause the protocol to move to "++COMMAND" to await a new command.

Otherwise, the protocol will move to the "++DISPLAY" label statement on line 29 because the FUNCTION variable was set to DISPLAY by the format. Line 32 will cause the requested record to be placed in the RECORD area. If this command fails, line 33 will direct the protocol to line 61, the MESSAGE variable will be set to "RECORD NOT FOUND FOR #SEARCH" by line 64, and the user will be returned to the COMMAND screen. If the command succeeds, lines 34 and 35 will reset the MESSAGE variable to indicate success and the COMMAND variable to null to clear the command field.

The protocol will return to the "++COMMAND" label statement where the new variable values will be placed in the COMMAND area, the terminal screen written, and the user will see the resulting record displayed and be able to enter a new command.

5.5.2.2  The FIND Command

When the user issues a FIND command, the CMDIN frame will assign the search request value to the SEARCH variable, and will assign the value "FIND" to the FUNCTION variable. The protocol will then move to the "++FIND" label statement, and the search request will be issued. The FOR RESULT command in line 45 will enable us to present the records in the search result sequentially.

The "++NEXT" label statement (line 47) initiates the display of the records. A single record is placed in the display area and the MESSAGE variable assigned, indicating which record out of how many is being displayed. If there are no records in the result, the message "NO RESULT" will be placed in the MESSAGE variable. The protocol returns to the "++COMMAND" label statement where the CMDOUT frame is executed and the CRT screen is written.

Each time a record is displayed from the result, the command field will contain the "NEXT" command. The user then need only press the RETURN key to see the next record. However, the user may initiate a new command by typing over NEXT.

At the end of the result, the "++END.NEXT" label (line 54) will initiate the message "END OF SELECTED RECORDS" and the screen will be prepared to accept a new command.

5.6  Updating Records

Now that you understand the easy part, we'll move on to a more complicated process that calls for two frames. When updating records, you display the requested record first with an output frame, allow the user to modify the display on the screen and then read the screen and update the record using an input frame.

The same input frame will be used when adding new records. You will note in the format that the INPUT frame is an indirect frame which is called by both the MERGE frame and the ADD frame. The difference between these two frames is the USAGE statement: the MERGE frame has a usage of MERGE, and the ADD frame has a usage of FULL.

We have chosen to use the MERGE command rather than the UPDATE command because with the merge process you only need to process altered elements of the record. When you use the UPDATE command, you must replace the entire record, which means that not only does the entire record have to be placed on the screen, but also that the input format must read every field on the screen and process all the elements, whether they have been changed or not. So for full-screen modification of records, the MERGE command is more efficient.

These frames have DIRECTION = INOUT because both input and output processing will take place. The output processing consists of the display of diagnostic information when errors are detected during input. [See 5.6.3.]

5.6.1  Displaying the Record to be Updated

The modify process begins when the user types a command like "MODIFY 5". The command is parsed and the SEARCH variable assigned the value of "5". The protocol transfers execution to the "++MODIFY" label (line 83). The COMMAND variable is set to "UPD" and the requested record is displayed using the frame OUT in the UPDATE area (line 87). Data is placed in the command area (line 90) and the screen is written (line 91).

The record must be displayed so that the user can alter or delete any existing values and add new values or occurrences. We use the same output frame as we did before, but we place the record in an area that has BGPROTECT specified for it; in this case, the UPDATE area. The record is displayed on the screen, but all the data fields are unprotected because of the SET DISPLAY = UNPROTECT Uproc included for the frame. The LENGTH statements and the SET PADCHAR Uproc insure that each field is the maximum size.

5.6.2  Merging the Record

When the user has completed modifying the record on the screen, he or she presses the RETURN key, which causes the screen to be read.

Line 95 attempts to merge the record using the format frame named MERGE. This frame calls the INPUT frame (which begins on line 611) which actually puts the elements back into the record in the data base. It reads each element value from the UPDATE area, checks to see if it has been changed, and, if it has, replaces the old value with the new. The rest of this section will describe each statement in the label groups to explain how SPIRES reads the record back into the data base.

The label group beginning on line 616 reads data from the command line, and checks to see if the user has changed the command field to "cancel". If so, the format is aborted and the input process cancelled. This is one reason why we overlapped the COMMAND area and the UPDATE area: so that the command field could be read from the MERGE frame.

The GETDATA statement is generally used to extract a value from a character array. In a full-screen application, GETDATA extracts the value from the specified screen area as determined by the START and LENGTH statements. When 5 and 7 are specified in combination with GETDATA, the data retrieved is tested to see if the value has been changed on the terminal screen since the screen was written. If the data has been changed, then the $CHANGED flag is set and the remainder of the label group is executed. If the data has not been changed, then the label group is not executed.

If the value returned from GETDATA is null, but has been changed -- i.e., changed to null by the user -- the label group will be executed. If this is the case, you want the PUTELEM statement to act like a REMELEM statement, that is, instead of putting a value into the element you want to remove the value. This is the function of the "8" on the GETDATA statement. In effect, the "GETDATA = 8" is equivalent to the Uproc "IF $ULEN = 0 : SET REMOVEL". That is, if the value has been changed, but is of null length, which would indicate that the value had been changed to null, the element value is to be removed. ("GETDATA = 8" has a different effect during an ADD; see Section 5.7).

The STAR label group (lines 634-640) controls the merging of six occurrences of the element STAR. The addition of the PUTELEM = STAR and LOOP = 5 will take each of the six fields from the screen and test to see if it has been changed and put each element value back into the record. The GETDATA statement does not include the "5,7" values because there are multiple occurrences of the element. If the first occurrence were unchanged, the "5,7" would cause the rest of the label group to be skipped, and the subsequent occurrences would not be processed.

The REVIEW label group (lines 662-668) controls the element REVIEW, which can span up to seven rows on the screen. The addition of the MARGINS and MAXROWS statements will cause the frame to read all seven rows before testing for a change to the element.

Note that the SET PADCHAR Uproc is included for the input frame. This is so that the pad character will be stripped from the end of the value read from the screen before it is put into the record.

5.6.3  Handling Error Conditions: The REPROMPT Uproc

You should provide for all possible errors that the user could make. In general, whenever you issue a command that does data base access, such as DISPLAY, ADD, or MERGE, you should follow that command with a statement that tests $NO and provides some action in case the command fails (see lines 33, 78, and 96).

When doing input via an input frame as we are doing, you can test for most errors from the format with INPROC rules and Uprocs. [See 5.8.1.] If there are errors in the input, you want the record to remain on the screen and the user given a chance to correct it. This can be done with either the REPROMPT option [See 4.7.5.] or the REPROMPT Uproc. We have chosen to use the REPROMPT Uproc. After the INPUT frame is executed, processing returns to the MERGE frame. The Uproc on line 578 tests to see if there were any errors detected by processing rules. If not, the format frame returns control to the protocol. But if there were errors, the REPROMPT Uproc is executed. REPROMPT sets up, in effect, a looping action by internally issuing a WRITE CRT REPROMPT command to allow the user to change incorrect data and press the RETURN key again.

When an error occurs during element processing, an error message (set by a $MSG system proc or a SET UCODE Uproc) is written to the location specified by the ESTART statement in the INPUT format frame. The length of the error message field is determined by the SET ELENGTH Uproc (line 715.2) and its display characteristics are specified in the SET EDISPLAY Uproc (line 715.1). When the REPROMPT Uproc is executed, the screen is rewritten and the error message appears. Because a single frame is thus controlling input and output processing, it must have DIRECTION = INOUT if it contains a REPROMPT Uproc. It is also necessary to include a SET PROTECT Uproc in the frame declaration section of the format so that these error messages will be protected.

When ESTART is set, the system variables $EROW and $ECOL hold the row and column values of the error message fields. ESTART execution has no effect on the contents of other row and column values (e.g. *, X, $SROW, $SCOL, etc.). Note also that ESTART is not relevant to other row or column positions (i.e., START, TSTART, or XSTART), only to the previous ESTART value. That is, "ESTART = *,X+2" will place the error message on the same line as the last error message, not the same line as the element value. This is understandable if you think about how error messages are placed: an INOUT frame is basically an input frame; the only data being placed are error messages, so the row and column pointers are only reset when an error message is placed.

The RELEASE.YEAR label group (lines 627-633) includes "ESTART = 5,58" and "INPROC = $MSG(A2)", so if the user enters the wrong type of value for the RELEASE.YEAR element (i.e., a non-date value) the error message "A2" will appear in column 58 of row 5 (which is directly to the left of the element value) and will be red and blinking because of the attributes specified in the SET EDISPLAY Uproc. Presumably, the A2 code is something that the user could then look up in documentation if online help were not available.

You will notice in lines 581-590 in the format that we are assigning a value to the MESSAGE variable and placing it on row 2 of the screen. This variable is usually written in the COMMAND area by the CMDOUT frame, but in this case it will be placed in the UDPATE area and appear in the same space. This is another reason why we overlapped the areas in the beginning: because the REPROMPT Uproc never lets us leave the format, we could not put this message out from the CMDOUT frame. We also included a SET DISPLAY Uproc for this frame (line 715.3); this will cause this data field to appear in red because of the A16 attribute.

From the user's point of view, the data remains on the screen as typed, and error messages appear to the left of the element value causing the error. A message will appear in the message field saying "ERROR FOUND, CORRECT AND RESEND". The user may cancel the update request by entering "cancel" in the command field and pressing RETURN, or simply pressing the ATTN key. Both actions cause the format to be aborted. No other response is accepted; unless "cancel" or ATTN is entered by the user, another REPROMPT will occur.

The CANCEL command is not read by the CMDIN frame like all other commands. The label group beginning on line 616 reads the command field; if it contains "cancel", the format is aborted (line 621) and the protocol branches to the "++CANCEL" label, because of the IF statement in line 96.

If the merge is unsuccessful for any reason not detected by the format, line 96 will detect this failure, and the protocol will branch to the "++CANCEL" label. The CANCEL label group of the protocol (lines 101-107) is thus executed under one of two conditions: 1) a REPROMPT is interrupted, or 2) the merge is unsuccessful due to an error not detected by the format. Line 105 tests for the $ABORT flag, which indicates that the REPROMPT has been aborted. When this is the case, the message "INPUT CANCELLED" appears in the message field. Line 106 is executed under other error conditions. It puts out the message "INPUT FAILED. CODE: $SNUM," substituting the SPIRES error code from the $SNUM system variable. No reprompting occurs in this situation, however, because the error was detected after the format was exited. But you could do a reprompt from the protocol with a WRITE CRT REPROMPT command. See 5.8.1 for an explanation of this process.

See 5.8.8 for information about placing error messages for multiply-occurring elements.

5.7  Adding New Records

Adding new records is similar to modifying existing records in that you have an output frame to display a record and an input frame to enter it into the data base. In this case, the "record" that you display is one without any data. This is done by using the NODATA option on the "USING frame" prefix -- "IN RECORD, USING OUT NODATA, DISPLAY". [See 5.3.] All titles and default values appear on the screen. The user can use the TAB key to move the cursor to the beginning of each field. The location of each field can be indicated by supplying default values for each element.

For example, "Title" will appear in the field specified for the title element because of the DEFAULT = 'Title' statement in the label group (line 496). If the user does not enter a value for the element, the default value will be entered into the record. The OUT frame includes DEFAULT statements in each label group that either supply a string to appear in the field or create a blank field on the screen where the user can type data.

After the user types in the data and presses the RETURN key, the format frame ADD (which has USAGE = FULL) is executed. This frame calls the INPUT frame, the same frame used when modifying records, and the record is added to the data base (if there are no errors, that is).

The GETDATA statement during an add will check to see if the field has been changed because of the "5,7", just as in a merge. So if the user types anything on the screen, it will be read and put into the new record. On an ADD command, the "8" option on the GETDATA statement causes a SET SKIPEL to occur if the value is of null length, rather than a SET REMOVEL as with updates, because you cannot remove an element from a record that does not yet exist. If the field is null, the element is simply not added to the record.

The TITLE label group, however, does not have the "5,7" values on the GETDATA statement. When the empty record is displayed, the TITLE field has the string "Title" displayed to indicate where the element is to be typed. If the user did not type in a value for this element, the field would be "unchanged" and the label group would be skipped. Instead, we want the string "Title" to be used as the element value.

If there is an error in the input, the REPROMPT Uproc will function as described above in Section 5.6.

5.8  Special Topics

This section includes descriptions of concepts that were not covered by our sample application. Because these are complicated procedures and vary for each application, only the basic concepts are explained here. Complete implementation is dependent upon a number of factors, so see the SPIRES consultants for assistance if needed.

5.8.1  INCLOSE Error Processing

If you have INCLOSE rules that can signal errors coded in your file definition, they must be treated differently from other processing rules, particularly when creating error messages. One way to avoid this is to duplicate the inclose processing with Uprocs in the format that do cross-element checking, testing for required elements and occurrences, etc. In our application, most errors were detected by the format, and error messages were placed with the ESTART and ELENGTH statements in conjunction with the REPROMPT Uproc. But for INCLOSE rules that are processed by the file definition after the format has been executed, ESTART and ELENGTH cannot be used to put out error messages about the failure of an INCLOSE rule. Remember that INCLOSE errors can also be generated when no rules have been defined in the file definition, e.g., if you try to add multiple occurrences of an element when OCC = 1 is coded.

If there are errors not detected by the format, you must use the REPROMPT option on the WRITE command. After the format has processed the record, the file definition attempts to "close out" the record by applying the INCLOSE rules. If there is an error, the ADD or MERGE command fails. You then test for $NO in your protocol, which would indicate that some error had been encountered when SPIRES tried to put the record in the data base. The error messages will be placed in the error message fields defined by ESTART and ELENGTH as they are with the REPROMPT Uproc. Or you could create an appropriate message based on an examination of $SNUM, $MSGNUM, $MSGINT, $MSGLIT, or by the technique shown in Section 3.3 to send system messages to a user-defined area. The WRITE CRT REPROMPT command rewrites the screen and the user can then modify the screen and attempt to ADD or MERGE the record again.

5.8.2  Displaying Multi-Screen Records

When you have records that contain variable length data elements, you will not be able to foresee when a record might take more than a single screen to display. So you run the risk of displaying only part of the data or encountering errors when the user requests the display of these records.

In order to allow a record to be displayed in "pieces," you need to code "PUTDATA = 1" in each label group of the format that puts out a data value. When this is coded in a format of fixed-dimensions (and presumably your display frame will have the dimensions of the screen area) and a label group is unable to place a value within these boundaries, the format variable $OVERFLOW will be turned on, and execution will immediately cease for the executing frame. If "PUTDATA = 1" is coded in an indirect frame, control will be returned to the calling frame.

You could then test for the $OVERFLOW flag from the protocol and execute the frame again if necessary (i.e., IF $OVERFLOW THEN USING frame-name DISPLAY record-key). When "PUTDATA = 1" is used, no S808 error will occur; the $OVERFLOW flag is turned on instead. This flag is set from within the format, but is available after the format completes execution.

To determine where the format should logically begin execution, you must do your own "checkpointing" to keep track of the last label group executed. One technique is to assign a numerical value to a variable in each label group. Each time the frame is executed, the first label group checks the value of this variable and branches to the appropriate label group. Because $OVERFLOW only remains set until another frame executes, you would need to set your own variable to insure that an overflow condition is properly flagged. If you are looping through multiple occurrences of an element, you must also keep track of which occurrence was last put out.

When the frame successfully executes the final label group, the $OVERFLOW flag is turned off, and the next time that the frame is called, execution will begin at the first label group.

5.8.3  Updating Multi-Screen Records

When dealing with multi-screen records, it is advisable to use Partial FOR Processing. This places the entire record in core and you can access it multiple times without doing all the I/O necessary to bring the record into core each time you issue a DISPLAY or MERGE command.

The process is relatively simple. You first bring the record into core by referencing it as follows:

And then issue the "FOR *" command. Now when you issue either a DISPLAY or MERGE command, it applies to that record which is being held in core.

After you have referenced the appropriate record, you may display a screen-full of the record as described in the above section, using the "PUTDATA = 1" statement in the format. Successive display commands will retrieve the same record from core each time the DISPLAY command is issued.

The user can update each screen of the record as they normally would, and when they press the RETURN key, your application should issue a MERGE command. The changes made to each screen will be merged into the copy of the record that resides in core. If errors are encountered, the individual screen will be rewritten (if a REPROMPT Uproc is coded) at the time of the MERGE command.

When the entire record has been displayed and updated, you must issue the "ENDFOR *" command to indicate that you have completed all transactions for the referenced record. Then issue the UPDATE command; this takes the core copy of the record and puts it back in the data base. If any INCLOSE errors are encountered, an error message will be issued by SPIRES, but unless you have coded logic to associate specific errors with specific screens to optimize close-out error processing, the entire updating cycle must be redone. For this reason, it is recommended that any possible INCLOSE errors be detected by the format as they occur.

When you want to add new records, instead of referencing the record in the beginning (since there is no record to reference yet), issue the commands

This will create an "empty" record in core into which you can merge the information that the user types on each screen. After the "ENDFOR *" command, you would, of course, issue an ADD command, and the newly created record in core will be added to the data base.

See Chapter 11 of "Technical Notes" for more information about the REFERENCE command, and Chapter 12 for details about Partial Record Processing.

5.8.4  Displaying Multi-Record Screens

If you want to put more than one record on the screen and you know for certain how much space each record takes up, it is a simple matter of saying, for example,

where the frame dimensions of the frame named "out" are such that the number of rows times the number of records (in this case 5) do not exceed the number of rows in the area. The first five records in the result will be placed one after another in the designated area.

If, however, you have variable length data and cannot estimate how much space each record will need, you can place each record in the area using either the CONTINUE or the OVERLAY option on the "IN areaname" prefix.

The CONTINUE option will place the new data beginning in the next available row. However, just as with large records, you run the risk of going beyond the boundaries of the screen. To avoid this, use "PUTDATA = 1" in your format as described in Section 5.8.2.

The OVERLAY option places the new data beginning in row 1, column 1, of the area, but does not blank the area. That is, all previous data placed in the area remains, and the new data is placed on top of it. This can be useful when you want to place multiple records on the screen using different formats.

See Section 4.1 for a complete description of these options.

5.8.5  Updating Multi-Record Screens

If you need to update records that appear on a multi-record screen, there are a number of things to consider:

1. Because you must have the key of the record to include on the MERGE command, you must either have the key values stored in an array, or process the records under Global FOR. Or, if the key appears in a predictable place on the screen, you can retrieve it with the $GETAREA function before issuing the MERGE command.

2. You must decide how you are going to handle errors. If, for example, an error occurs in the second record, and you have a REPROMPT Uproc coded in the format, the entire screen will be rewritten. But the first record has already been successfully merged, so the user will not be able to make any changes to the first record (although it will be possible to type over the display of this record). If you wanted to allow this, you could remerge all the records on the screen each time, which would allow the user to modify all the records on the screen each time a reprompt occurs.

Also, the user might wish to skip the second record if he is unable to modify it correctly, but still process the rest of the records on the screen. You might want to implement a special form of the cancel command (like "cancel *") to allow this. However, you would have to use the REPROMPT option on the WRITE command rather than the REPROMPT Uproc.

3. Your format must be designed to read a single record at a time, so there must be a fixed number of rows per record or some sort of end-of-record indicator, the easiest being a blank line. When the format encounters this blank line, you would set a variable equal to $LROW so that you will know where to begin reading the next record.

The above guidelines should help you get started on designing a multi-record screen application. There are many different approaches to the problem, but your procedural solution will depend entirely on the programmatic design of your application.

5.8.6  Menu-Driven Applications

Generally, menus can be written to the screen as part of a data frame in a format, or by an XEQ frame. User input on the menu can then be read from the screen just as any other input is read. Special features for menu-driven applications can be implemented using field detection or cursor select capabilities, and/or function keys. Currently only the IBM 3270s have the cursor select capability.

Your menu might allow input into an unprotected field, so that the user could enter a number or word to indicate their choice of items. Or your menu might be a screen of protected fields, each field being a choice in the menu. The "DISPLAY = DETECT" statement must be included for each field. The user indicates the selection of a field by altering the field in some way (e.g., typing an "X" in the field) and pressing the RETURN key, or by use of a light pen, or by pressing the CURSOR SELECT key while the cursor is anywhere in the field (if using an IBM 3270). [See 6.8 for a description of the "DISPLAY = DETECT" statement.]

It may also be useful to know the location of the cursor in a menu on a screen when the user presses RETURN; this location can be used to signal a menu selection. The cursor location at RETURN is returned by the following function:

Function keys allow the user to indicate a procedural choice. Which key was pressed is read by the application via the function

This function returns an integer representing the function key pressed. [See 6.7 for a description of function keys.]

5.8.7  Help and Explain Facilities

In order to assist the user of your application, you would probably want to implement help and explain facilities. A help facility gives the user descriptions of commands and aids them in learning and using the system. An explain facility provides information about error messages, giving the user assistance when they have entered wrong data.

Because a Help message is something that the user requests when they want information (rather than a response from the system to something the user has done wrong), it is usually not a part of record displays. We recommend that you make your help screens a separate display format that is called by the command HELP or perhaps a special character such as "?". The text of the help screens might be hard coded in an XEQ frame, or kept as separate records in a subfile, which could be accessed via a path. The command verb (i.e., HELP or ?) alone might give the user a menu of choices, or if followed by another word might give the user the explanation for that word.

An Explain message, on the other hand, has to be displayed on the screen with the record that is in error, so that the user can see what the explanation is pointing to. (There is currently no straightforward way to display an explanation on a separate screen and then restore the screen from which the explanation was requested.) To accomplish this, at the point during the update or add process where a reprompt occurs because of an error, the protocol can check for "explain" appearing in the command line. If it does, the appropriate error message can be placed in the message variable (or some other space available on the screen) and the screen rewritten with the WRITE CRT REPROMPT command.

See Section 4.7.5 for a description of the REPROMPT option.

5.8.8  Error Messages for Multiply-Occurring Elements

When you have multiply-occurring elements, you want the error message to appear next to the offending occurrence, but the ESTART statement only specifies the location for a single error message. [See 5.6.3.] Each time SPIRES enters a label group that contains an ESTART statement, the error message field is blanked. When you are processing multiple occurrences by looping through the same label group, each time the label group is entered, the error message field is blanked and if an error is encountered for that occurrence, the error message is placed in the field. So only if the error occurs in the last occurrence will the message appear on the screen. (Note that when the field is blanked, the display attributes from the background area are used; this is only of consequence when areas are overlapping and have reverse video specified as an attribute.)

To provide a separate error field for each occurrence of an element, use the XESTART statement:

It specifies a position for the error message field for the second and subsequent element occurrences. In almost all cases, you would want to put a relative position value on the XESTART statement, i.e., "*" or "X".

As an example, look at the following label group:

The element has six occurrences, placed one below the other beginning on row 8, at column ten. The ESTART statement places the error message for the first occurrence at column 7 on row 8, and the XESTART statement specifies that all subsequent error messages will begin in column 7, but the "X" places them on the next row.

Here is a complicated example using XESTART. Suppose you have a frame that handles an element's occurrences placed across the screen as well as down:

Each pair of exclamation points represents a 2-character error field, while each set of underscores represents a 5-character unprotected field. (The symbols in the top line show column numbers.)

The label group to handle all those fields might look like this:

The MARGINS statement has an effect on XESTART: SPIRES establishes an "emargins" value for use in positioning the error fields across the screen. The "emargins" are defined as the ESTART column (7, in the example), and the right MARGINS value (23) minus the difference between the START and ESTART columns (in other words, 10-7, or 3). So 7 and 20 (23-3) are used as the left and right margins for the error fields.

When SPIRES is trying to place a value in the third error field, it finds that the *+8 starting column is past 20, so it starts it in the left margin of the next row, in column 7, etc.

5.8.9  Combining Full-Screen and Line-by-Line Processing

When developing a full-screen application it is sometimes desirable to test one section without having the other sections working. To facilitate this, the controlling protocol can have a mixture of full-screen commands and line-by-line commands in it. By combining full-screen code with line-by-line, you can gradually put everything together.

You can code full-screen record display frames first, and then add full-screen merge/add frames. Leave the command parsing logic until the last, since you can use the ASK AREA command from the terminal to prompt you for commands. You can also write a format in line-by-line and debug it before writing it to a screen and adding DISPLAY statements.

Another aid to the development of a full-screen application is to define a special command verb or prefix, such as "WYL" or ":", which passes any command following it on to the interactive system. This enables you to suspend a session with a BREAK XEQ command and issue other commands to help you debug your program, such as showing the current values of variables or resetting the message level.

5.9  A Sample Full-Screen Application

This protocol is available in the PUBLIC PROTOCOLS subfile. It can be executed by issuing the commands

The format, protocol, vgroup, and file definition code is available for copying from the following data sets:

5.9.1  The Protocol

  1.   * MOVIES
  2.   STORE SETTINGS
  3.   ! SET NOECHO NOSTOP
  4.   SET MESSAGES 0
  5.   SET TERMINAL NOCOMM NOMSG
  6.   SET NOWRITE
  7.   -
  8.   ++AREAS
  9.   -
 10.   DEFINE AREA COMMAND(2,79) ON CRT(1,1) BGPROTECT
 11.   DEFINE AREA UPDATE(24,79) ON CRT(1,1) BGPROTECT
 12.   DEFINE AREA RECORD(24,79) ON CRT(1,1) PROTECT
 13.   -
 14.   ++SELECT
 15.   -
 16.   SELECT MOVIES
 17.   SET FORMAT MOVIE.DIS
 18.   BLANK CRT
 19.   LET MESSAGE = 'ENTER COMMAND, TYPE END TO EXIT'
 20.   LET FUNCTION = 'COMMAND'
 21.   -
 22.   ++COMMAND
 23.   -
 24.   IN COMMAND, XEQ FRAME CMDOUT
 25.   WRITE CRT, READ CURSOR (2,1) ATTN = 'JUMP ATTN'
 26.   IN COMMAND, XEQ FRAME CMDIN
 27.   /JUMP #FUNCTION
 28.   -
 29.   ++DISPLAY
 30.   -
 31.   IF $FORTYPE THEN ENDFOR
 32.   /IN RECORD, USING OUT, DISPLAY #SEARCH
 33.   IF $NO THEN JUMP NOFIND
 34.   LET MESSAGE = 'RECORD ' #SEARCH ' DISPLAYED'
 35.   LET COMMAND = ''
 36.   JUMP COMMAND
 37.   -
 38.   ++FIND
 39.   -
 40.   /FIND #SEARCH
 41.   -
 42.   ++RESULT
 43.   -
 44.   IF $RESULT = 0 THEN JUMP NOFIND
 45.   FOR RESULT
 46.   -
 47.   ++NEXT
 48.   -
 49.   IN RECORD, USING OUT, DISPLAY END = 'JUMP END.NEXT'
 50.   LET MESSAGE = 'RECORD ' $GXCOUNT ' OF ' $RESULT
 51.   IF $GXCOUNT < $RESULT THEN LET COMMAND = 'NEXT'
 52.   JUMP COMMAND
 53.   -
 54.   ++END.NEXT
 55.   -
 56.   LET MESSAGE = 'END OF SELECTED RECORDS'
 57.   LET FUNCTION = 'COMMAND'
 58.   LET COMMAND = ''
 59.   JUMP COMMAND
 60.   -
 61.   ++NOFIND
 62.   -
 63.   ENDF
 64.   LET MESSAGE = 'RECORD NOT FOUND FOR '#SEARCH
 65.   JUMP COMMAND
 66.   -
 67.   ++CREATE
 68.   -
 69.   IF $FORTYPE THEN ENDFOR
 70.   LET COMMAND = 'ADD'
 71.   IN UPDATE, USING OUT NODATA, DISPLAY
 72.   IN COMMAND, XEQ FRAME CMDOUT
 73.   WRITE CRT, READ CURSOR (5,5) ATTN = 'JUMP ATTN'
 74.   -
 75.   ++ADD
 76.   -
 77.   IN UPDATE, USING ADD, ADD
 78.   IF $NO THEN JUMP CANCEL
 79.   LET MESSAGE = 'ADD SUCCESSFUL FOR RECORD ' $KEY
 80.   LET COMMAND = ''
 81.   JUMP COMMAND
 82.   -
 83.   ++MODIFY
 84.   -
 85.   IF $FORTYPE THEN ENDFOR
 86.   LET COMMAND = 'UPD'
 87.   /IN UPDATE, USING OUT, DISPLAY #SEARCH
 88.   IF $NO THEN JUMP NOFIND
 89.   LET MESSAGE = 'RECORD ' #SEARCH ' TO BE MODIFIED'
 90.   IN COMMAND, XEQ FRAME CMDOUT
 91.   WRITE CRT, READ CURSOR (5,5) ATTN= 'JUMP ATTN'
 92.   -
 93.   ++UPDATE
 94.   -
 95.   /IN UPDATE, USING MERGE, MERGE $KEY
 96.   IF $NO THEN JUMP CANCEL
 97.   LET MESSAGE = 'UPDATE SUCCESSFUL FOR RECORD ' #SEARCH
 98.   LET COMMAND = ''
 99.   JUMP COMMAND
100.   -
101.   ++CANCEL
102.   -
103.   LET FUNCTION = ''
104.   LET COMMAND = ''
105.   IF $ABORT THEN LET MESSAGE = 'INPUT CANCELLED'
106.   ELSE LET MESSAGE = 'INPUT FAILED.  CODE = ' $SNUM
107.   JUMP COMMAND
108.   -
109.   ++ATTN
110.   -
111.   LET FUNCTION = ''
112.   LET COMMAND = ''
113.   LET MESSAGE = 'ATTENTION RECEIVED; TYPE "END" TO EXIT'
114.   JUMP COMMAND
115.   -
116.   ++END
117.   -
118.   LET FUNCTION = ''
119.   LET COMMAND = ''
120.   BLANK CRT
121.   LET MESSAGE = 'SESSION IS TERMINATED'
122.   IN COMMAND, XEQ FRAME CMDOUT
123.   WRITE CRT
124.   -
125.   ++EXIT
126.   -
127.   SET WRITE
128.   SET TERMINAL COMM MSG
129.   SET MESSAGES 2
130.   RESTORE SETTINGS

5.9.2  The Vgroup

 300.  VGROUP = GQ.BEC.MOVIES;
 301.  MODDATE = WED. JUNE 30, 1982;
 302.  DEFDATE = WED. MAY 26, 1982;
 303.  VARIABLE = MESSAGE;
 304.    LEN = 40;
 305.    TYPE = STRING;
 306.  VARIABLE = COMMAND;
 307.    LEN = 28;
 308.    TYPE = STRING;
 309.  VARIABLE = FUNCTION;
 310.    LEN = 8;
 311.    TYPE = STRING;
 312.  VARIABLE = SEARCH;
 313.    TYPE = STRING;
 314.    LEN = 28;
 315.  VARIABLE = CMDNUM;
 316.    TYPE = INT;
 317.    LEN = 4;

5.9.3  The Format

  400.   ID = GQ.BEC.MOVIES;
  401.   AUTHOR = Becky Morton;
  402.   MODDATE = TUES. MAY 10, 1983;
  403.   DEFDATE = MON. APRIL 5, 1982;
  404.   FILE = GQ.BEC.MOVIES;
  405.   RECORD-NAME = REC01;

5.9.3.1  Frame CMDOUT

  406.   FRAME-ID = CMDOUT;
  407.     DIRECTION = OUTPUT;
  408.     FRAME-DIM = 2,79;
  409.     USAGE = ALL, NAMED;

  410.     LABEL = FUNCTION;
  411.       VALUE = #FUNCTION;
  412.       START = 1,1;
  414.       PUTDATA;

  415.     LABEL = MOVIES;
  416.       VALUE = 'MOVIE REVIEWS';
  417.       START = *,35;
  419.       PUTDATA;

  420.     LABEL = DATE;
  421.       VALUE = $UDATE;
  422.       START = *;
  424.       OUTPROC = $DATE.OUT(DAY.MONTH)/ $SQU;
  425.       ADJUST = RIGHT;
  426.       PUTDATA;

  427.     LABEL = CLR.MESSAGE;
  428.       VALUE = ' ';
  429.       START = 2,30;
  430.       LENGTH = 50;
  431.       PUTDATA;

  432.     LABEL;
  433.       UPROC = IF ~#MESSAGE THEN JUMP COMMAND;

  434.     LABEL = MESSAGE;
  435.       VALUE = #MESSAGE;
  436.       START = 2,30;
  437.       LENGTH = 50;
  439.       ADJUST = RIGHT;
  440.       PUTDATA;

  441.     LABEL = COMMAND;
  442.       VALUE = #COMMAND;
  443.       START = 2,1;
  444.       LENGTH = 28;
  445.       DISPLAY = UNPROTECT;
  446.       PUTDATA;

  447.     LABEL = CLR.VARIABLES;
  448.       UPROC = LET COMMAND = '';
  449.       UPROC = LET MESSAGE = '';

5.9.3.2  Frame CMDIN

  450.   FRAME-ID = CMDIN;
  451.     DIRECTION = INOUT;
  452.     FRAME-DIM = 2,79;
  453.     USAGE = NAMED;

  454.     LABEL;
  455.       START = 2,1;
  456.       LENGTH = 28;
  457.       GETDATA = 5;
  458.       INPROC = $SQU;
  459.       UPROC = LET COMMAND = $CVAL;
  460.       UPROC = IF $CVAL = '' THEN JUMP NODATA;
  461.       UPROC = LET SEARCH = $RIGHTSUB(#COMMAND,' ');
  462.       UPROC = IF #SEARCH THEN LET COMMAND = $LEFTSUB(#COMMAND,' ');
  463.       UPROC = LET CMDNUM = $PMATCH($CAP(#COMMAND),DIS?PLAY, END, FIN?D,
  464.         NEX?T, MOD?IFY, CRE?ATE);
  465.       UPROC = IF #CMDNUM = 0 THEN JUMP ERR1;
  466.       UPROC = IF #CMDNUM = 2 THEN LET FUNCTION = 'END';
  467.       UPROC = THEN RETURN;
  468.       UPROC = IF #CMDNUM = 4 THEN LET FUNCTION = 'NEXT';
  469.       UPROC = THEN RETURN;
  470.       UPROC = IF #CMDNUM = 6 THEN LET FUNCTION = 'CREATE';
  471.       UPROC = THEN RETURN;
  472.       UPROC = IF #SEARCH = '' THEN JUMP ERR2;
  473.       UPROC = IF #CMDNUM = 1 THEN LET FUNCTION = 'DISPLAY';
  474.       UPROC = THEN RETURN;
  475.       UPROC = IF #CMDNUM = 3 THEN LET FUNCTION = 'FIND';
  476.       UPROC = THEN RETURN;
  477.       UPROC = IF #CMDNUM = 5 THEN LET FUNCTION = 'MODIFY';
  478.       UPROC = RETURN;

  479.     LABEL = NODATA;
  480.       UPROC = LET MESSAGE = 'YOU MUST ENTER A COMMAND';
  481.       UPROC = LET FUNCTION = 'COMMAND';
  482.       UPROC = RETURN;

  483.     LABEL = ERR1;
  484.       UPROC = LET MESSAGE = 'INVALID COMMAND - TRY AGAIN';
  485.       UPROC = LET FUNCTION = 'COMMAND';
  486.       UPROC = RETURN;

  487.     LABEL = ERR2;
  488.       UPROC = LET MESSAGE = 'COMMAND REQUIRES AN OBJECT';
  489.       UPROC = LET FUNCTION = 'COMMAND';
  490.       UPROC = RETURN;

5.9.3.3  Frame OUT

  491.   FRAME-ID = OUT;
  492.     DIRECTION = OUTPUT;
  493.     FRAME-DIM = 24,79;

  494.     LABEL = TITLE;
  495.       GETELEM;
  496.       DEFAULT = 'Title';
  497.       START = 5,5;
  498.       LENGTH = 50;
  500.       PUTDATA;

  501.     LABEL = RELEASE.YEAR;
  502.       GETELEM;
  503.       TITLE = 'Released:';
  504.       TSTART = 5,61;
  505.       DEFAULT;
  506.       START = 5,72;
  507.       LENGTH = 4;
  509.       PUTDATA;

  510.     LABEL = STAR;
  511.       GETELEM;
  512.       TITLE = 'Starring:';
  513.       TSTART = 7,7;
  514.       DEFAULT;
  515.       START = 8,10;
  516.       LENGTH = 25;
  518.       PUTDATA;
  519.       LOOP = 5;

  520.     LABEL = DIRECTOR;
  521.       GETELEM;
  522.       TITLE = 'Directed by:';
  523.       TSTART = 7,42;
  524.       DEFAULT;
  525.       START = 8,45;
  526.       LENGTH = 25;
  528.       PUTDATA;

  529.     LABEL = RATED;
  530.       GETELEM;
  531.       TITLE = 'Rated:';
  532.       TSTART = 13,45;
  533.       DEFAULT = NR;
  534.       START = 13,52;
  535.       LENGTH = 2;
  537.       PUTDATA;

  538.     LABEL = RATING;
  539.       GETELEM;
  540.       TITLE = 'Rating:';
  541.       TSTART = 15,5;
  542.       DEFAULT = NR;
  543.       START = 15,14;
  544.       LENGTH = 4;
  546.       PUTDATA;

  547.     LABEL = REVIEW;
  548.       GETELEM;
  549.       DEFAULT = review;
  550.       MARGINS = 5,75;
  551.       MAXROWS = 7;
  552.       START = 16,5;
  554.       PUTDATA;

  555.     LABEL = REVIEWER;
  556.       GETELEM;
  557.       TITLE = 'Reviewed by:';
  558.       TSTART = 23,5;
  559.       DEFAULT;
  560.       START = 23,19;
  561.       LENGTH = 25;
  563.       PUTDATA;

  564.     LABEL = REVIEW.DATE;
  565.       GETELEM;
  566.       DEFAULT;
  567.       START = 23,47;
  568.       LENGTH = 8;
  570.       PUTDATA;

5.9.3.4  Frame MERGE

  571.   FRAME-ID = MERGE;
  572.     DIRECTION = INOUT;
  573.     FRAME-DIM = 24,79;
  574.     USAGE = NAMED, MERGE;

  575.     LABEL;
  576.       IND-FRAME = INPUT;

  577.     LABEL;
  578.       UPROC = IF ~$GPROCERR THEN RETURN;

  579.     LABEL;
  580.       UPROC = LET MESSAGE = 'ERROR FOUND, CORRECT AND RESEND';

  581.     LABEL;
  582.       VALUE = #MESSAGE;
  583.       START = 2,30;
  584.       LENGTH = 50;
  586.       ADJUST = RIGHT;
  587.       PUTDATA;

  588.     LABEL;
  589.       UPROC = LET MESSAGE = '';
  590.       UPROC = REPROMPT;

5.9.3.5  Frame ADD

  591.   FRAME-ID = ADD;
  592.     DIRECTION = INOUT;
  593.     FRAME-DIM = 24,79;
  594.     USAGE = FULL, NAMED;

  595.     LABEL;
  596.       IND-FRAME = INPUT;

  597.     LABEL;
  598.       UPROC = IF ~$GPROCERR THEN RETURN;

  599.     LABEL;
  600.       UPROC = LET MESSAGE = 'ERROR FOUND, CORRECT AND RESEND';

  601.     LABEL;
  602.       VALUE = #MESSAGE;
  603.       START = 2,30;
  604.       LENGTH = 50;
  606.       ADJUST = RIGHT;
  607.       PUTDATA;

  608.     LABEL;
  609.       UPROC = LET MESSAGE = '';
  610.       UPROC = REPROMPT;

5.9.3.6  Frame INPUT

  611.   FRAME-ID = INPUT;
  612.     DIRECTION = INOUT;
  613.     FRAME-DIM = 24,79;

  616.     LABEL = CANCEL.CHECK;
  617.       START = 2,1;
  618.       LENGTH = 28;
  619.       GETDATA = 5;
  620.       INPROC = $SQU/ $CAP;
  621.       UPROC = IF $PMATCH($CAP($CVAL),CAN?CEL) = 1 THEN ABORT;

  622.     LABEL = TITLE;
  623.       START = 5,5;
  624.       LENGTH = 50;
  625.       GETDATA = 8;
  626.       PUTELEM;

  627.     LABEL = RELEASE.YEAR;
  628.       ESTART = 5,58;
  629.       START = 5,72;
  631.       GETDATA = 5, 7, 8;
  632.       INPROC = $MSG(A2)/ $INT(4);
  633.       PUTELEM;

  634.     LABEL = STAR;
  635.       START = 8,10;
  636.       LENGTH = 25;
  637.       GETDATA = 8;
  638.       PUTELEM = STAR;
  639.       LOOP = 5;
  640.       XSTART = X,10;

  641.     LABEL = DIRECTOR;
  642.       START = 8,45;
  643.       LENGTH = 25;
  644.       GETDATA = 5, 7, 8;
  645.       PUTELEM;

  646.     LABEL = RATED;
  647.       ESTART = 13,42;
  648.       START = 13,52;
  649.       LENGTH = 2;
  651.       GETDATA = 5, 7, 8;
  652.       INPROC = $MSG(A5)/ $ENCODE('P, PG, R, X, NR');
  653.       PUTELEM;

  654.     LABEL = RATING;
  655.       ESTART = 15,2;
  656.       START = 15,14;
  657.       LENGTH = 4;
  659.       GETDATA = 5, 7, 8;
  660.       INPROC = $MSG(A6)/ $ENCODE('*, **, ***, ****, NR');
  661.       PUTELEM;

  662.     LABEL = REVIEW;
  663.       MARGINS = 5,75;
  664.       MAXROWS = 7;
  665.       START = 16,5;
  666.       GETDATA = 5, 7, 8;
  667.       INPROC = $SQU;
  668.       PUTELEM;

  669.     LABEL = REVIEWER;
  670.       START = 23,19;
  671.       LENGTH = 25;
  672.       GETDATA = 5, 7, 8;
  673.       PUTELEM;

  674.     LABEL = REVIEW.DATE;
  675.       ESTART = 23,44;
  676.       START = 23,47;
  677.       LENGTH = 8;
  679.       GETDATA = 5, 7, 8;
  680.       INPROC = $MSG(A8)/ $DATE;
  681.       PUTELEM;

5.9.3.7  Frame Declaration Section

  682.   FORMAT-NAME = MOVIE.DIS;
  683.     ALLOCATE = ORV.GQ.BEC.MOVIES;

  684.     FRAME-NAME = CMDOUT;
  685.       FRAME-TYPE = XEQ;
  686.       UPROC = SET PADCHAR = $TERMPAD;
  689.       UPROC = SET PROTECT;
  690.       UPROC = SET AUTOTAB;

  691.     FRAME-NAME = CMDIN;
  692.       FRAME-TYPE = XEQ;
  695.       UPROC = SET PADCHAR = $TERMPAD;
  696.       UPROC = SET PROTECT;

  697.     FRAME-NAME = OUT;
  698.       FRAME-TYPE = DATA;
  701.       UPROC = SET PADCHAR = $TERMPAD;
  703.       UPROC = SET AUTOTAB;
  703.1      UPROC = SET DISPLAY = 'UNPROTECT,A48';
  703.2      UPROC = SET TDISPLAY = 'PROTECT,A8';

  704.     FRAME-NAME = INPUT;
  705.       FRAME-TYPE = INDIRECT;

  710.     FRAME-NAME = MERGE;
  711.       FRAME-TYPE = DATA;
  714.       UPROC = SET PADCHAR = $TERMPAD;
  715.       UPROC = SET PROTECT;
  715.1      UPROC = SET EDISPLAY = 'A16,E8';
  715.2      UPROC = SET ELENGTH = 2;
  715.3      UPROC = SET DISPLAY = A16;

  716.     FRAME-NAME = ADD;
  717.       FRAME-TYPE = DATA;
  720.       UPROC = SET PADCHAR = $TERMPAD;
  721.       UPROC = SET PROTECT;
  721.1      UPROC = SET EDISPLAY = 'A16,E8';
  721.2      UPROC = SET ELENGTH = 2;
  721.3      UPROC = SET DISPLAY = A16;

5.9.4  The File Definition

This is the File Definer input used to generate the file definition. The file definition code is available as WYL.GQ.DOC.MOVIES.FILEDEF ON CAT.

FILE MOVIES/ BIN PURGE
SUBFILE MOVIES/ ACCOUNT PUBLIC
FIXED
DATE.ADDED/ DATE ADD
DATE.UPDATE/ DATE UPDATE
OPTIONAL
TITLE, T/ OCC 1/ INDEX/ WORD
RELEASE.YEAR, RY/ OCC 1/ LEN 4/ INT/ INDEX
STAR, STA, STR/ NAME/ OCC 6/ INDEX
DIRECTOR, DIR/ NAME/ INDEX STAR
RATED, RAT, RTD/ OCC 1/ ENCODE P,PG,R,X,NR/ INDEX
RATING, RTG/ OCC 1/ ENCODE *,**,***,****,NR/ INDEX
REVIEW,REV
REVIEWER, REVR, RVR/ OCC 1/ NAME/ INDEX
REVIEW.DATE, REVD, RD, RVD/ OCC 1/ DATE/ INDEX

6  Display Attributes and Specific Terminal Characteristics

Some area attributes are valid only for terminal devices because the attributes specify display characteristics or screen related functions. This chapter describes those attributes and how they apply to the specific terminals that SPIRES supports.

SPIRES recognizes what kind of terminal you are using by what you have indicated with the SET TERMINAL command. This must be issued before the CALL SPIRES command. SPIRES recognizes four terminal types: Model Terminal, IBM 3270s, Tektronix (terminal type TEK4023D), and Zentecs. To find out what types of terminals are supported as Model Terminals, issue the WYLBUR command HELP TERMINAL TYPE.

When you are using a terminal as a Model Terminal, the ENTER key may not function as it does for other terminals. When using a Model Terminal, the RETURN key should be used to transmit information to the computer.

If you do not set your terminal type, SPIRES will assume that you are either a line-by-line terminal or a Zentec, depending on your terminal connection (i.e., which front-end you are using). To avoid any possible misinterpretation, it is recommended that you always set the terminal type.

The terminal ID does not have any effect on full-screen SPIRES. The ID is used to set the $TERMINAL variable, which can be tested in applications.

All display attributes are available for full-screen terminals, i.e., for the CRT area and all areas defined on CRT. Some display attributes can be used in line-by-line mode for areas defined on TER. [See 6.1.5.]

The general descriptions of terminal attributes in this chapter assume that you are using Model Terminal. Differences for the IBM and Tektronix are noted where appropriate.

6.1  General Rules for Specifying Display Attributes

Display attributes determine how values appear on the screen; primarily they specify emphasis (blinking, reverse video, etc.) and alternate character sets (color and ruling font). They can be specified for an area, format frame, or label group, or any combination of these. You can specify an attribute for an area to set up a default for that area and alter specific fields from a format. Or by restricting areas to not allow an executing format to alter certain characteristics, you can use the same format code to display values differently in different areas.

At the highest level, an attribute can be defined for an area to determine the display characteristics for all the fields -- foreground and background -- in the area. The area attribute is specified on the DEFINE AREA command. [See 3.1.] This specification sets up a default for the area and, in some cases, determines if a format can override it.

Several display Uprocs are available to specify display characteristics at the frame level. They are:

With these Uprocs you can control separately the display characteristics for all data fields, titles, and error messages. They are included in the frame declaration section of the format definition and apply to that frame and all indirect frames called by that frame. They can also be included in a label group to change the specification for subsequent label groups in the format, overriding the global Uproc for those label groups.

Display Uprocs might override the area specification for a particular attribute, and might themselves be overridden by a display Uproc or a DISPLAY statement in the label group.

For example, let's say we have an area defined with the following command:

All fields in the area will be displayed in white if the terminal in use is capable of color. But if we defined a format that included the following Uproc in the frame declaration section:

the area attribute would be overridden whenever this frame was executed in that area, and the fields would be displayed in pink. However, we could then include a DISPLAY statement in a single label group as follows:

and the value placed by that single label group would be in red. That too could be overridden, if need be, by a SET DISPLAY Uproc in the label group, e.g.:

An important format detail: If you have an indirect frame whose label groups specify different display attributes but the calling label group includes a PUTDATA statement, all the attributes within the indirect frame are ignored. That's because the PUTDATA statement tells SPIRES to treat the indirect frame's output as a single value to place, which must all have the same attributes. And those attributes would be determined not by anything within the indirect frame, but by whatever attributes were defined for the calling label group. If you want the indirect frame's attributes to be effective, do not code a PUTDATA statement in the calling label group.

6.1.0  Display Attributes for Specific Types of Fields

It is generally recommended that applications developed in SPIRES and Prism use the same attributes for various types of data on input screens. It is quite helpful to the user (who might have to work with many different applications) if, for example, all applications mark input errors with red, blinking error flags, and use yellow and green to distinguish between required and optional input fields.

SPIRES has some standard attribute terms that can be specified on a DISPLAY statement in a format, or in the format Uprocs SET DISPLAY, SET TDISPLAY and SET EDISPLAY, or in a $SETAREA function. They each invoke a standard set of attributes for the field:

REQUIRED                 =  Unprotected, Yellow, Bright, Underline
 (an input field for
  required data)
OPTIONAL                 =  Unprotected, Green,          Underline
 (an input field for
  optional data)
DATA                     =  Protected,   White,  Bright
 (a field for protected
  data)
TITLE                    =  Protected,   Cyan
 (a field identifying a
  data field)
TEXT                     =  Protected,   White
 (a field for non-data
  information)
ERROR                    =  Protected,   Red,    Bright, Blinking
 (a field near an input
  field for marking errors)
WARNING                  =  Protected,   Pink,   Bright, Blinking
 (a field for marking
  warning errors)

Besides helping to make SPIRES and Prism applications consistent, these attributes make code easier to write and read too.

You can specify a field-type attribute and make alterations to it too, if you want, by adding other attributes after it. For example, if you wanted to use the TITLE attributes with a ruling font character set, you might code the following in a label group:

Or, if you want to define a protected, bright, blinking, yellow field, you could specify:

which is simpler than:

6.1.1  The DISPLAY Statement

The DISPLAY statement is included in a label group to specify the display attributes for the value placed by that label group. Attributes specified with the DISPLAY statement only apply to data values -- values extracted from records, or specified in a VALUE statement or DEFAULT statement (i.e., $CVAL). Titles are not affected.

The statement is in the form

where "attribute" is one of the display attributes described in this chapter, e.g., E2, A6, or DETECT. (PROTECT may also be specified on the DISPLAY statement; [See 3.1.2.] for details on the use of this attribute.)

The inclusion of a DISPLAY statement in a label group will cause all attributes specified for the frame with a SET DISPLAY Uproc to be overridden unless an area or frame attribute is more restrictive than that specified in the label group. For example, if an area is assigned the NOUNDERLINE attribute, a specification of UNDERLINE in a label group will have no effect in that area.

Attributes are only output from frames that actually do output. They are NOT returned from an indirect frame when PUTDATA is done by the calling frame.

If you have an input frame that provides for the display of error messages, [See 5.6.3.] the DISPLAY statement can be used to specify display characteristics for that single message, if no SET EDISPLAY Uproc is included. [See 6.1.4.] A DISPLAY statement does not override a SET EDISPLAY Uproc. DISPLAY attributes may also be set by the $SETAREA function. [See 4.5.]

6.1.2  The SET DISPLAY Uproc

The SET DISPLAY Uproc is put in the frame declaration section of a format definition to specify that all values placed by that frame will have the specified display characteristics. An individual label group can override this specification by including a DISPLAY statement. Like the DISPLAY statement, this only affects $CVAL, the value placed by the START or XSTART statements. Titles and error messages are not affected.

The syntax is:

Multiple attributes may be specified, separated by commas, with the entire list enclosed in apostrophes. A variable may also be used (i.e., SET DISPLAY = #variable).

If a SET DISPLAY Uproc is put in a label group it sets the display characteristics for that and all subsequent label groups in that format frame. If you later want to cancel the display setting for subsequent label groups, you can set the display to null with the following Uproc:

This overrides the global display setting, and the current and all subsequent label groups will revert to the area default.

6.1.3  The SET TDISPLAY Uproc

The SET TDISPLAY Uproc is put in the frame declaration section of a format definition to specify that all titles placed by that frame will have the specified display characteristics. If this Uproc is not included for a frame, all titles will default to the display characteristics specified for the area.

The syntax is similar to the SET DISPLAY Uproc and can be in any of the following forms:

A SET TDISPLAY Uproc can be included in an individual label group to change the titles for all subsequent label groups in the format frame. It does not affect the current label group. If you later want to cancel the display setting for subsequent label groups, you can set the display to null with the following Uproc:

This overrides a global title display setting and all titles for subsequent label groups will revert to the area default.

6.1.4  The SET EDISPLAY and SET ELENGTH Uprocs

The SET EDISPLAY and SET ELENGTH Uprocs are used to specify the length and display characteristics for error message fields displayed when a REPROMPT is executed. [See 4.7.5, 5.6.3.]

The SET ELENGTH Uproc sets the length of the error field. It can be included in the frame declaration section of the format definition to set the length for all error fields in the frame, or in a label group to change the error field length for subsequent label groups. Anytime the SET ELENGTH Uproc appears, it resets the global elength value. If you need to be certain that it affects the current label group, add it as an entry-Uproc. The syntax is:

You can also use the ELENGTH statement in a label group to set the error field length for the current label group. It is in the form

This will locally override whatever global elength value is in effect but does not reset the global elength value.

The SET EDISPLAY Uproc determines the display characteristics for the error message. It can be in either the frame declaration section to set the characteristics for every error field in the frame, or it can be included in a label group to set the characteristics for the error field of all subsequent label groups. If no SET EDISPLAY Uproc is included, the error message defaults to the display characteristics specified by the DISPLAY statement. Error messages are not affected by a SET DISPLAY Uproc.

The Uproc can be in any of the following forms:

If you later want to cancel the display setting for subsequent error messages, you can set the display to null with the following Uproc:

This overrides a global EDISPLAY setting and all subsequent error fields will have the characteristics determined by a DISPLAY statement, or will revert to the area default.

6.1.5  Using Display Attributes with the TER Area

Some display attributes can be used in line-by-line mode when used with a Model Terminal. You can specify emphasis levels, color, and underlining for values to be displayed in the TER area or in an area defined on TER. For example, if you have a format that includes DISPLAY statements to specify emphasis levels (e.g., reverse video), color, or underlining, and you display a record through the TER area using that format as follows:

the record will be displayed on the terminal screen in line-by-line mode with the specified display attributes.

Another example is defining display attributes for an area defined on TER:

This defines an area that all system messages will be sent to; messages will appear on the screen underlined in reverse video on a blue background if the terminal supports those attributes.

The TER area will not display ruling font characters, and you cannot specify AUTOTAB or DETECT for TER areas. Non-Model Terminals will not accept display attributes for TER areas, and 3270-type terminals cannot display underlining in line-by-line mode.

As always, the display characteristics that you actually get are determined by the physical capabilities of the terminal in use.

6.1a  Controlling the Terminal Screen: The SET CRT Command

The SET CRT command lets you specify characteristics that affect the way the terminal screen behaves when certain keys are pressed or when the Ask Uproc is executed in a format. It can only be issued for areas defined on the CRT area or the CRT area itself. The syntax is:

"Type" is either COMMAND, WARN, or HOME; each type is described below. The "location" can be an area name or a specific location on the screen. A location is defined by three integers separated by commas, representing row, column, and length, in that order. If row or column is not included, 1 is assumed. If a length specification is not included, the remainder of the row beginning at the specified column is used.

If you issue multiple SET CRT commands with the same "type", the settings will replace the currently set values. In other words, only one setting for any one type can be in effect. If you wish to cancel a setting, issue one of the following commands:

The COMMAND type specifies that the area is to be used as the default area for all output and input from an Ask Uproc in a format. Because the area is being used for both output and input, it must also be valid for IODATA.

For example, if you set up the following area:

and you then execute a format that includes the Uproc

the prompt will be placed at the beginning of the first unprotected field in the ASKNAME area and the CRT area will be automatically written. After the user types in a response and presses RETURN, the response is placed in the $ASK variable.

The WARN type lets you place a "[WAIT]" indicator on the screen to warn the user that SPIRES is processing a command and cannot accept input from the keyboard. This is only valid for Model Terminals. For example,

would place the "[WAIT]" indicator on row 20 at column 55 whenever the user presses the RETURN key. The indicator disappears when SPIRES completes the command.

The HOME type lets you specify a location on the screen as "home". As the user moves around the screen using the TAB key and the cursor positioning keys, this location remains "home", and whenever the user presses the HOME key, the cursor will return to this location. If the user then presses the HOME key again, the cursor will return to the most recent location of the cursor that was not on the same line as the home position.

The actual home location is the first TAB stop at the beginning of the first unprotected field at or beyond the position defined as "home". (TAB positions are established by the use of the AUTOTAB statement as the first position of each unprotected field. [See 6.6.] Specifying a home location does not override the CURSOR location specified on the WRITE or READ command when the screen is first written.

For example,

causes the home position to be the first TAB position after row 5, column 20.

If there is no home position defined, or there are no unprotected fields that begin at or beyond the specified position, then the CURSOR position becomes the home position.

The SET CRT MODE Command

Another flavor of the SET CRT command is:

     SET CRT MODE options

There are two options currently available:

 1)  REPLACE [ON|OFF]

If this option is specified as REPLACE or REPLACE ON, then the model terminal CRT driver will not discard changes made to the current screen if the user presses the ATTN/BREAK key. If the option is specified as REPLACE OFF (the default condition if the command SET CRT MODE REPLACE is not issued at all), then any changes made to the screen before the ATTN/BREAK key is pressed will be discarded. Another WRITE CRT command will refresh the original screen.

 2)  SAVE [CONTinue] [ON|OFF]

If this option is specified as SAVE or SAVE ON, then screen images will be saved for later restoration. If the option is specified as SAVE OFF (the default condition if the command SET CRT MODE SAVE is not issued at all), then screen images will no longer be saved.

The SHOW CRT Command

To look at the current settings for the CRT area, issue the SHOW CRT command. You can use the IN ACTIVE prefix to place this information in your active file.

6.2  Emphasis Attributes

EMPHASIS is an area attribute that determines the degree of visibility of the characters on the terminal screen. It can be used to set reverse video, blinking, bright or hidden fields, for instance.

EMPHASIS can be specified in the DEFINE AREA command, in the $SETAREA function, in the DISPLAY statement in a format label-group, or in the format Uprocs SET DISPLAY, SET TDISPLAY and SET EDISPLAY. It is specified in one of the following forms:

where "n" is an integer from 0 to 63, and "emphasis-term" is a descriptive emphasis term, chosen from the list that appears below. Note that you cannot use the "En" form in the DEFINE AREA command.

For Model Terminal, emphasis levels are as follows:

     Emphasis terms:
       REVERSE    <- for reverse video
       BLINKING
       BRIGHT
       HIDE       <- for hidden fields
     "En" values:
         E0       default emphasis for area
       E1 - E4    normal
       E5 - E9    blinking
      E10 - E15   reverse video
      E16 - E31   normal
      E32 - E47   reverse video, blinking
      E48 - E62   reverse video
         E63      blanked

If your terminal supports bright emphasis (as do some VT-1xx and IBM terminal types), then E9, E31, E47, and E62 provide bright emphasis in addition to the emphasis already provided by that range. For example, E47 provides a bright, blinking, reverse video field if your terminal supports bright emphasis.

Level 63 creates a non-printed field, that is, one that does not display what the user is typing. This is used primarily for keywords or other "secret" codes. Whatever the user types in the field remains in that field as the area is read and written to the device, but it does not appear on the device. If the field is unprotected, the user may change the field at any time, allowing the program to check the contents of the field for a password, or security check. If the field is protected, the data in that field will be written to and read from the device, but the user will not be able to see or change it.

Other terminals will come as close to the Model Terminal interpretation as allowed by the physical hardware. The 3270 terminals and the Tektronix terminals translate emphasis levels differently. [See 6.9.2, 6.10.2.]

In general, it is recommended that you do not interchange the "term" method and the "En" method. [But even SPIRES breaks that rule in at least one situation: if you use the "term" method in a DEFINE AREA command, the SHOW AREA command shows the value in the converted form "EMP n".] Two or more terms can be used together (e.g., BLINKING, REVERSE), but if you specify two "En" values, the second will undo the first.

Similarly, if you follow a term with an "En" value, as in "BRIGHT, E5", the "En" value will cancel the term. The reverse is also true: a term following an "En" value will cancel the "En" value.

A DISPLAY statement can be included in a label group to specify an emphasis level for the individual field.

You can specify an emphasis level for an entire format frame by including one of the display Uprocs in the frame declaration section of the format; these are SET DISPLAY for data values, SET TDISPLAY for titles, and SET EDISPLAY for error messages. [See 6.1.] For example,

Minimum Emphasis Levels for Areas

If you do not include an EMPHASIS specification on the DEFINE AREA command or if you specify EMPHASIS 0, all fields will be displayed at the default level for the area, unless an executing format frame specifies differently for one or more fields.

If you include an EMPHASIS specification on the DEFINE AREA command, it determines the minimum emphasis level for the entire area; an executing format can specify a higher emphasis level, but not a lower one. The same rule applies to hierarchical areas. For example, if you define an area named BOTTOM with an emphasis level of 24, you could not define an area ON BOTTOM with an emphasis level lower than 24. If you issued the command

the emphasis level for area TOP would become 24. You could achieve the desired result, however, by specifying EMPHASIS 0 for area TOP and specifying an emphasis level of 12 in a format frame. EMPHASIS 0 allows you to specify any emphasis level regardless of a minimum level that might be already established.

Including NOEMPHASIS on the DEFINE AREA command will create an emphasis level of 16 (normal) and will not allow an executing format frame to override it.

6.3  Color and Alternate Character Set Attributes

ALTCHAR is an attribute that specifies an alternate character set to be used as the default character set for an entire area or field. For applications on the IBM 3270s and Model Terminals that support color, it is most often used to specify that the ruling font be used (for drawing boxes, for example) or that the data should be displayed in a different color, if a color terminal is being used.

ALTCHAR may be specified in the DEFINE AREA command, in the $SETAREA function, in the DISPLAY statement in a format label-group, or in the format Uprocs SET DISPLAY, SET TDISPLAY and SET EDISPLAY. It is specified in one of the following forms:

where "n" is an integer from 0 to 255 that specifies the number of the character set, while "altchar-term" is a term that describes the color or specifies the ruling font. A value of 0 for "n" or the term NOCOLOR, meaning "the Standard Character Set," is the default value.

Other values represent "Alternate Character Sets" and are used to indicate different fonts, positions (subscript or superscript), or color. For Model Terminals, the terms that can be specified are:

You can specify both RULING and a color (or NOCOLOR) if you want; but if you specify two colors at once, only the second will go into effect.

If you want to use the "n" or "An" forms, the value specifies which color and which character set (ruling font or standard) according to the following chart:

Note: "Default" or NOCOLOR on a 3279 indicates that unprotected fields are displayed in green, protected fields are displayed in blue, and bright fields are displayed in white. The default for other terminals varies.

Thus, the statement

will produce red ruling font. How to use a ruling font is discussed in the next section. [See 6.3.1.]

Although the "term" method lets you supply both RULING and one of the colors, you should not specify multiple values of "An" in a command or statement -- if you do, only the last one given has any effect.

In general, you should not interchange the "term" method and the "An" method. [Sometimes SPIRES does, though: if you use the "term" method in a DEFINE AREA command, the SHOW AREA command shows the value in the converted form "ALT n".] If you follow a term with an "An" value, as in "RED, A1", the "An" value will cancel the term, and vice versa.

No hierarchy is assumed between alternate character sets; that is, if ALTCHAR is used in the DEFINE AREA command, areas that are contained by the named area are not affected by this parameter.

The character set specified on the DEFINE AREA command determines the character set to be used as a default for the area; a different alternate character set can be specified for an entire format frame with one of the display Uprocs, or for an individual field by including a DISPLAY statement in the label group. [See 6.1.]

Currently the ruling font character set is supported for Model Terminals, the Tektronix, and the IBM 3270s. (Note, however, that not all terminals will have the ruling font character set installed.) Color is supported for the IBM 3279 and some Model Terminals.

6.3.1  The Ruling Font Character Set

To get the ruling font character set, specify the attribute RULING or "An" or "ALTCHAR = n". where "n" is an odd number from 1 to 255. If the terminal also supports color, the different numbers specify the ruling font in various colors. [See 6.3.]

If the terminal is not physically equipped with the specific ruling font character, SPIRES translates it to the closest possible choice. For example, all double-line ruling font are translated to single-line ruling font if that is all the terminal supports. If your terminal does not have a ruling font character set, no translation takes place.

Ruling font characters can only be displayed in protected fields. The characters that are specified in a format to indicate which of the ruling font characters are to be displayed are indicated as follows:

For example, the top line of a small box -- left corner, horizontal line, right corner -- would be written with the following label group in a format:

6.4  PTUNDERLINE|UNDERLINE|NOUNDERLINE and DISPLAY = UNDER

The PTUNDERLINE, UNDERLINE, and NOUNDERLINE attributes are used to control the underlining of fields on the screen. The specification included on the DEFINE AREA command determines the underlining for the entire area.

PTUNDERLINE is the default; if specified on the DEFINE AREA command, no special action takes place, but an executing frame may specify underlining of specific fields by including one of the display Uprocs [See 6.1.] or by including a DISPLAY statement in the label group. [See 6.1.1.]

If UNDERLINE is specified, each data field within the area will be underlined. This cannot be overridden by a DISPLAY statement.

NOUNDERLINE will override the specification of an executing frame, and no underlining will be done.

Note that not all terminals that can be run as Model Terminal have the underline capability. Refer to your terminal manual.

6.5  PTNUMERIC|NUMERIC|ALPHANUMERIC and DISPLAY = NUMERIC

The numeric field attributes allow a field to be restricted to accept only numeric data. For Model Terminals, "numeric" data is defined as all numerals (0-9), the minus sign (-), the decimal point (.), the dollar sign ($), the plus sign (+), and the slash (/). This differs for the IBM 3270s [See 6.9.2.] and the Tektronix. [See 6.10.4.] It does not affect the display of data.

Like the display attributes, the specification included on the DEFINE AREA command determines the characteristic of the entire area; this can be overridden for an individual field within that area by including a DISPLAY statement of the form "DISPLAY = NUMERIC" in the label group. A Uproc in the form "UPROC = SET DISPLAY = NUMERIC" may be included in the frame declaration section of the format definition to affect every label group in the frame. Because this attribute only affects the input of data, it is not allowed with the SET TDISPLAY and SET EDISPLAY Uprocs. [See 6.1.]

PTNUMERIC is the default for an area definition, and specifies that no special action is to take place. An executing frame may specify that a field is to accept numeric data only by including the "DISPLAY = NUMERIC" statement in the label group.

If NUMERIC is specified, then each data field within the area will be restricted to accept numeric data only. This cannot be overriden by a DISPLAY statement.

If ALPHANUMERIC is specified, an executing frame specifying "DISPLAY = NUMERIC" is overridden, and the field will accept any data character.

Note that this specification affects the terminal only; you would probably also want to verify the data with INPROC rules, since not all terminals are capable of NUMERIC checking.

6.6  Autotab Specification

Model Terminals and IBM 3270s have the capability to automatically tab from one field to the next. The statement

specifies that when the user attempts to type past the last character position in this unprotected field, the cursor tabs to the next unprotected field on the screen.

The statement

can be specified in the frame declaration section of the format to indicate that all fields written by the particular frame are autotab fields.

6.7  Function Key Determination

Function keys can be used by the user to respond to a screen display. The function call

can be used after a READ to determine which key was pressed by the user to complete the READ. The integer values returned from the function and their meanings are shown in the table below:

6.7.1  (Function Keys on VT100-Type Terminals)

When using a VT100-type terminal in full-screen mode in SPIRES, you can use the keypad to do page mode editing when making modifications to records being displayed. The following diagram shows how the keys on the keypad function.

+-----------------------+   PW Key -- moves cursor to previous word.
| PW  | NW  | BF  | EF  |   NW Key -- moves cursor to next word.
|-----------------------|   BF Key -- moves cursor to the beginning
| PF7 | PF8 | PF9 | I   |             of the field.
|-----------------------|   EF -- moves cursor to the end of
| PF4 | PF5 | PF6 | DW  |         the field.
|-----------------------|   I -- allows you to insert characters.
| PF1 | PF2 | PF3 |     |        (works as toggle switch)
|-----------------|HOME |   DW -- deletes the word where the
|    PF0    | DC  |     |         cursor is placed.
+-----------------------+   DC -- deletes a single character.

The HOME key allows you to move the cursor around the screen. When each screen is written, the initial position of the cursor is considered true home. Use of the HOME key will always return the cursor to this position. If the cursor is on a different line from true home when the HOME key is pressed, that position becomes alternate home. If the cursor is at true home, pressing the HOME key will move the cursor to the alternate home once one is defined.

The PF keys function as described in the previous section. [See 6.7.]

If you run your terminal as a Model Terminal type VT100NP, some keys on the keypad function differently. The numeric keys (0-9, period, and minus sign) will function as numeric characters, and the ENTER key functions the same as the RETURN key. The other keys function as they do for type VT100.

6.8  PTDETECT|DETECT|NODETECT and DISPLAY = DETECT

You can specify that all fields in the area are detectable by including the DETECT attribute on the DEFINE AREA command. [See 3.1.] The default for an area is PTDETECT, which allows an executing format to enable a field for detection by including a DISPLAY = DETECT statement in the label group. If you specify NODETECT as an area attribute, an executing format cannot override it with a DISPLAY statement.

DETECT makes a field unprotected, thus allowing the field to be altered to signal detection. For example, the user can type a character in the field to indicate that they are selecting that field. The last altered DETECT field (left to right, top to bottom) establishes the value of $CROW and $CCOL (cursor row/column), which can be reported by the $GETAREA function.

See Section 5.8.6 for a brief description of how this can be applied in menu-driven applications.

6.9  The IBM 3270 Terminals

Full-face device support is available in SPIRES for the following IBM hardware devices:

The 3278 Model 3 is the standard supported device at Stanford.

The above 3278 models have "bright" emphasis (a field is displayed brighter than other fields) as a standard feature; it is highly recommended that the following options be ordered in addition to this "standard" for 3278 terminals for full-face SPIRES applications:

(Note: the "B" models of the 3279 have the 3610 and 1120 options as standard features.)

Any IBM terminals other than the 3278-2 and the 3279's listed above should have the 3610 option to function properly with full-face SPIRES.

Other features and devices -- such as down-line loadable character sets and the 3287 printer -- can be described by I.T.S. Communications Services.

The following documentation assumes a 3278 Model 3 with the 3610 and 1120 options.

The IBM 3270s have the following special characteristics:

 - Support for seven colors is available on the 3279.
 - "Dim" field emphasis is not available; in its place, "bright" emphasis is
 available.  "Underline" is available as an emphasis level on the 3270s.
 - "Cursor Detect" (nominally for light-pen detection) is  available  via  the  CURSOR
 SELECT  key  to  allow  the  user  rapidly  to  fill  in or check a box or boxes on a screen.
 - Different screen sizes are supported; SPIRES asks the terminal the size of its screen when it
 first defines an area on CRT.  (Note: IBM models without the  3610  option  cannot  recognize
 this  question  when  SPIRES  asks  it,  so a status message of "X PROG471" will be
 displayed along with a "TRANSMISSION ERROR" message, and the user  MUST  press  the
 Reset  key  to  continue.   SPIRES  assumes  the  screen size for such terminals to be 24x80.
 However, if you have a terminal with a 32-line screen, you can issue the WYLBUR  command  SET
 HEIGHT 0,32 and SPIRES will know that your terminal screen has 32 lines.
 - The 3278-2 and 3278-3 provide a denser dot  matrix  character  than  other  3270s  and  other
 terminals.   These  are  ideal  for  intensive CRT-use applications where readability without
 eyestrain for long periods is important.
 - The  first  reference  to  the  CRT  area  in  any  SPIRES  statement  (e.g.,  "IN   CRT
 command") will cause the screen to be blanked on the 3270s.

6.9.1  Emphasis Levels

Emphasis levels for the IBM 3270s to control blinking, reverse video, underlining, bright, and private (blanked) fields are specified with the EMPHASIS area attribute, the display Uprocs, and the DISPLAY statement. [See 6.2.] The "En" value specifies the characteristics of the field according to the following chart:

(* Bright displays only on the 3278.)

Some combinations of attributes are not possible because of terminal hardware limitations. For example, you cannot have a field that is blinking and underlined, or reverse video and underlined. If the combination is not explicitly listed in the above chart, it cannot be specified.

If "DISPLAY = DETECT" is specified, and an emphasis level of E24 or higher is given, then the field is displayed with bright emphasis. Frequently, DETECT is specified only to get bright emphasis; the fact that the field is detectable is of no consequence unless the field begins with a designator character of "&", blank, or "?". [See 6.9.3.]

"DISPLAY = UNDERLINE" has no effect unless the field has otherwise normal emphasis (E1-E4, E16-E31).

6.9.2  Numeric Field Editing

Fields may be restricted to accept only numeric data on input, any data may be placed in the field when it is output to the screen. [See 6.5.] For the IBM 3270s, "numeric data" is defined as the numerals (0-9), the minus sign (-), and the decimal point (.). Note that spaces, commas, dollar signs, and the like cannot be accidentally entered from the keyboard for such fields; alphabetic characters can be entered into numeric protected fields if the shift key is pressed, allowing for intentional but not accidental entry of non-numeric data.

To blank out numerals in a numeric-data-only field you must use the ERASE TO END key, since spaces (entered by the space bar) cannot be used.

(Note: when the cursor is in a protected AUTOTAB field, the NUM status indicator will be on for terminals with the 4690 option.)

6.9.3  Light-Pen and Cursor Selection Control

With the IBM 3270s, you can specify that a field is enabled for light-pen and cursor selection by including the statement

in a label group. The user indicates selection of an enabled field by use of the light pen, or by pressing the CURSOR SELECT key while the cursor is anywhere in a detectable field.

You can also specify that all fields in the area are detectable by including the DETECT attribute on the DEFINE AREA command. [See 3.1.] If you specify NODETECT as an area attribute, an executing format cannot override it with a DISPLAY statement. The default for an area is PTDETECT, which allows an executing format to enable a field for light-pen and cursor selection as described above.

Though this characteristic can be specified for any field, for cursor selection purposes it is generally used only for protected fields. If this characteristic is specified for a field with an emphasis level of E24 through E63 on the 3278, then the field is displayed with bright emphasis in addition to another appropriate emphasis characteristic. For example,

specifies a bright, blinking, detectable, protected field on a 3278 (the field is blinking, detectable, protected on the 3279).

To be functional for cursor selection purposes, the first character of a detectable field -- called the designator character -- must be a "?", "&", or a blank. Which of these is used depends on the effect you want use of the CURSOR SELECT key to have. On any one screen there may be a combination of different types of detectable fields.

Note that if DETECT is specified on an unprotected field, then the user could change the first character of that field to be a valid designator character. If the user subsequently presses the CURSOR SELECT key while in this field, then the actions described below will occur. Therefore, it is recommended that DETECT be specified only for protected fields. (On all terminals other than the 3270s, DETECT makes the field unprotected, regardless of protection attributes assigned to the field, so that it may be altered by the user to signal "detection".)

The functions of the different designator characters are described below.

The "?" Designator Character

The "?" designator character and the ">" character function in combination with each other. The function is to allow the user to mark or indicate the selection of a particular field on the screen. If the CURSOR SELECT key is pressed when the cursor rests in a detectable field beginning with a "?" or ">" character, then the one character changes to the other; if the CURSOR SELECT key is pressed again, the character changes back. When the ENTER key is pressed, any selected field (fields beginning with a ">") is marked as a changed field, and any changed data on the screen is available to the program.

Note that it is possible to mark a field or fields on the screen before the screen is presented to the user; if a DETECT field begins with the ">" character, then that field is selected and marked as changed unless the user changes the character to a "?".

The "&" Designator Character

The "&" character is similar to the above, but when the CURSOR SELECT key is pressed while in a detectable field beginning with an "&", the mark function described above is followed immediately by an automatic ENTER. Thus, only one "&"-detect field can be marked per screen. The "&"-detect field is marked as changed, and any changed data on the screen is available to the program. The cursor location at the time the CURSOR SELECT key was pressed is available via the $GETAREA function.

The Blank Designator Character

The blank is similar to the "&" above as a designator character, except that only the cursor location at the time the CURSOR SELECT key was pressed (available via the $GETAREA function) and an indication of which fields have been changed are available to the program; changed data itself is not available. The use of the blank as a designator character makes the CURSOR SELECT key function similarly to the ATTENTION key.

6.9.4  Pad Characters: The SET PADCHAR Uproc and PADCHAR Statement

The SET PADCHAR Uproc and the PADCHAR statement specify a character to be used to fill out a field to its maximum length, as determined by LENGTH and/or MAXROWS statements. [See 5.3.]

Only one character is allowed; if multiple characters are specified, only the first will be used. A string variable may be used in place of 'character' if desired.

The SET PADCHAR Uproc does not affect the current label group; it affects subsequent ones. It is often placed in the frame declaration in the Format Declaration section of the definition. The pad character set remains in effect till another SET PADCHAR Uproc is encountered. Each time the format is executed, the pad character is reset to null, meaning that it should be set in a frame that will be executed when it is needed.

The PADCHAR statement sets a pad character that applies only to the label group in which it appears. If a pad character has been set by a SET PADCHAR Uproc, it is overridden by the PADCHAR statement for the duration of the label group's execution, but still applies to subsequent label groups.

To turn off padding explicitly, set the pad character to null like this:

The most common pad character is a blank, although it can cause problems for IBM 3270-type terminals. For them, the character "hex 00" works better. [On the IBM 3270s, you cannot insert characters in a field with the INSERT key if you are displacing blanks or other characters -- you must be displacing nulls (hex 00 for the IBMs). So if you want the user to be able to use the INSERT key, you must set the PADCHAR to hex 00. To specify a null PADCHAR, you could use the following Uproc: SET PADCHAR = $RETYPE($HEX(00),STR).]

If you do not know which type of terminal the users of your application will be using, you can set the pad character to the $TERMPAD character. The $TERMPAD system variable is a one-character value that is set by SPIRES to a "hex 00" character for the IBM 3270-type terminals but a blank for all others. Hence, you do not have to test the terminal type ($TERMTYPE) before setting the appropriate pad character, assuming you want the pad character to be "blank". Instead, you can simply issue one of the following as needed:

6.10  The Tektronix Terminal

6.10.1  The DIRECT/BUFFER Switch

When using the Tektronix terminal, the DIRECT/BUFFER selector switch located above the keyboard must be placed in the BUFFER position after (or while) the first screen of a full-face session is written to the CRT. After your full-face session is over, move the DIRECT/BUFFER switch to DIRECT. You are now back in line-by-line mode and can continue a normal session.

6.10.2  Emphasis Levels

As described above, [See 6.2.] emphasis levels are specified with the EMPHASIS area attribute, the DISPLAY statement, and the display Uprocs. On the Tektronix, the emphasis levels are as follows:

         E0                           default emphasis for area
       E1 - E4                        dim
       E5 - E9                        dim, blink
      E10 - E15                       dim, reverse video
      E16 - E31                       normal
      E32 - E47                       blink
      E48 - E62                       reverse video
         E63                          no print

Note: Because of hardware restrictions, unprotected fields cannot be displayed dim. Therefore, for unprotected fields only, emphasis levels 1-15 (dim) are displayed as if they were level 16 (normal).

6.10.3  Alternate Character Sets

The Tektronix terminal is equipped with the ruling font character set. It is specified by including an alternate character set specification for the area, the frame, or the label group. [See 6.3.] For the Tektronix terminal, specifying "DISPLAY = A1" will select the ruling font character set. You should place ruling font characters in protected fields, because the terminal hardware assumes that they are protected.

The characters that are specified in a format to indicate which of the ruling font characters are to be displayed are indicated for the Tektronix as follows:

For example, the top line of a small box -- left corner, horizontal line, right corner -- would be written with the following label group in a format:

6.10.4  Numeric Field Editing

Fields may be restricted to accept only numeric data on input, although any data may be placed in the field when it is output to the screen. [See 6.5.] The Tektronix terminal considers "numeric" to include 0-9, and all special characters (except @ ^ ~ [] {} | \ _ ).

6.11  The Zentec Terminal

SPIRES supports the specially programmed Zentec terminals used by RLIN. These terminals are only available to RLIN users.

A special DISPLAY value (DISPLAY = EXP) is available with the Zentec terminal to indicate that a field is expandable.

The following function keys are supported:

    Value Returned       Key Pressed

      2                  SEND MESSAGE (F8)
      3                  +B           (F1)
      4                  -B           (F2)
      5                  +            (F3)
      6                  -            (F3 shifted)
      7                  INSERT LINE
      8                  BREAK        (F16)

7  Using File Devices

This chapter describes the application of Device Services concepts and commands to file devices. Currently, any non-SPIRES ORVYL file (hereafter simply called an ORVYL file) or an OS (WYLBUR) data set can be used. File devices can be useful in several situations. If, for example, you wanted to collect data from several physical files for processing into a SPIRES file, FILE areas can be assigned to these files. Or a single physical file can be assigned to several overlapping FILE areas to allow your application to process the data in different ways, while only reading the file a single time. Although FILE areas are not conversational, by closing and reassigning the area, you can read from a file, process the data, and write it back to the end of the same file.

FILE areas can be used to send data directly to JES along with predefined JCL. This allows you to do a number of things, such as sending data directly to the printer and thereby avoiding active file size limits, creating OS files, moving SPIRES data directly to tape, and moving SPIRES data into other programs.

FILE areas can also be used as memory space for your application (similar to the MEM area), in which case they are not assigned to a physical file. [See 7.1.]

When data is moved between a FILE area and the physical disk file, it goes through an intermediate buffer, but this buffer is of no concern to you; it is completely handled by SPIRES to make actual I/O more efficient. The step of moving data between the buffer and the physical file is invisible. As far as you can tell, the data is moved directly from the area to the physical file, or vice versa.

The following diagram shows how data is moved from SPIRES to an ORVYL file. As with other areas, the "IN areaname" prefix is used to move data between SPIRES and the FILE areas. The "ASSIGN area" and "CLOSE area" commands are used to tell ORVYL what files the areas are associated with, and if the area is to be sent to JES. The WRITE and READ commands transfer data from the area to the physical file.

+------+                    +------+                    +------+
|      | IN area <output>   |      | ASSIGN area        |      |
|SPIRES|------------------->| FILE |- - - - - - - - - ->|      |
| DATA |                    | AREA | CLOSE area         | ORVYL|
|      |<-------------------|      |                    |      |
|      | IN area <input>    |      |                    |      |
+------+                    +------+                    +------+
                                |                           |
                                |
                                |                           |
                                |                           V
                                |                       +------+
                                |WRITE area             |      |
                                |---------------------->|      |
                                |                       | FILE |
                                |<----------------------|      |
                                 READ area              +------+

This chapter describes how FILE areas are defined and assigned, how to submit jobs using FILE areas, and how the READ, WRITE, and BLANK commands function with FILE areas.

7.1  The FILE Area

There are currently three uncontained areas capable of supporting FILE processing: FILE, FIL2, and HTML. Throughout this document, to save repetition, references to the FILE area apply to the FIL2 and HTML areas in the same way, although HTML is limited to output only. Each of these uncontained areas is separate from the others, and any areas defined on one do not affect areas defined on the others.

As described in Section 2.2, multiple areas can be defined on the FILE area to support I/O to several physical files. A FILE area is assigned to a physical file with the ASSIGN AREA command. [See 7.2.] This enables data to be moved between the file and the area, but in one direction only. The CLOSE AREA command [See 7.3.] detaches the file, which may then be reassigned to the same area (to move data in the other direction) or other areas. All assigned areas must be closed before you can define or redefine an area on FILE, so if you are going to have several areas defined on FILE and assigned to several physical files, you must define them all first and then assign them to files.

If you define an area on FILE without assigning it to a physical file, you may use the area as a "scratch pad," placing data in it, copying the data to other areas, getting data from it with the $GETAREA function, etc. For example, the command

will give you an area 150 lines long and 100 columns wide (much larger than the MEM area) in which to place data in temporary storage.

Since FILE is a flexible area capable of indefinite length and width, the size of the file area depends on the size of the areas defined on it. If all areas defined on FILE do not have dimensions specified, then the FILE area and all such non-dimensioned areas will, by default, become line-by-line areas with the dimensions (0,80). Otherwise, the FILE area will be the size needed to hold all areas defined on it. When areas with fixed dimensions are defined on FILE, it becomes an area with fixed dimensions. You cannot have both line-by-line and fixed-dimension areas defined on FILE at the same time. If you define an area with no dimensions, but place it at a specific location on FILE (e.g., DEFINE AREA ONE ON FILE (5,20)), it becomes a null area.

Areas can be overlaid on the FILE area and on one another, and each time an area is defined or redefined, the size of the FILE area might be altered. The width of the FILE area is only affected by areas laid directly on FILE, not those laid on other areas contained by FILE. Size alterations depend on the order in which the areas are defined. For example,

will create an area named ONE that has the default definition of the FILE area, i.e., a line-by-line area 80 characters wide. If we now define another area as follows:

both the FILE and ONE areas will expand to be 100 rows, but will still only be 80 columns wide. But if we define an area directly on FILE,

the width of the FILE area will expand to hold the new area. Also, area TWO will now be able to expand to its defined width. The area definitions are now:

See Appendix A for more details and examples of size adjustments for contained areas.

If areas on FILE do not overlap, then different data can be placed in different areas to be written to different physical files. [See 7.4.] If areas overlap, the data placed in these areas will also overlap, with possible truncation or loss of data if data is placed in them at different times. Overlapping areas can be used to write the same data to more than one physical file or to read from a single physical file into multiple areas.

7.2  The ASSIGN AREA Command

The ASSIGN AREA command attaches one area to one physical file. The syntax is:

  ASSIGN AREA areaname TO ...
   {[OS FILE] filename [file-opts]|ACTIVE FILE [act-opts]|TEMPORARY}

The "areaname" may be FILE, FIL2, or HTML, or any areas defined on those areas. Throughout this section, references to the FILE area are used, but FIL2 and HTML areas have similar capabilities. So, for example, it is possible to ASSIGN the FILE area directly, rather than assigning an area defined on FILE. This provides a single command for simple use of the FILE device:

The possible forms for the filename are:

If you use the OS FILE option to request an OS file, the possible forms for the filename are any legal WYLBUR filename format, such as these popular forms:

Whenever a gg.uuu is specified, there must be a mapping of that account in the .empath tables in Unix implementations.

Only one file may be assigned to each area, and a particular file can be assigned to only one area. If you attempt to ASSIGN a file or area that is already assigned or try to assign an area that is not FILE or defined on FILE, you will receive the message "INVALID ASSIGN". To change assignments or options, the area/file must be closed [See 7.3.] and a new ASSIGN command issued.

If you specify ACTIVE FILE on the ASSIGN, SPIRES will use your active file as the destination for the output, or the source for the input.

If you specify TEMPORARY (or TEMP) rather than a filename, a temporary ORVYL file will be attached for output processing (to use this file as an input file, see below). The format of this file will be EDIT. Data can be sent to this file with the WRITE command or any of the output commands preceded by the IN areaname prefix. The data placed in this file is only held for the duration of the assignment. It can be retrieved by reassigning the file to be valid for the IDATA function (with the ASSIGN INPUT option of the CLOSE AREA command). [See 7.3.] The benefit of creating temporary files in this fashion is to provide you with one or more very large "scratch pads" to store data that does not need to be stored permanently.

The "file-opts" options that may appear on the ASSIGN AREA command with the TO [OS FILE] filename option are:

 - OUTPUT or INPUT.  OUTPUT indicates that the file will be written to, INPUT that it will  be
 read  from.   If  neither  is given, OUTPUT is assumed.  Usually, if you specify INPUT, you
 don't need any other options.
 - NEW or OLD.  This indicates whether the file already exists and is to be replaced or  if  a
 new file is to be created.  If neither is given, NEW is assumed.
 - EDIT or FIXED or LRECL=n.  This need not be specified for INPUT.  The default is EDIT,  for
 which  the  maximum  line  size  is  235.   $DELTA at the time of the ASSIGN is used as the
 starting line number, and as the increment for all lines.  Temporary files can only be EDIT
 format.  If LRECL=n is given, the maximum line size is 2048 for an ORVYL file, and 8164 for
 an OS data set.  For  an  OS  data  set,  you  may  also  specify  a  blocking-factor,  eg:
 LRECL=80(40)  signals  LRECL=80 and BLKSIZE=3200 for a FIXed data set.  For a VARiable data
 set, LRECL=80(40) signals LRECL=84 and BLKSIZE=3364.  In other words, SPIRES  will  compute
 the  proper  LRECL and BLKSIZE for FB or VB data sets so that output records can be as long
 as the LRECL you specified.  If you don't specify a blocking-factor,  a  default  is  used.
 FIXED is assumed with LRECL.  If FIXED is given without LRECL, the area's column dimensions
 are  used.   For  each  line moved from an area to a file, truncation or blank padding will
 occur to fill the column width of the area if FIXED is specified.
 - REPLACE [REFORMAT]/SCRATCH/ERASE or APPEND/CONTINUE.  For an OUTPUT  file,  this  specifies
 whether the data sent to the file is to replace data already in the file, or be appended to
 the file.  For an existing OUTPUT file, either REPLACE or APPEND must be given; if the file
 does  not  exist  and  one of these options is specified, no error is reported.  (Note that
 when you use the APPEND or CONTINUE option, you  must  have  WRITE  access  to  the  file.)
 Normally,  the  APPEND/CONTINUE option supresses the output of the <HTML> heading for
 assignments related to the HTML area, but it signals the need to  output  </HTML>  at
 final  close.  For an OS data set that already exists, you must include the REFORMAT option
 after REPLACE to change the attributes (e.g., LRECL) of the OS data set.
 - HEADING.  The HEADING option indicates the <HTML> heading should be output  when  the
 first  non-TEXT  mode  write  occurs  from  HTML related areas, even if the APPEND/CONTINUE
 option has been specified in the assignment.
 - SHARE.  For an INPUT or OUTPUT file, the file is attached "shared" so that others
 may attach it "shared" simultaneously.  If SHARE is not specified,  the  file  is
 attached  so that no other user may have the file attached at the same time.  For an OUTPUT
 file,  if  APPEND  is  also  specified,  then  multiple  users  may  write  to   the   file
 simultaneously.   For  an OUTPUT file with both APPEND and EDIT specified, you must use the
 "GET filename RENUMBER" command to copy the resulting file into the active  file.
 - JOB.  The JOB option indicates that a job path is to be opened, and  the  contents  of  the
 file  copied to the beginning of the job stream.  It cannot be used in conjunction with the
 INPUT option, nor with the OS FILE option.  This option creates a  different  situation  in
 that  the ORVYL file is read, but not into the area -- it is placed in the job stream.  The
 SPIRES data is written from the area, but not to the file -- it, too, is placed in the  job
 stream.   The only options that can be combined with the JOB option are the EDIT, FIXED, or
 LRECL option and the SHARE option.  [See 7.6.]
 - VARIABLE.  This option is specified for output data sets to request  variable  edit  format
 (the  same  format used by exception files).  It can be used for input data sets as well as
 long as the file truly has a variable format;  if  it  has  a  fixed  format,  variable  is
 invalid.
 - WRAP (for output).  All data that is output under the WRAP option will have lines that  end
 either  with  a semicolon (;) or a backslash (\).  Under WRAP, the complete output of a row
 from the area always ends in a semicolon, but if the row's content is too long to fit  into
 the  file because of the file's format (e.g., EDIT or LRECL=n), then the row is broken into
 multiple lines, each ending with a backslash except for the final line, which will end with
 a semicolon.  This would let you output very large rows (more than  235  characters)  to  a
 file  of  EDIT format (which could then be read by WYLBUR) without any data being lost when
 the file was created.  (See also WRAP TRANSPARENT below.)
 - WRAP (for input).  On input, WRAP will do the reverse of what it does for output.  An input
 line ending with a backslash (\) indicates that the next line should be concatenated to the
 current line, with the backslash discarded.  Concatenation stops when a line is  read  that
 doesn't end with a backslash. If that line ends with a semicolon, the semicolon is removed.
 The single line that results from the concatenations then becomes a single row of the input
 area. If the line is longer than the row, the excess data is discarded.  Note that trailing
 blanks  are  always  removed  from  each  input line, no matter what the value of LRECL is.
 - WRAP TRANSPARENT (for output).  This variation on WRAP is the same as WRAP except that  the
 last  line  of  a  row  will  not end with a semicolon.  This allows you to choose your own
 termination character to use in a format.  Do not use a backslash, however.
 - TRANSPARENT.  On output, if TRANSPARENT is requested without WRAP, rows are output  to  one
 or  more  lines,  with a leading and trailing vertical bar (|) on each line. Rows with more
 than 62 characters (don't count blanks at the end of a row) will create more than one line.
 The last line output from a long row will end with a carriage return (hex 0D)  just  before
 the  trailing  vertical bar.  Including the two vertical bars, lines are not longer than 64
 characters.  If LRECL is less than 64,  then  that  length  will  be  used  instead  of  64
 characters.  (See also WRAP TRANSPARENT above.)
 - TEMPORARY (OS FILE option only).  When specified as a file-option when the OS  FILE  option
 is  in  effect, SPIRES opens a temporary WYLBUR data set on a scratch volume; hence it will
 be scratched overnight when the temporary volume is erased.
 - TRACKS=n (OS FILE option only).  For new OS data sets, use this option to specify how  much
 space  should  be  allocated.   SPIRES  uses  "n"  as the primary allocation, and
 "n/8" (rounded up to an integer) as the secondary allocation.  If not  specified,
 the  default "n" is 10, meaning a primary aloocation of 10 tracks and a secondary
 allocation of 1.  You may also specify the desired  allocation  with  CYLINDERS,  KBYTE  or
 MBYTE instead of TRACKS.

The "active-opts" options that may appear on the ASSIGN AREA command with the TO ACTIVE FILE option is used are:

 - OUTPUT or INPUT.  OUTPUT indicates that the file will be written to, INPUT that it will  be
 read from.  If neither is given, OUTPUT is assumed.  When OUTPUT is in effect, one of these
 additional sub-options may be specified:
 - NEW = open a new active file without clearing any others
 - KEEP = use the current active file if it is empty; otherwise, keep the  current  one  but
 open a new one for the area to use
 - CLEAR = use the current active file if it is empty; otherwise, clear it and  open  a  new
 one for the area to use
 - CONTINUE = append to the current active file, and supress the output of the  <HTML>
 heading for assignments related to the HTML area.
 - HEADING.  This option work as described above.
 - WRAP, TRANSPARENT, WRAP TRANSPARENT.  These options work as described above.

If you assign an area to the active file for output and do not specify one of the sub-options listed above, SPIRES will ask you "OK to clear?" if the active file has any contents. The usual responses are available there: YES, OK, NO, or KEEP.

Internally SPIRES will keep track of which WYLBUR active file has been established for the area, so even if you pick another to work on, SPIRES will put the output into the correct one, just as long as you don't clear it yourself with a CLEAR ACTIVE or other text-editor command that would clear the active file.

Because both SPIRES and WYLBUR support multiple active files, you can use this method for several active files at once, using some for input and others for output, assigning each active file to a separate file area.

More Details on OS Data Sets

You handle output processing under the OS FILE option just like with ORVYL files, by commands such as "WRITE areaname" when you've SET NOWRITE. Typically, output is done with "IN areaname" prefixed to standard output commands, like DISPLAY, TYPE, and SHOW EVAL. You must "CLOSE areaname" to complete the output and allow the file to be saved.

Input processing for INPut data sets is done as follows:

This commands fills as much of the specified area as possible. If nothing is read, End-of-File is signaled, and the command in the optional ATTN clause is executed.

Lines/records that exceed the width of the area are truncated without notice. Lines/records shorter than the width of the area are blank padded.

You can also input with "IN areaname" prefixed to certain data entry commands, like formatted ADD, UPDATE, and MERGE. These commands read the entire data set, very much like the way the active file is read. Again, you must "CLOSE areaname" to detach the file.

Here is a complete example, using a protocol file that has a bi-directional input/output format ($PROTOCOLS).

7.3  The CLOSE AREA Command

When you have finished writing to or reading from a file and its associated area, issue the command:

If the area was assigned with the JOB option, the CLOSE AREA command detaches the file and submits the job to JES. The PURGE option only applies when the JOB option is in effect, and cancels the job after detaching the file.

The ASSIGN option is allowed for any area defined on FILE except for an ACTIVE FILE or JOB assignment or an output file with the APPEND option. [See 7.2.]

For a temporary file, the ASSIGN option allows you to reassign the file to either OUTPUT (the ODATA function) or INPUT (the IDATA function), thus allowing you to, for example, read data from the file that you had previously placed there using a WRITE command or some other output command. If the ASSIGN option is not used when closing a temporary file, the file is erased (discarded).

When an area is reassigned to INPUT, you can read from the file using the READ command. If, in addition, the "IN areaname SET READ" command has been issued, you can read from the file using input commands for formatted input (ADD, UPDATE, MERGE) preceded by the IN areaname prefix.

For a regular (non-temporary) file, the ASSIGN INPUT option rewinds the file and places it in input mode if it is not already. ASSIGN OUTPUT is only allowed if the file is already in output mode. This option rewinds the file and places it in output mode. This permits the rewrite of a file that is not a standard input file.

When the CLOSE AREA command is issued for an output file (ODATA), the file's buffer is flushed, the file is detached and the area is blanked. If SET WRITE is in effect for the area, then all data has been automatically moved from the area to the file's buffer. However, if SET NOWRITE is in effect, data is not automatically moved from the area to the buffer, and because the CLOSE AREA command does not move data from the area to the buffer before flushing the buffer, data remaining in the area will be lost. In this case, you would want to issue a WRITE command before issuing the CLOSE AREA command.

If CLOSE AREA refers to an HTML area, then </BODY></HTML> is normally output to the associated file if the area was assigned with the CONTINUE option, or with the HEADER option and a non-TEXT write occurred. The CONTINUE option on CLOSE suppresses this termination output.

Once this command has been issued, the file may be assigned with different options via the ASSIGN AREA command, or it may be manipulated by ORVYL commands (such as GET) (or by WYLBUR commands, if it is an OS data set or the Active File), or it may be accessed by other users (it may be accessed by other users if SHARE has been specified, in any case).

If you EXIT SPIRES, then all areas are closed and all files are detached.

7.4  Writing to a File Device

Writing to file devices is like writing to any device. When SET NOWRITE is in effect, data is moved from the area to the file only when a WRITE command is issued.

If SET WRITE is in effect, the area is written when it becomes filled or when a data output command has completed. However, although other physical devices are blanked when such implicit WRITEs occur, [See 4.8.1.] in the case of FILE areas, only the area is blanked; the physical file is not affected.

One situation in which you would definitely want to SET NOWRITE is when using a FILE area as a "scratch pad" and never intend to write the area to a disk file. [See 7.1.] In this case, you must set NOWRITE because if a command completes and no physical file exists for it, the data in the area will in effect be thrown away.

The assignment of areas to physical files allows FILE areas to be written separately, something not available with most other areas (except MEM and TER, see 4.7.1). Because each file is a physically discrete unit, writing one of them does not affect any other one. So if you had SET NOWRITE in effect and had placed data in, say, 3 FILE areas, you could issue a WRITE command for one of them, and the other two areas and files would be unaffected.

As you place data in areas and write the areas to the file, the data is placed at the end of the file. If you want several areas to be placed in relationship to one another, you must SET NOWRITE first, fill the areas with the data, and then write the areas to the file with an explicit WRITE command. (See example below.)

Whenever a FILE area is written, the content of that area is moved to the first physical file associated with this area or any of its containing areas. That means that if the area is a member of a hierarchy and one of the lower members has a file assigned to it, then this area's data is written to or read from that physical file. Consider the following:

  DEFINE AREA ONE (30,40) ON FILE
  DEFINE AREA TWO (20,10) ON ONE(6,11)
  DEFINE AREA THREE (20,10) ON ONE(6,21)
  DEFINE AREA FOUR (10,5) ON THREE(6,4)
  ASSIGN AREA ONE TO DATASET1
  ASSIGN AREA TWO TO DATASET2
  ASSIGN AREA THREE TO DATASET3

A picture of the areas might look like this:

  0         10        20        30        40
  +---------------------------------------+
  |                 ONE                   |
  |                                       |
  |          +--------------------+       |
  |          |         |          |       |
10|          |   TWO   |   THREE  |       |
  |          |         |          |       |
  |          |         |  +----+  |       |
  |          |         |  |    |  |       |
  |          |         |  |FOUR|  |       |
20|          |         |  |    |  |       |
  |          |         |  +----+  |       |
  |          |         |          |       |
  |          +--------------------+       |
  |                                       |
  |                                       |
30+---------------------------------------+

ONE, TWO, and THREE are all assigned to physical files. Assuming that WRITE is in effect, if data is placed in any of them, their specific area is "written" to the associated file, for the length of the data placed into the area. If data is placed in area FOUR, then its data is written to the DATASET3 file since that file is the first one found in the hierarchy leading back toward the FILE area. Of course, it is the file assigned to THREE. If no file had been assigned to THREE, then the file assigned to ONE would have been used. Note that FOUR's data is moved to THREE's file, but according to FOUR's area boundaries, not according to THREE's boundaries, that is, column 1 of area FOUR will be in column 1 of the file.

However, if SET NOWRITE is in effect, the area is not written and blanked at the end of a command. Therefore, by doing IN FOUR SET NOWRITE, the user could put data into FOUR without causing it to be written to THREE's file. A separate WRITE THREE would then move all of THREE's data to THREE's file, including the portion that is area FOUR in the position shown. If area ONE were written, all of the data in all four areas would be written in the location shown in the drawing.

The CLOSE AREA command caused the data remaining in the file's buffer to be written to the disk and the file detached.

7.5  Reading from a File Device

Before you can read from an input file, it must be assigned to the area with the ASSIGN AREA command, with the INPUT option. [See 7.2.]

Reading a FILE area is different from reading any other area. In the first place, it is the only area for which implicit READs occur. In other words, it is the only area for which you would ever want to set NOREAD. And NOREAD must be set for each area (e.g., IN areaname SET NOREAD); global NOREAD has no effect on FILE areas.

It also differs because it can be either line-by-line or fixed-dimension, depending on the areas defined on it. [See 7.1.] How much data is read from the input file depends on whether the area is defined as line-by-line or fixed-dimension.

If SET READ (the default for a FILE area assigned the IDATA function) is in effect, data is moved sequentially from the file to the area under either of the following conditions:

If SET NOREAD is in effect, data must be moved by an explicit READ command, as follows:

If CURSOR is specified, "lines" limits the number of lines to be read; if it isn't specified, then the area is filled with as many lines as possible (until an end-of-file condition, or the maximum number of rows in the area has been filled). The "command" specified by ATTN is executed if no lines are read from the input file into the area.

Note that $GETAREA(areaname,CROW) [See 4.3.] returns the number of lines read into the area (which may be fewer than the CURSOR option requested if the end of the file was reached).

The following example reads data from the area named ONE. Because NOREAD is in effect, an explicit READ command must be issued, and because the area has fixed dimensions, 10 rows of data will be read into the area each time a READ command is issued. The data in the area is then used to add a record according to the instructions in the format frame named INPUT.

7.6  Submitting a Job Using FILE Areas

The JOB option on the ASSIGN AREA command lets you create a job stream that is sent directly to JES. The job stream consists of JCL that is in the ORVYL file assigned to the area and the data you place in the area. (This option is not available for OS data sets.) When the area is closed, the job is submitted.

For example,

In this example, we defined an area named DATAJOB and assigned it to an ORVYL file named JCL, adding the JOB option to the ASSIGN AREA command. This file contains some JCL to which will be added the data from the subfile that we direct to the area. When we issue the CLOSE AREA command, the job is sent directly to JES.

If there is an error in the JCL, the job is rejected and SPIRES issues an error message. If the job is successfully sent, the $JOBNUM variable holds the 4-digit job number.

You can write the JCL so that it can be run by several different accounts. If the first line of the JCL contains one of the following strings, SPIRES will make the appropriate substitution:

If the job card is not valid for your account, JES will notify SPIRES that it cannot accept the job, and SPIRES will issue an error message.

Using the ASSIGN AREA Command to Copy the JCL

The ASSIGN AREA command assigns an area to an ORVYL file. If you add the JOB option to the command, SPIRES will copy the contents of this file to the job stream. Any other data placed in the area will appear in the job stream following the JCL.

In some cases, you might need to have your data appear in the middle your JCL; that is, you will need to copy some JCL from your file to the beginning of the job stream, move the data from your SPIRES file to the job stream, and then copy more JCL to complete the job. To do this, place the following line, beginning in column 1, in your JCL file where you expect your data to go:

When the area is assigned to the file, all the JCL up to that line is copied. When the area is closed, any JCL in the file after the "/*DATA" line is copied to the end of the job stream before it is sent to JES.

Using the CLOSE COMMAND to Submit the Job

The CLOSE AREA command detaches the ORVYL file and submits the job. If the file contains any additional JCL following a "/*DATA" statement, that JCL will be copied to the job stream at this time.

The size of the line images sent to JES will be equivalent to the width of the area up to a maximum of 254 characters. If you include the LRECL option on the ASSIGN command, and the specified LRECL does not exceed the width of the area, then the line images will be equivalent to the LRECL specification up to a maximum of 254 characters.

If you do not wish the job to be submitted add the PURGE option to the CLOSE AREA command as follows:

The area will be flushed and the file detached, but the job will not be submitted.

If you EXIT SPIRES without closing the area first, the job will be cancelled.

System Files for Common Types of Jobs

There are five system files that can be specified on the ASSIGN AREA command that contain JCL to perform commonly needed jobs. These are:

$LIST. This JCL creates the job to send your data stream directly to the printer. It looks like this:

$LISTCC. This JCL creates the job to send your data stream directly to the printer, to be printed with carriage control. It looks like this:

$HOLD. This JCL creates the job to send your data stream to the printer, but the job is held in the print queue until you release it. It looks like this:

$HOLDCC. This JCL is similar to that in $HOLD, but the job will be printed with carriage control. It looks like this:

$NULL. This file is an empty file. You would use this when you wanted to open the job stream, but write your own JCL to the area via some other source, such as from a format or the command level.

Using the FILE Area to Write an OS Data Set

One of the handiest applications of the JOB option is that you can, in effect, write SPIRES data directly to an OS file by submitting an IOPROGM job. The following example demonstrates this:

The file named OSFILE looks like this:

7.7  The HTML Area

The HTML area is used to output data to non-SPIRES ORVYL files, OS FILE datasets, or the Active File. The output is done on a field-by-field basis, row-by-row from the area. Like FILE or FIL2, you ASSIGN AREA to an output file, and CLOSE the area to finish.

If CONTINUE is not an option of the ASSIGN AREA command, or HEADING is included as an option, then the first write of the area (either explicit or implicit) following the ASSIGNment creates <HTML> with optional <HEAD>header</HEAD> information, and then <BODY> or <BODY BGCOLOR="#color">. The header may include any combination of: <TITLE>title</TITLE>, <LINK REL="STYLESHEET" HREF="imported_style">, and <STYLE>style</STYLE> information. The "title" is supplied by executing the $HTML(TITLE,"title") function, which should occur before the first write. The "imported_style" or "style" information is supplied by executing the $HTML function with LINK, STYLE, and Sn codes and defining strings. BGCOLOR is created by executing the $HTML(BGCOLOR,color) function. The simplest header is just: <HTML><BODY>.

After the header, all writes output the data fields, including background fields. Consecutive blanks in a field are normally squeezed to a single blank, so background fields usually supply only a single blank. If a field exceeds 224 characters, it could be split across lines. Such splitting occurs at the nearest blank before the 224th character.

DISPLAY attributes usually affect the way data fields are output. Certain characters in the data are translated during output into "escape sequences", unless there is a DISPLAY attribute of RAW associated with the field. We will cover DISPLAY attributes in the next section.

When you CLOSE AREA, the output is terminated by appending </BODY></HTML>, if the CONTINUE option is not used on the CLOSE. Therefore, the entire process of ASSIGN AREA, write data, and CLOSE area, will create an HTML document.

You place data into an HTML area using any standard output command with the "IN area" prefix, or with the $PUTAREA function. Data placed in an area using one of these methods creates data fields, which are distinct from background fields. In order to get the full benefit of HTML output processing, you should be setting display attributes either with DISPLAY statements in a format, or with the $SETAREA function.

Let's assume an output format doing PUTDATA to create fields in an HTML area. For example:

Assuming the FOR command defines a set of records, this would produce a document in the Active File that looked something like this:

For more information, [See 7.7.1, 7.7.7.]

7.7.1  HTML Display Attributes

All existing output formats may be used with the HTML area, even those written specifically for CRT or TER. The DISPLAY attributes for CRT and TER carry over into HTML with little or no conversion. For example, all "color" attributes are recognized by HTML, just like CRT. So is UNDERLINE. WRAP (or EXPAND) takes on a new meaning in HTML, indicating there should not be a <BR> at the end of the output row in which WRAP was specified. Attributes like NUMERIC, DETECT, PROTECT, UNPROTECT, TRIGGER, and AUTOTAB are ignored in HTML. However, these attributes are reserved for HTML to use in conjunction with certain HTML attributes. For example, TRIGGERS and AUTOTAB are used by Hn, Sn and Xn to define the B and E extensions. Most RULING font fields are ignored, treated as empty data fields. They were generally designed for CRT, not HTML. However, RULING font that defines a horizontal line creates an <HT> field in HTML.

We recommend that you specify DISPLAY attributes in this order:

You should start with the 1st group because it defines terms in following groups, which you can then override. Note that the last group contains the HTML tags, which override the prior combination. That is, HREF or CENTER or H3 (etc.) takes precedence over BOLD, BLINK and ITALIC. And you may not have more than one HTML tag in a single DISPLAY or $SETAREA.

7.7.2  UNDERLINE, WRAP, CENTER, NBSP and Hn Attributes

The UNDERLINE attribute can be used on any field. It surrounds the data value by <U> and </U>. Normally, a row containing non-blank data is output with ending <BR>. The WRAP attribute can be used on any field within a row to signals that no <BR> should be output at the end of that row. Furthermore, an all blank background row is not output at all.

The NBSP attribute retains all blanks in a field. This is done by outputting "&nbsp;" for the first blank, and " &nbsp;" for succeeding pairs of blanks, and "&nbsp;" for the last blank in a field that ends with a non-paired blank.

The CENTER and Hn attributes creates the following output:

Hn may be specified as HnB or HnE to indicate just the <Hn> at the beginning (B), or </Hn> at the end (E). If the data.value is blank, only the <Hn> or </Hn> is output. Otherwise, HnB and HnE place the associated data.value as follows:

It is your responsibility to insure you pair HnB with HnE to surround your information properly. Here is an example:

7.7.3  HTML Color Attributes

When you use a color attribute on a field, the output is surrounded by:

Your field data and other attributes go between these HTML terms. If several fields occur consecutively on the same row with no intervening background fields, and they all have the same color attribute, then all these fields will be output between a single <FONT COLOR...> and </FONT>. Example:

The resulting output would look like this:

The color codes are 6-character hexadecimal values which can be examined and changed by the $HTML function. [See 7.7.7.]

There are seven colors: BLUE, RED, PINK, GREEN, CYAN, YELLOW, WHITE. If the color is WHITE and the BGCOLOR is either not specified (DEFAULT) or WHITE, then no color designation is output. If any other color matches the BGCOLOR, then it is changed to a complement.

7.7.4  HREF, NAME, TAG and MAILTO Attributes

The HREF and NAME attributes are used to create an "anchor" in HTML, which looks like one of these:

The "data.value" is the value supplied for the field with these attributes. If either of these is followed immediately by another field with the TAG attribute, then the trailing </A> has the tag.value associated with the TAG attribute inserted before it, which makes the examples look like this:

Here is a specific example:

The resulting output would look like this:

The START statement is important because it guarantees the TAG field occurs in the same row, providing the area is wide enough to hold both TAG and its companion field. In formatted output, the FRAME-DIM must also be wide enough.

The MAILTO attribute takes a single user@hostvalue and creates the following HREF:

where 'user@hostvalue' would normally be an email address. Notice that 'user@hostvalue' appears twice in the created HREF.

7.7.5  IMG and ALT Attributes

The IMG and ALT attributes go together like HREF and TAG. The IMG attribute creates the following output:

If the IMG field is followed immediately by an ALT field, then the alt.value is inserted to produce this combination:

Here is a specific example:

The resulting output would look like this:

The START statement is important because it guarantees the ALT field occurs in the same row, providing the area is wide enough to hold both ALT and its companion field. In formatted output, the FRAME-DIM must also be wide enough.

7.7.6  RAW Attribute

The RAW attribute outputs the data.value exactly as it is given, without translation of "escape characters" or squeezing of blanks. This is particularly handy if you want to output your own HTML tags. Otherwise, all "escape characters" in data values are translated to "escape sequences".

If you need to translate a string, you can use $HTML(TRANSLATE,string). [See 7.7.7.]

7.7.7  The $HTML Function

The $HTML function is a 2-argument function that has many purposes. The first argument is always a code or color name. The second argument may be a code or color name or a string, depending upon the first code.

$HTML can be used to change the RRGGBB codes of the seven (7) colors. If the first argument is a color name, then the second must either be DEFAULT or a 6-character hex-code for the color in RRGGBB format.

DEFAULT may be followed by anything except GET, Sn or Xn, TRANSLATE, ENCODE or DECODE.

COLORS and ALL may only occur as the second argument following DEFAULT:

BGCOLOR may be followed by a color name, or DEFAULT.

TITLE may be followed by a string:

Note that $html(title,default) makes the title = "default".

LINK may be followed by an HREF string value that is output in the heading of the document in a <LINK REF="STYLESHEET" HREF="value">.

STYLE and Sn are followed by strings that define HTML tags with style information enclosed in braces. STYLE may define multiple tags and styles, but Sn should only define individual tags.

Xn is followed by a string that defines an HTML tag, possibly with other information. [See 7.7.10.]

GET may be followed by any code except ALL, COLORS, GET or TRANSLATE.

Note that $html(get,$html(get,bgcolor)) will either return the word DEFAULT, or the RRGGBB code of the Background color.

When text is output with a color specification that matches the BGCOLOR, the color of the text is changed to a complement. WHITE text is displayed in the brower's default foreground color if BGCOLOR is either WHITE or DEFAULT.

The $HTML function is used to set the <TITLE>...</TITLE> in the heading of the created document, and the BGCOLOR of the <BODY>...</BODY> of the created document. The LINK, STYLE, and Sn style controls are also placed in the heading.

The $HTML function may be used anyplace a function is allowed. We expect it will be incorporated into UPROC statements of formats using EVAL or LET commands. $HTML returns a string, which varies depending upon the first code. For GET, it is the value of the requested item. For all other codes, it should be the second parameter. A null string return should only happen with a null TITLE. Any other null string return indicates an error (usually an invalid parameter).

TRANSLATE is followed by a string, and is used to translate HTML-escape characters into their escape sequences. For example:

You could use this in a format to translate data which you surround by your own HTML tags, and output with DISPLAY = RAW; or DISPLAY = color,RAW;

The ENCODE and DECODE options act upon the second parameter, a string to be converted.

ENCODE converts all punctuation into a %hh string (three-character percent-prefixed hex-value). The hh value is the ASCII-hexcode for the converted character. For example:

Note that blank is converted to %20. All upper/lower case letters and digits are unchanged.

DECODE does the reverse, converting any %hh, where hh is a pair of hexadecimal digits (0-9,a-f,A-F), from this ASCII-hexcode to the equivalent EBCDIC character. For example:

Note that the "+" character is converted to blank by DECODE.

The ENCODE and DECODE codes may be abbreviated to their first three characters. Be aware that "DE" is interpreted as DEFAULT, not DECODE. These codes are useful in processing web pages (both input and output). For example, ENCODE would be used on a value placed inside an HTML-tag, such as:

 <a href="http://server/script?term=%22A%3CB%22">&quot;A&lt;B&quot;</a>.

Notice the value between HTML-tags is created using $HTML(translate, '"A<B"'). This is common practice with HTML pages.

The MODE parameter may be used as follows:

WRAP and NOBR are equivalent, and BR is the compliment. NBSP and BSP are compliments. TEXT and NTEXT are compliments. Defaults are BR, BSP and NTEXT .

$HTML(MODE,WRAP) or $HTML(MODE,NOBR) set a global setting that acts as though DISPLAY=WRAP was in effect for every field sent to an HTML area. $HTML(MODE,BR) is the DEFAULT, in which case DISPLAY=WRAP controls the suppression of <BR>.

$HTML(MODE,NBSP) sets a global setting that acts as though DISPLAY=NBSP was in effect for every field sent to an HTML area. $HTML(MODE,BSP) is the DEFAULT, in which case DISPLAY=NBSP controls the use of &nbsp; in the output fields.

$HTML(MODE,TEXT) sets a global setting that tells output processing to output as TEXT instead of HTML. $HTML(MODE,NTEXT) is the DEFAULT, in which case HTML is output. [See 7.7.8.]

Both $HTML(DEFAULT,ALL) and $HTML(DEFAULT,MODE) reset all MODE settings to their defaults (BR, BSP and NTEXT). You can sense the MODE settings with: $HTML(GET,MODE) which returns a digit character from "0" through "7". The meanings are:

3,5,6,7 are sums of 1,2,4. Note that when supplying parameters to the $HTML function, the word MODE should be given as MODE or MOD. If you give "N" for "NOBR" or "NBSP or "NTEXT", it is interpreted for all. That is: $HTML(MODE,N) sets both NOBR and NBSP, and resets TEXT. Likewise for "B" which resets both to their defaults (BR and BSP).

7.7.8  $HTML, TEXT Mode Option

$HTML(MODE,TEXT) sets a global setting that tells output processing to output as TEXT or modified HTML. $HTML(MODE,NTEXT) is the DEFAULT, in which case HTML is always output.

In TEXT mode, the BSP/NBSP global settings affect the type of output. In all cases, all blanks are retained as blanks, and each line is output as a separate line with no <BR> ending regardless of the global BR/NOBR/WRAP setting. Also, HEADER, Xn, Sn and Hn processing is ignored in TEXT mode.

For $HTML(MODE,NBSP), the HTML-tags defined as DISPLAY attributes are processed normally as standard HTML output, except as listed above. DISPLAY=RAW fields are always output unchanged. Non-RAW data fields have a TRANSLATE operation done on them. This can be very handy when outputting inside <PRE> to </PRE> tags.

For $HTML(MODE,BSP), the default, all ruling fonts are ignored. HTML-tags are also ignored, except for COLOR, BOLD, ITALIC, UNDERLINE and REVERSE attributes, which are output surrounded by escape sequences like <.RED>red_text<.RED-> or <.BOLD>bold_text<.BOLD-> . If the output file is sent to "trc", the text report converter, then these escape sequences are translated for use by PostScript or GhostScript, or removed from non-PostScript output. TRANSLATE operations are NOT done on any field.

7.7.9  HTML Style Attributes

The $HTML function can be used to set up Style Sheet information, or TAGS, like "TABLE" or "DIV" or "PRE", that are created by special DISPLAY attributes. There are three classes of Sytle Sheet information: LINK, STYLE and Sn.

LINK, STYLE, and Sn information is output when the header is output. This usually occurs with the first output from an area ASSIGNed to an output file, providing the CONTINUE option was not used on the assignment.

The following example shows $HTML functions used to define the Style Sheet information, and what is output when the header is output.

Notice that S0, which defines a DIV tag, is placed in the header as #s0 followed by the style information. The same would be true for all other Sn definitions.

Tags brought in by LINK, or defined by STYLE, are referenced by the DISPLAY attributes created by the HTML output process, such as <BODY> or <IMG...> or your own constructs output by DISPLAY=RAW.

When you use DISPLAY=Sn, you referenced one of the Sn definitions, such as the S0 definition in the example that begins with a DIV tag. You may use SnB to indicate a start-only reference, or SnE to indicate and end-only reference. Here is an example of DISPLAY reference:

Every Sn or SnB reference creates the HTML tag defined by the $HTML function definition, followed by the ID="sn" reference to the style information output in the heading that corresponsed to Sn. Your value is then output, although a single blank value is suppressed. Sn then outputs the corresponding termination HTML tag.

SnE outputs your associated value, other than a single blank, and then outputs the corresponding termination HTML tag.

Finally, notice in the $HTML function definitions of Style information, the use of semi-colon or quotes (") requires placing the entire UPROC in quotes, doubling any interior quotes. We recommend using apostrophy (') around the string in the $HTML function.

7.7.10  HTML Xn Attributes

The $HTML function can be used to set up TAG information like "TABLE" or "TR" or "TD", that are created by Xn DISPLAY attribute references. Every Xn or XnB reference creates the HTML tag defined by the $HTML function definition enclosed in angle bracket: <definition>. Your value is then output, although a single blank value is suppressed. Xn then outputs the corresponding termination HTML tag: </TAG>.

XnE outputs your associated value, other than a single blank, and then outputs the corresponding termination HTML tag: </TAG>.

Here is an example:

The dash-comments on the DISPLAY lines shows what is output when this field's value is flushed from the area. Notice the use of Xn, XnB and XnE to control HTML tag generation. The values in the data area do NOT include the HTML tag strings. They are held in a separate place by the $HTML function. The combination of HTML tag strings and values is created as the fields are output to the destination file.

To describe this another way, the area contains the GETELEM/VALUE shown, along with DISPLAY attribute information. When the data in the area is output, the Xn strings defined by the $HTML function are output along with the values, as illustrated by the dash-comments.

Finally, notice in the $HTML function definitions of Xn TAG information, the use of quotes (") requires placing the entire UPROC in quotes, doubling any interior quotes. We recommend using apostrophy (') around the string in the $HTML function.

7.7.11  HTML Recommendations

The default size of the HTML area is (0,80), which means it is designed as a line-by-line area with a minimum width of 80. You may overlay areas on top of HTML to change its dimensions:

We recommend using HTML directly, even when overlayed this way. That's because multiple area outputs can get confused if the $HTML function has been used to establish TITLE, LINK, STYLE, Sn or Xn. These terms are common to all HTML areas, and therefore it is NOT recommended that you have more than one ASSIGN AREA active at a time. Therefore, only one area is needed, and it may as well be HTML itself.

Next, we do NOT recommend fixed-dimension areas, although they may be necessary to get old formats designed for the CRT to work properly. We recommend line-by-line areas (row dimension of 0).

Your formats designed for HTML should have a FRAME-TYPE = STARTUP that establishes the TITLE and other information that should appear in the header of the output documents. The first thing you should do is reset all previous information:

This clears out old information, and lets you define information that is relavent to this format. But be careful. If you SET FORMAT on several paths, only the last one will effectively be active.

Alternatively, you can establish header information directly by EVAL $HTML(parm,string) commands, possibly in a protocol. Or you could use a combination of a STARTUP frame and then EVAL $HTML function commands to make a few alterations.

We recommend the following order:

Of course, you probably don't need all these steps, and some of them may be done by protocols (or extended execs). The "for" through "endfor" could be replaced by "in html clean type" if you have a search result or stack. But "for" through "endfor" could be used with them too.

You might also do "in html set write" once at the beginning to insure that the html area is flushed when closed.

7.8  The NIO Area

The NIO device type enables you to read and send information from/to a Remote Host via ORVYL Network I/O services.

NIO device services include the ability to OPEN, CLOSE, READ or WRITE data to the network via functions or through Device Services Area processing. These services also include the ability to Trace the activity on a device and to display various types of information concerning the status of device activity.

The following information summarizes the NIO features:

1. NIO system variables

2. NIO device system functions.

$NETOPEN -- Create and Open a Network socket

$NETCLOSE -- Close a network device

$NETREAD -- Receive data from a network device

$NETWRITE -- Send data to a network device

Note that certain types of errors may occur in which $NETSTATUS is not set. This condition will occur if there is a system error during the process (EG. Out of core -- S198) or if you issued invalid values in the function call.

$NETINFO -- Return information concerning network device activity

3. NIO Device Area Processing.

You may utilize the NIO Device Services facility either in place of or in conjunction with the above $NIO functions to Open, Close, receive or send data to a remote host. This facility will simplify the processing of data that may be used with SPIRES processes such as Input and Output FORMAT processing which will shield you from the problems having to do with end-of-line, end-of-file, getting all the data etc. The NIO Device Services will allow you to deal with data as if it were a FILE device. The following commands may be used to establish an NIO area.

4. SHOW NIO INFORMATION command

This command may be used to display information concerning established NIO devices.

5. The NTRACE facility

Like other trace processes (PTRACE, FTRACE, XTRACE) the NTRACE process may be captured in the TLOG file.

8  The Host Language Interface (HLI)

HLI is not defined in the Unix/Linux environments. This is a historic mainframe description.

The HLI is a way for programs written in any language to read data from or write data to SPIRES files. In addition to being an interface to SPIRES files, the HLI provides an interface to the rest of the interactive environment (WYLBUR, JES, ORVYL, MILTEN), by allowing the same commands that would be typed at an interactive terminal to be "issued" by a host program and passed to the interactive environment by the HLI.

The host program will include three "calls": 1) SPISET, to open the communication paths between the program and SPIRES, 2) SPIRES, to pass commands and data back and forth (note that this is totally different from the CALL SPIRES command in the interactive environment), and 3) SPIXIT, which terminates the SPIRES session. Only one SPISET call may be made per job, and usually only one SPIXIT call, but multiple SPIRES calls are normally used.

The following drawing illustrates the paths of data and commands between SPIRES and a host language program.

                       +--------------------------------------------+
                       |                                            V
 +------------+        V                   +------------+  +------------+
 |            |    +-------+               |            |  |            |
 |    HOST    |    |  JOB  |<--------------|            |  |            |
 |  PROGRAM   |    |  LOG  |               |   SPIRES   |  |   WYLBUR   |
 |            |    +-------+               |            |  |            |
 |            |                     +------|            |->|            |
 +------------+                     |      +------------+  +------------+
         |    |                     V        |    |
         |    |     +-------------------+    |    |  IN HLCA TYPE
         |    |     |               |   |    |    |  IN HLIO MERGE
         |    |----------COMMANDS----------->|    |
         |    |<---------RESPONSE------------|    |
         |          |               |   |         |
        +------+    |       HLI     |   |   +------+
        |      |    |               |   |   |      |
        | DATA |------------READ----------->| HLCA |
        |REGION|<-----------WRITE-----------| HLIO |
        |      |    |               |   |   |      |
        +------+    +-------------------+   +------+
        |      |                    |
        | DATA |                    V
        |REGION|    +------------------------------+
        |      |    |    HLIPRINT  or  SYSPRINT    |
        +------+    +------------------------------+

Like in all other Device Services processing, data is moved between SPIRES and the device via areas. In this case, the "device" is a data region defined by the host program, and the areas are HLIO and/or HLCA.

More than one data region can be used and assigned to areas defined on HLCA or on HLIO. In this sense, it is similar to using FILE areas, which can be assigned to different disk files.

8.1  Areas used with the HLI

The Device Services areas that are used with the HLI are the HLIO [See 2.4.] and HLCA [See 2.5.] areas.

In most cases, you normally would only need the system-defined HLIO area to pass data back and forth, but you may define areas on the HLCA area. Like the FILE area, the HLCA area is of indefinite capacity and its size is determined by the areas defined on it. It allows multiple "lines" of data to be transferred at a time.

Note that for any one SPIRES path, HLCA and HLIO occupy identical space in memory; data written to one is present in the other by definition. Either area may be associated with separate data regions in the host program. Either SPIRES path has its own physical HLIO/HLCA space associated with it. [See 8.2.1.] Thus, if multiple simultaneous HLIO/HLCA areas are needed, multiple paths can be used.

8.2  Using the HLI

The host program must include the following JCL for its linkage editor (LKED) step and its execution (GO) step:

For COBOL programs compiled with the DYNAM option (the standard in AIS), it is necessary to use a special interface to the HLI called UTMSPI. The second and subsequent parameters of the UTMSPI call correspond to the first and subsequent parameters of the SPISET, SPIRES, and SPIXIT calls.

Thus,

             DYNAM                               STATIC

  CALL 'UTMSPI' USING 1, parms     =     CALL SPISET USING parms
  CALL 'UTMSPI' USING 2, parms     =     CALL SPIRES USING parms
  CALL 'UTMSPI' USING 3, parms     =     CALL SPIXIT USING parms

Symbolic syntax shown in the following sections is for (A) PL/1 or similar languages, [See 8.5.] (B) COBOL (without DYNAM), [See 8.4.1.] (C) COBOL (with DYNAM), [See 8.4.2.] (D) C language. [See 8.7.] Calls must, of course, obey the conventions of the host language with respect to literal and symbolic parameters, punctuation, continuations, etc.

8.2.1  The SPISET Call

The host program establishes communication paths to SPIRES via the SPISET call to HLI. The first parameter of the SPISET call specifies the number of paths to open. Each path opened begins a separate session in the WYLBUR/ORVYL/SPIRES interactive systems; these are called "virtual sessions." There is currently a limit of 4 paths.

For each path there are two links: a command link and a data link. Each command link requires a response buffer within the host program, so the second and subsequent parameters of the SPISET call specify the address of 60-byte response buffers, one for each path. The total number of parameters is equal to the number of paths + 1. Several paths may share the same response buffer. Each response buffer begins with integer values equivalent to the variables $NO, $RELPOS, $STACK, $RESULT, $MNUM, $SNUM, and $ENUM. Each of these values is 4-bytes long, and each SPIRES call [See 8.2.2.] causes the appropriate response buffer's variables to be updated based upon the results of the call.

The syntax of the SPISET call is:

The SPISET call is logically equivalent to a logon for each path. The account and keyword used for the logon are taken from the account of the host job. (The account's SPIRES entry commands are executed, but the logon EXEC file is not.)

Currently, active virtual sessions' statistics can be displayed at the terminal by the SHOW LINES VIRTUAL command and the SHOW VIRTUAL command.

8.2.2  The SPIRES Call

Once communication paths have been established, the host program can send commands to interactive SPIRES by calling upon the SPIRES entry in the HLI module as often as necessary. The basic syntax of the call is:

The first parameter (path#) identifies the number of the path/session for which the command stream is meant.

The second parameter, "commands", consists of one or more commands separated from each other by semi-colons, and terminated by double semi-colons. An individual command may not contain semi-colons, and must not exceed 133 characters in length; otherwise, an error will occur. Commands may be imbedded within the program itself, read from some external source, or both. The following are examples of SPIRES calls with different command streams imbedded in the program:

These calls from the host program to the SPIRES entry in HLI place HLI in control. HLI then sends these commands, one at a time, to online SPIRES. When all commands have been sent, HLI returns to the host program. If one of the commands fails, HLI does not send any remaining commands associated with this call to online SPIRES, but instead returns immediately to the host program. $NO in the response buffer will be non-zero if a command fails. The other variables in the response buffer will reflect the state of their counterpart in online SPIRES at the time of the last executed command. For example, if the command stream had been:

then $RESULT would contain the result count, and $RELPOS (similar to $GXCOUNT, but only for STACKS and RESULTS) would contain the relative position within Global FOR. The I/O parameters of the CALL statement are only needed if the commands involve data transmission. [See 8.2.3.] If the third and fourth parameters are not included when passing commands that involve data transfer, HLI will signal an error.

8.2.3  Data Transfer Between SPIRES and the Host Program

Between the Host and HLIO/HLCA

Besides the $variable responses, commands can cause transmission of "data" that requires the I/O parameters. The third and fourth parameters of the CALL SPIRES statement identifies which of the host program's data regions data is to be moved from or to. As with other Device Services areas, the READ and WRITE commands may be used to move data between an area and the device. In the case of the HLI, the data is being moved between the host program's data region(s) and either the HLIO or HLCA area (or areas defined on them). A maximum of 4092 bytes of data can be transmitted to or from the host program in a single operation (e.g., a single WRITE or READ).

Between the HLIO/HLCA and SPIRES

SPIRES transfers from or to the HLIO/HLCA area only as much data as specified in the I/O length parameter in the CALL statement. Data will automatically be transferred to the HLIO/HLCA area when a SPIRES command that does data output is executed; that is, SET WRITE is the default in the host language environment.

Data will NOT automatically be transferred from the HLIO/HLCA area to SPIRES when a SPIRES command that reads input is executed; that is, SET READ is not the default in the host language environment. Any command that attempts to read data from the HLIO/HLCA area should be preceded by an explicit READ command to copy the data from the host's data region to the SPIRES HLIO/HLCA area. For example, using PL/I conventions, and assuming a format is set:

Data is usually transferred to and from the HLIO/HLCA areas by a SPIRES format (including system formats such as $REPORT), since a format can place or read data in the fixed positions normally used to map the HLIO/HLCA area to the host's data region. Unformatted input from areas is not supported. However, a format is not necessary for data output.

For example, if you wish to inform the host program of the key of the record most recently processed, it may be sufficient to pass the command:

The HLIO area would then contain the value of $KEY (blank-padded to the length in the I/O length parameter).

A single SPIRES call can pass commands that first read the contents of the host program's data region, and then write data back to that region. If multiple WRITEs occur in a single command stream, the host program will only see the last one since HLI doesn't return to the host program till after the last command has been executed in that command stream. Generally, however, only one data transfer command occurs in any particular command stream.

HLIO Area

When using the HLIO area, if the data is to be transferred by a format, the frame dimensions must specify a single row up to 4092 columns. For example:

HLCA Area

When using the HLCA area, you may reference either the HLCA area directly, or define areas (in a CALL to SPIRES) on the HLCA area and reference them.

Consider the following DEFINE AREA command:

This causes HLCA to expand to the 10 by 20 dimensions given. HLCA is now the same size as A, so either can be referenced (e.g., IN HLCA DISPLAY 10 and IN A DISPLAY 10 will produce identical results.)

If you issue these commands:

then the HLCA area would take 10 by 40 dimensions (rows from A, columns from B). That means there is another piece in the lower right corner of HLCA that could be defined as:

If you place information in any of the defined areas, only that section of HLCA receives data, but the entire HLCA area is transmitted to the host language program. The dimensions of HLCA defines the number of bytes transmitted, i.e., (rows) x (cols). Data transmitted is considered to be a linear series of bytes without dimensions. If HLCA has multiple rows, then the series is just row 1, followed directly by row 2, row 3, etc.

The two-dimensional character array allowed by HLCA -- compared to the one-dimensional array allowed by HLIO -- has possible advantages to the programmer:

HLCA or HLIO is transmitted to the host program whenever:

HLCA or HLIO is read by the host program only by a specific READ command. Note that an areaname is not required on READ or WRITE commands if there is a default assigned to the IDATA or ODATA functions. For host language sessions, HLIO is assigned as the default for both IDATA and ODATA. You can change the defaults with the "SET AREA" command. [See 3.3.]

See Appendix B for a list of commands that may use HLIO or HLCA.

8.2.4  Output to HLIPRINT or SYSPRINT

Many commands produce a data or message response that cannot be directed to the HLIO or HLCA areas. Any output from a SPIRES command that would normally be displayed on the terminal (e.g., the result message from FIND, or the output from IN TER TYPE, etc.) will be sent to the host program's print output.

HLI will attempt to send print output to the HLIPRINT data set. If no such DD statement is found, then HLI sends output to SYSPRINT. Of course, if the host program also writes to SYSPRINT, then output will be interspersed between HLI and the host program.

Once an HLI program has been debugged, a "SET INFORMATION MESSAGES = 0" command is usually placed in the program to reduce the output sent to the printer.

8.2.5  The SET PATH ECHO Command; The $ENVIRON Variable

If the SPIRES command "SET PATH ECHO" is passed to SPIRES during the execution of a host language program by any of the "users" declared in the program, then all subsequent messages that would be printed by online SPIRES for that "user" (e.g., echo of protocol commands, informational and error messages such as "-NO SUCH SUBFILE" or "-'RESTAURANT' SELECTED", or the display from a "*" command) will be written to the JES job log in addition to being written to HLIPRINT or SYSPRINT. The messages are always written to HLIPRINT or SYSPRINT unless a SET MESSAGES command has been issued to change the message level; but the messages written to HLIPRINT or SYSPRINT are not separated by path. If more than one SPIRES user is being simulated, then the messages passed by SPIRES to each "user" will be distinguished from those of other "users" in the JES job log. Also, commands that online SPIRES doesn't understand get passed on to the other interactive systems (WYLBUR, ORVYL, etc). If such commands cause a "response", that response is sent to the JES job log. The listing of the active file caused by a LIST command would be an example, as would the message from a SAVE command.

SET PATH ECHO is intended ONLY for use as a debugging aid, since its use incurs some overhead for communication between the batch and online systems.

The $ENVIRON variable has a value of "2" when the SPIRES session is under HLI control. This variable can be tested by entry commands, protocols, formats, etc.

8.2.6  The SPIXIT Call

The SPIXIT call terminates the virtual terminal paths. If SPIXIT is called with a parameter, that parameter specifies a single specific path to be terminated. Other paths (if any) will remain active. Eventually there must be a SPIXIT call with a zero or no parameter to close out HLI. All ORVYL files are closed and all HLI paths are terminated. If you do not issue the SPIXIT call before the end of your job, unpredicatable ABEND errors may occur (most likely SA03).

The syntax of the final call is:

8.3  Host Language Interface Error Messages

Incorrect parameter list

This message indicates that the CALL SPIRES either

 - has a user-number <= 0 or > the maximum (currently 4)
 - does not have either 2 parameters (if no host language I/O is being done in the CALL)  or
 4 parameters (if host language I/O is being done by commands in the CALL)

***** Incorrect parameter list *****

This message indicates that the CALL SPISET either

 - has an invalid path-number
 - has a number of parameters unequal to the path-number plus one

No semicolon in 133 characters

This message indicates that an attempt was made to pass a single command (perhaps part of a multiple-command string) across the interface, but the command was over 133 characters. Multiple commands must be delimited by a semicolon; a string of commands must be terminated by a double semicolon. This error is frequently due to a missing semicolon.

Entire command blank

This message indicates that no non-blank characters were found between the beginning and ending of a command. This error may be caused by not putting a value in a host-program variable, or by putting a space between the double-semicolons that are the command-string terminator.

No data address in COBOL

This message indicates that I/O between SPIRES and the host language program (whether in COBOL or not) was attempted by a command in the command-string, but the CALL SPIRES did not specify an I/O area and/or the length of the I/O area on the CALL.

Too many parms on SPIXIT

This message indicates that the SPIXIT call has more than one parameter.

Command failure on: command

This message is printed whenever a command failure is detected, i.e., $NO is set. The "Command failure" message appears after the standard SPIRES error message(s) that was caused by the command that failed, e.g.,

The command that caused the failure is written out as part of the message. If SET PATH ECHO [See 8.2.5.] is in effect, then the system response to the command failure (e.g., "No such subfile" in response to a "SELECT" command that named an unknown subfile) is written to the JES job log; in all cases, the system response is written to SYSPRINT/HLIPRINT.

Invalid: command

This message may appear in the JES job log. If it does, it indicates that some command was passed from SPIRES to the other interactive systems available through the HLI (WYLBUR, ORVYL, MILTEN) and that none of those systems recognized the command.

Other error messages are possible, but generally reflect internal SPIRES problems. Some examples of these messages are '-Path code wrong' or '-Path read not successful.' If you get one of these error messages, see your SPIRES consultant.

8.4  Two Examples of Using the HLI from a COBOL Host

8.4.1  COBOL Host Program: STATIC Option Used in Compilation

Example of a simple COBOL host program inputting data:

The SYSPRINT or HLIPRINT listing generated by the program's execution:

The file definition in FILEDEF:

The format definition in FORMATS:

8.4.2  COBOL Host Program: DYNAM Option Used in Compilation

The following program is identical to the previous COBOL program example except for added or changed lines marked with an asterisk at the right margin (don't include the asterisk in the COBOL code, of course). This COBOL example should be used as a model for coding COBOL/HLI programs when the COBOL program is compiled with the DYNAM parameter (as is the standard in AIS).

    ID DIVISION.
    PROGRAM-ID.
        COBLPROG.
    AUTHOR.
        JIMMSE MANDL.
    ENVIRONMENT DIVISION.
    CONFIGURATION SECTION.
    SOURCE-COMPUTER. IBM-3081.
    DATA DIVISION.
    WORKING-STORAGE SECTION.
    77  USER-NO     PIC 9(6) COMP SYNC VALUE 1.
    77  SETUP       PIC X(43) VALUE 'SEL HOST;SET FOR HOST;;'.
    77  COM1        PIC X(10) VALUE 'READ;ADD;;'.
    77  IOAREA      PIC X(1000) VALUE '12345 HI THERE'.
    77  IOLEN       PIC 9(6) COMP SYNC VALUE 1000.
    77  BAD-DATA    PIC X(14) VALUE 'XXXXX 99999999'.
    77  HLIO-SPISET PIC X VALUE '1'.                                   *
    77  HLIO-SPIRES PIC X VALUE '2'.                                   *
    77  HLIO-SPIXIT PIX X VALUE '3'.                                   *
    01  RETURN-CODES.
        02  NO-COND PIC 9(6) COMP SYNC VALUE 0.
        02  RELPOS  PIC 9(6) COMP SYNC VALUE 0.
        02  RESULT  PIC 9(6) COMP SYNC VALUE 0.
        02  STACK   PIC 9(6) COMP SYNC VALUE 0.
        02  MNUM    PIC 9(6) COMP SYNC VALUE 0.
        02  SNUM    PIC 9(6) COMP SYNC VALUE 0.
        02  ENUM    PIC 9(6) COMP SYNC VALUE 0.
        02  RFILR   OCCURS 8 TIMES PIC 9(6).
    PROCEDURE DIVISION.
    INITIALIZATION.
        CALL 'UTMSPI' USING HLIO-SPISET, USER-NO, RETURN-CODES.        *
        IF NO-COND > 0 GO TO ERROR-ROUTINE.
        CALL 'UTMSPI' USING HLIO-SPIRES, USER-NO, SETUP.               *
        IF NO-COND > 0 GO TO ERROR-ROUTINE.
    SUBROUTINE.
        CALL 'UTMSPI' USING HLIO-SPIRES, USER-NO, COM1, IOAREA, IOLEN. *
        IF NO-COND > 0 GO TO ERROR-ROUTINE.
        CALL 'UTMSPI' USING HLIO-SPIRES, USER-NO, COM1, IOAREA, IOLEN. *
        IF NO-COND > 0 GO TO ERROR-ROUTINE.
    ERROR-ROUTINE.
    CLOSE-ROUTINE.
        CALL 'UTMSPI' USING HLIO-SPIXIT.                               *
    EXIT-ROUTINE.
        STOP RUN.

8.5  Two Examples of Using the HLI from a PL/1 Host

8.5.1  PL/1 Host Program: Single-Path Example

// JOB (,,.25)
/*JOBPARM ONLINE=YES  Require that interactives be available.
/*jobparm copies=3
// exec plixcg,parm.go=nomap
//pli.sysin dd *
* PROCESS OPTIMIZE(TIME);
* PROCESS MARGINI('|'), MARGINS(1,72), SEQUENCE(73,80);
* PROCESS XREF(SHORT), AGGREGATE, STMT, GOSTMT;

addmisc: procedure options(main) reorder;

   /*   This program adds miscellaneous charge records to the
        MISC.CHARGES RECORDS subfile via the Host Language Inter-
        face.

        Records are read from file INPUT.  Records which are
        successfully added to the subfile are written out to file
        ACCEPTS.  Records which are not successfully added are
        written to file REJECTS.

                                                */

 /***** Declaration of variables and external procedures *****/

 /* The Host Language Interface is called through three external
    procedures.
                                                */


declare (spiset, spires, spixit) external options(asm inter);

 /* PL/I can't really check the validity of arguments, so no
    attempt is made to do so.  The calling program must insure that
    the correct things are passed.

    The OPTIONS(ASM INTER) clause tells PL/I to pass arguments
    directly instead of passing location-descriptor address, and
    to handle system abends caused by the called procedure.  For
    more information, see the PL/I Language Reference Manual.  */
 /* We have to declare the communications area. */

declare 1 comm_area,
          2  ($no,
              $relpos,
              $result,
              $stack,
              $msgnum,
              $snum,
              $enum)    fixed binary(31,0),
          2   filler     char(32);

 /* We also need some program variables */

declare hlio_area char(80);  /* The input records are placed here
                                before being added. */

declare hlio_length fixed binary(31,0) init (80);
                               /* This contains the length of the
                                  hlio area.  PL/I will not pass
                                  the number in the correct format
                                  if the length is specified as a
                                  constant in the call to SPIRES. */

declare user_1 fixed binary(31,0) init (1);
                            /* Just a number.  See the comment for
                               hlio_length. */

declare eof char(1) init('N');

declare (oncode, pliretc) builtin, intabnd condition;

declare input record input file;
declare (accepts, rejects) record output file;
declare mcounts stream output file;

open file (input),
     file (accepts),
     file (rejects),
     file (mcounts) linesize(80);

declare sysprint print file;
open file (sysprint) title ('SYSOUT');
                 /* SYSPRINT is the standard output file for PL/I.
                    It is also the outfile file for error messages
                    from the HLI.  To prevent the messages from
                    being intermingled, the DD statement for
                    SYSOUT will be used for the SYSPRINT output
                    of this program. */
declare 1 counts,
         2 (input,
            accepts,
            rejects)  fixed binary(31,0) init(0);

declare i fixed binary(15,0);  /* loop counter variable */

declare 1 mcounta(100) aligned,
          2 (mcount,
             mtotal) fixed binary(31,0);

 /***** Program setup *****/

on endfile(input) eof = 'Y';

on error
   begin;
   on error system;
   if oncode() = 9050
   then
      signal condition(intabnd);
   call put_counts;
   put data;
   call pliretc(16);
   call spixit; /* To prevent horrendous abends */
   stop;
   end;

on condition(intabnd)
   begin;
   on condition(intabnd) signal error;
   if oncode() = 9050
   then
      put file (sysprint)
          edit ('An abend has occurred.  The probable cause is ' ||
                'a failure in the interactive systems.')
               (col(1), a);
   call put_counts;
   call pliretc(20);
   call spixit;
   stop;
   end;
 /***** Now we call SPISET to get a path, then select the subfile.
        The format is automatically set.        *****/

call spiset(user_1, comm_area);

if $no
then
   do;
   put file (sysprint)
       edit ('Could not open HLI path.')
            (col(1), a);
   signal condition(intabnd);
   end;

call spires(user_1, 'select misc.charges records;;');
if $no
then
   do;
   put file (sysprint)
       edit ('Could not select MISC.CHARGES RECORDS.')
            (col(1), a);
   signal condition(intabnd);
   stop;
   end;

call spires(user_1, 'set mes 0;;');
if $no
then
   do;
   put file (sysprint)
       edit ('Could not SET MES 0.')
            (col(1), a);
   signal condition(intabnd);
   stop;
   end;
 /***** Read file INPUT and add records *****/

read file(input) into (hlio_area);

do while (eof = 'N');
   counts.input = counts.input + 1;
   call spires(user_1, 'read;in hlio using cardin.total add;;',
               hlio_area, hlio_length);
   if $no
   then
      do;
      write file (rejects) from (hlio_area);
      call spires(user_1, '* Record is '''||hlio_area||''';*;;');
      /* if the record doesn't add, we want to print it on the
         SPIRES log right after the error messages.  A * will
         separate sets of error messages and records.  */
      counts.rejects = counts.rejects + 1;
      end;
   else
      do;
      write file (accepts) from (hlio_area);
      counts.accepts = counts.accepts + 1;
      end;
   read file (input) into (hlio_area);
   end;

 /* Now that we have finished adding the records, we want to
    print counts.  We will do so two ways.  Record types for which
    there were records will be printed on SYSPRINT.  Counts and
    totals for all records will be written to file COUNTS. */

 /* first, get the counts */
hlio_length = 800;
call spires(user_1, 'in hlio xeq frame hli.counts;;',
            mcounta, hlio_length);

put file (sysprint) skip (2)
    edit ('Record type           Count          Totals')
         (col(1), a);

put file (sysprint) skip;
 do i = 1 to 99;
   put file (mcounts) skip
       edit (i, mcount(i), mtotal(i))
            (p'9999', x(2), p'999999', x(2), p'999999999.99V');
       if mcount(i) ~= 0
       then
          put file (sysprint)
              edit (i, mcount(i), mtotal(i))
                   (col(8), p'ZZZ9',
                    col(21), p'ZZZ,ZZ9',
                    col(33), p'$---,--9.99');
end;

 /* Write a time and date stamp */

put file (mcounts) skip
    edit (date(), time())
         (col(1), a, x(1), a);

call spixit;  /* Terminate the SPIRES session */

close file (input),
      file (accepts),
      file (rejects),
      file (mcounts);

put_counts: procedure;

 /* This procedure writes counts to SYSPRINT. */

put file (sysprint) skip(2)
    edit ('Records read from INPUT: ', counts.input,
          'Records accepted:        ', counts.accepts,
          'Records rejected:        ', counts.rejects)
         (col(10), a, p'ZZZ,ZZ9');

end put_counts;

end addmisc;
//go.steplib dd dsn=wyl.gg.prd.hlilib,disp=shr
//go.syslib dd dsn=wyl.gg.prd.hlilib,disp=shr
//go.sysout dd sysout=$
//go.input dd dsn=wyl.gb.jfh.testmisc,disp=shr
//go.accepts dd sysout=$,dcb=card
//go.rejects dd sysout=$,dcb=card
//go.mcounts dd sysout=$,dcb=card

8.5.2  PL/1 Host Program: Multiple-Path Example

     /* INITIALIZE FOR 2 SPIRES USERS, SHARING RETURN CODE AREA */
             CALL SPISET(USER_NO_2,RETURN_CODES,RETURN_CODES);
             IF NO ~= 0 THEN GOTO ERROR;

             CALL SPIRES(USER_NO_1,
                'SET INFO MES 0;SET WARN MES 0;SET WRITE;'
             || 'SEL MAIL;SET FOR ACCTS;EXTRACT;FOR STACK;;');
             IF NO ~= 0 THEN GOTO ERROR;

             CALL SPIRES(USER_NO_2,
                'SET INFO MES 0;SET WARN MES 0;SET WRITE;'
             || 'SEL ADDRESS;SET FOR HLIO LABELS;'
             || 'FOR RESULT;;');
             IF NO ~= 0 THEN GOTO ERROR;

             GO TO GET_ACCT;
     ERROR:
             NO_CODE = NO;
             PUT SKIP EDIT (ERROR_MESSAGE)(A);
             PUT SKIP DATA (MNUM,SNUM,ENUM);
             GO TO DONE;

     GET_ACCT:
             CALL SPIRES(USER_NO_1,'USING FRAME DIS;;',
                        ACCT,ACCT_LEN);
             IF MNUM = 63 THEN GOTO DONE;
             IF NO ~= 0 THEN GOTO ERROR;

             FIND = ACCT, BY NAME;
             CALL SPIRES(USER_NO_2,FIND);
             IF NO ~= 0 THEN GOTO ERROR;
             IF RESULT = 1 THEN DO;

             CALL SPIRES(USER_NO_2,'USING HLIOFRAME DIS;;',
                        ADDRESS,ADDRESS_LEN);
             IF NO ~= 0 THEN GOTO ERROR;

                DO I = 1 TO 5;
                PUT FILE (LABLOUT) SKIP EDIT (ADDRESS(I))(A(30));
                END;
             END;
             ELSE PUT SKIP EDIT (RESULT,' ACCOUNT(S) FOR ',
                      ACCT.GG,'.',ACCT.III) (5(A));

             GO TO GET_ACCT;
     DONE:
             CALL SPIXIT;
             CLOSE FILE (LABLOUT);
             END SAMPLE;

8.6  Example using PL360 as the host language

The following program illustrates many of the concepts discussed in this chapter. The program is written in PL360, a programming language that provides Algol-style Assembly-level capability. This program establishes the HLCA as a data area that looks like a 60-line page, with 64 characters per line. The first few commands sent to SPIRES are built into the program itself. Then the program reads command lines from SYSIN, prints them on SYSPRINT, and sends them to SPIRES. The commands read from SYSIN would need semi-colon separation and may have double semi-colon termination, although the program safeguards against forgetting them. After each command line is sent, the contents of the response variables are printed on SYSPRINT, followed by the non-blank lines of the PAGE.

Below are some samples of command streams that could follow SYSIN. These examples are not meant to be exhaustive, but only serve to illustrate a variety of possibilities. Text in uplow represents items for which you would substitute values appropriate to your application.

SELECT subfile; THRU 1 SELECT sub2;; after double is comment.
SET FORMAT form1 startparm; THRU 1 SET FORMAT alternate;;
FOR SUBFILE WHERE elem = value; SET SCAN BACKWARDS
DISPLAY 10;; comment: 10 records fit on a page.
BLANK HLCA; WRITE HLCA;; - Blank host's data region.
CLEAR FORMAT; FIND personal name; FOR RESULT;;
TRANSFER; CHANGE "old" TO "new" NOLIST; UPDATE;; - uses Active File
SET FORMAT bidirectional; IN HLCA DISPLAY;; - Host gets record.
READ; UPDATE; DISPLAY;; - HLCA is read & written with format.
DEFINE AREA box2 (60,32) ON HLCA(1,32); WRITE box2;;
DEFINE AREA box1 (60,32) ON HLCA(1,1) OVERFLOW TO box2;;
IN box1 SET NOWRITE; IN box1 SHOW ELEMENT NAMES;;
WRITE HLCA; BLANK HLCA INTERNAL;;
WITHIN XEQ, THRU 1, IN box2, USING frame, DISPLAY record;;
SHOW EVAL $DATE ' ' $TIME; SET WIDTH 32;;
LET alpha = $ACCOUNT; IF #alpha = 'gg.uuu' : EXPLAIN help;;
// JOB ,TIME=(,15)
/*JOBPARM ONLINE=YES
// EXEC PL360CL
//PL360.SYSIN DD *
  BEGIN INTEGER NOFLAG, RELPOS, RESULT, STACK,
           MNUM, SNUM, ENUM;    |-- response variables --|
        ARRAY 8 INTEGER FILLER;  |-- to fill 60 bytes. --|
        INTEGER USER = 1;        |-- only one session. --|
        ARRAY 134 BYTE COMMAND = 134(" ");
        ARRAY 2 INTEGER SETUP = (@@USER,@@NOFLAG(0/#80));
        INTEGER PAGELEN = 3840;  |-- data region length --|
        ARRAY 4 INTEGER PARM1 =  |-- parm list for SPIRES --|
        (@@USER,@@COMMAND,@@FILLER,@@PAGELEN(0/#80));
        ARRAY 3840 BYTE PAGE = 3840(" ");  |-- data region --|
           EXTERNAL PROCEDURE SPISET (R14) BASE R15;  NULL;
           EXTERNAL PROCEDURE SPIRES (R14) BASE R15;  NULL;
           EXTERNAL PROCEDURE SPIXIT (R14) BASE R15;  NULL;
     R1 := @PAGE =: PARM1(8); |-- data address --|
     R1 := @SETUP;  SPISET;  |-- start session --|
     COMMAND := "DEFINE AREA X (60,64) ON HLCA (1,1);;";
     R1 := @PARM1;  SPIRES;  |-- establish large HLCA --|
     COMMAND := "SET AREA HLCA ODATA; SET AREA HLCA IDATA;;";
     R1 := @PARM1;  SPIRES;  |-- HLCA is default I/O area --|
     WHILE  R0 := @COMMAND;  READ;  = DO  |-- Commands Ready --|
     BEGIN  R0 := @COMMAND;  WRITE;       |-- Print Commands --|
        COMMAND(80) := ";;";  R1 := @PARM1;  SPIRES;  |-- Send --|
        COMMAND(60/30) := COMMAND(90);    |-- blank pad --|
        R1 := @COMMAND;  R2 := 1;  R3 := 9;  |-- length --|
        R4 := @NOFLAG;  R5 := @FILLER;  WHILE R4 < R5 DO
        BEGIN  R0 := B4;  VALTOBCD;  R1 := R1 + R3;
           R4 := @B4(4);  |-- increment to next variable --|
        END;  R0 := @COMMAND;  WRITE;  |-- print variables --|
        R4 := @PAGE;  R5 := R4 + PAGELEN;
        WHILE R4 < R5 DO  |-- print non-blank data lines --|
        BEGIN  COMMAND(0/64) := B4;  R4 := @B4(64);
           IF COMMAND(0/64) ~= COMMAND(64) THEN
           BEGIN  R0 := @COMMAND;  WRITE;
           END;  |-- only non-blank lines printed --|
        END;  |-- keep reading commands till EOF on SYSIN --|
     END;  R1 := R1--R1;  SPIXIT;   |-- terminate session --|
  END.
/*
//LKED.SYSLIB DD DSN=WYL.GG.PRD.HLILIB,DISP=SHR
//GO EXEC PGM=MAIN
//STEPLIB DD DSN=&&GOSET,DISP=(OLD,DELETE),UNIT=SYSDA
// DD DSN=WYL.GG.PRD.HLILIB,DISP=SHR
//SYSPRINT DD SYSOUT=A,DCB=(BUFNO=1)
//HLIPRINT DD SYSOUT=A
//SYSIN DD *

8.7  Example using C as the host language

The following program, written in C, illustrates many of the concepts discussed in this chapter. This program establishes the HLCA as a data area that looks like a 50-line page, with 80 characters per line. The first few commands sent to SPIRES are built into the program itself. Then the program reads command lines from stdin, writes them to stdout, and sends them to SPIRES. The commands read from stdin would need semi-colon separation and may have double semi-colon termination, although the program safeguards against forgetting them. After each command line is sent, the contents of the response variables are written to stdout, followed by the non-blank lines of the 50-line page.

Note that CSPISET may be called with a variable number of arguments, the first of which must be the non-zero number of simultaneous SPIRES users (1 through 4), and then that number of pointers to response areas. Also note that CSPIXIT may be called with a specific user number, closing just that path to SPIRES, but you must call CSPIXIT(0) before leaving to terminate all HLI paths.

Below are some samples of command streams that could appear in the stdin input stream (//SYSIN). These examples are not meant to be exhaustive, but only serve to illustrate a variety of possibilities. Text in uplow represents items for which you would substitute values appropriate to your application.

SELECT subfile; THRU 1 SELECT sub2;; after double is comment.
SET FORMAT form1 startparm; THRU 1 SET FORMAT alternate;;
FOR SUBFILE WHERE elem = value; SET SCAN BACKWARDS
DISPLAY 10;; comment: 10 records fit on a page.
BLANK HLCA; WRITE HLCA;; - Blank host's data region.
CLEAR FORMAT; FIND personal name; FOR RESULT;;
TRANSFER; CHANGE "old" TO "new" NOLIST; UPDATE;; - uses Active File
SET FORMAT bidirectional; IN HLCA DISPLAY;; - Host gets record.
READ; UPDATE; DISPLAY;; - HLCA is read & written with format.
DEFINE AREA box2 (50,40) ON HLCA(1,41); WRITE box2;;
DEFINE AREA box1 (50,40) ON HLCA(1,1) OVERFLOW TO box2;;
IN box1 SET NOWRITE; IN box1 SHOW ELEMENT NAMES;;
WRITE HLCA; BLANK HLCA INTERNAL;;
WITHIN XEQ, THRU 1, IN box2, USING frame, DISPLAY record;;
SHOW EVAL $DATE ' ' $TIME; SET WIDTH 40;;
LET alpha = $ACCOUNT; IF #alpha = 'gg.uuu' : EXPLAIN help;;
// JOB ,TIME=(,15)
/*JOBPARM ONLINE=YES
// EXEC C370CLG
//C.SYSIN DD *
#include <stdio.h>
#include <string.h>

 extern void CSPISET (long, void* ,...);
 extern void CSPIRES (long, char*, char*, long*);
 extern void CSPIXIT (long);

 static struct retcd {
    long noflag;
    long relpos;
    long result;
    long stack;
    long mnum;
    long snum;
    long ernum;
    long filler[8];
 } retcd;

 void main ()
 {  long buflen = 4000;
    char buffer[4000];
    char command[256];
    char *strptr, *strend;

    memset(buffer,' ',4000);  /* Blank buffer */
    CSPISET(1,&retcd);        /* Start SPIRES */
    CSPIRES(1,"DEFINE AREA X(50,80) ON HLCA;;",buffer,&buflen);
    strptr = "SET AREA HLCA ODATA; SET AREA HLCA IDATA;;";
    CSPIRES(1,strptr,buffer,&buflen);
    while (gets(command))        /* Input commands */
    {  printf("%s\n", command);  /* Output command */
       strcat(command,";;");     /* Terminate line */
       CSPIRES(1,command,buffer,&buflen);
       printf("%9ld %9ld %9ld %9ld %9ld %9ld %9ld\n",
         retcd.noflag, retcd.relpos, retcd.result,
         retcd.stack, retcd.mnum, retcd.snum, retcd.ernum);
       strptr = buffer;   /* Prepare to output buffer */
       strend = strptr + buflen;  /* Buffer ends here */
       while (strptr < strend)    /* Loop thru lines. */
       {  if (*strptr != ' ' || strncmp(strptr,strptr+1,79))
             printf("%.80s\n",strptr);
          strptr += 80;  /* Next line */
       }
       memset(buffer,' ',4000);   /* Blank buffer */
    }
    CSPIXIT(0);
 }
/*
//LKED.SYSLIB DD
//        DD DSN=WYL.GG.PRD.HLILIB,DISP=SHR
//GO.STEPLIB DD
//        DD DSN=WYL.GG.PRD.HLILIB,DISP=SHR
//GO.HLIPRINT DD SYSOUT=C
//GO.SYSIN DD *
SELECT RESTAURANT
SET FORMAT OUTPUT
FIND NAME RUE
TYPE

:  APPENDICES

:A  Appendix A: Size and Attribute Adjustments to Contained Areas

As described in Section 3.5, areas are either "contained" or "containing". A contained area is limited by the area that contains it. These limitations apply to size, placement, and area attributes.

All user-defined areas have a "declared" definition and an "actual" definition, the declared definition being what you specify on the DEFINE AREA command, the actual definition what the area currently is, given the confines of its containing area. But the declared definition is never "thrown away"; if the containing area is redefined, the actual definition of the contained area might also change.

This appendix describes the various ways that contained areas are affected by the definitions of the areas that contain them.

Size and Placement Adjustments

Size adjustments might be made when a contained area is defined. The actual size will always be as close to the declared size as the containing area will allow. Whenever the containing area is redefined, all contained areas will be altered in relationship to the containing area's new size. The following example demonstrates how this works.

Let's begin with an area ALPHA defined as follows:

Now, we define another area:

BETA is the upper left portion of ALPHA, leaving out the last four rows and right-most ten columns of ALPHA.

Now, we define another area:

We end up with the following actual definitions:

Notice that GAMMA begins at a point in BETA that causes the centers of the two areas to coincide.

Remember that you can always find out the current actual dimensions of an area by issuing the SHOW AREAS command.

Lastly, we define:

That creates an area as defined. But what happens if we now redefine BETA? Since both GAMMA and DELTA are defined on BETA, they might be forced to change dimensions. For example,

That reduced BETA to dimensions below what DELTA was declared to have, and it should affect the "center" of GAMMA as well. This is the result:

Let's shrink BETA some more:

We now have:

As you can see from the result shown above, both GAMMA and DELTA shrink to the same size as BETA. Let's expand:

We get:

Notice that BETA only expanded to the size of ALPHA, and both GAMMA and DELTA have expanded to their original declared sizes (which are both smaller than BETA's size).

If we had declared DELTA at a time when BETA was smaller than 18 by 60, the declaration would take place, but the actual dimensions of DELTA would shrink to fit within BETA. Then, when BETA expands at some later time, DELTA would expand also -- up to its declared limits or BETA's actual limits, whichever is smallest.

Areas Adjusted to Null

Sometimes an area will be impossible to place within its containing area because the "(srow,scol)" specification exists outside the boundaries of the containing area. In this case, the area becomes defined as having a null size, that is, a zero number of rows. This differs from the definition of a line-by-line area (which also has zero as the value for "rows"), because a line-by-line area cannot exist on an area of fixed-dimensions.

For example, some CRT screens have 32 rows, others only 24. If the following area were defined:

it would occupy the bottom four rows of a 32-row CRT screen. However, if it were defined on a terminal that has a 24-row screen, the actual definition would be:

and would be effectively null. Any data placed in this area would be lost.

Size Adjustments for Areas of Indefinite Size

An area may have an indefinite row capacity, meaning that the internal image of the area contains only one row; the area is written continuously as the one row overflows. An indefinite row capacity is specified by a zero value for "rows"; "areaname2" must also be of indefinite row capacity. As mentioned above, this differs from a null area because it is not defined on an area with fixed-dimensions. An area of indefinite row capacity can exist only on devices that are capable of unlimited input or output; currently this includes only FILE, TER, and HLCA (to the limit allowed by HLIO).

You may change an unlimited input/output device so that it operates as if it had a fixed capacity by defining an area with fixed dimensions on it. The uncontained area, as well as all areas contained by it, will then have a fixed capacity. Remember that line-by-line areas and fixed-dimension areas cannot exist on the same containing area at the same time.

As areas are defined on FILE, the size of FILE and possibly the size of all areas previously defined on FILE might change. If a starting row is not specified, the new area begins on the next possible row (the default starting position of "X"). If the area is given a starting position but not a size, it will expand to the remaining number of rows in the FILE area.

The following examples will demonstrate how this works:

Example 1:

If we define the following two areas on FILE:

we get the following actual definitions:

But, if we had defined TWO on ONE, we would get the following actual definitions:

FILE only expanded to the size necessary to contain all the areas defined on it.

Example 2:

Consider the following definitions:

   DEFINE AREA ONE (30) ON FILE
   DEFINE AREA TWO ON FILE (MIDDLE,MIDDLE)

If we begin with FILE as the default (0,80) area, then the definition for area ONE causes it and FILE to both become (30,80) areas. The column width of ONE is taken from FILE. Then area TWO is defined. The middle of FILE is (16,41) given that FILE is currently (30,80). Since TWO didn't declare either row or column sizes, FILE is not allowed to expand, so area TWO takes its size from the available space in FILE. The results are as follows:

    DEFINE AREA ONE (30,80) ON FILE (1,1) IODATA
    DEFINE AREA TWO (15,40) ON FILE (16,41) IODATA
    DEFINE AREA FILE (30,80) IODATE, NOMSG

Example 3:

The following command:

will create an area named ONE which is a line-by-line area. But, if instead, we issue this command:

then both ONE and FILE become 30 x 80. Because FILE is now of fixed-dimensions, a line-by-line area cannot also exist on it, so if we now issue the command

it will be given a default size and placement based on the 30 x 80 area. Because we did not specify a location on FILE where the area will begin, it defaults to 'X', which would be line 31. But line 31 does not exist because FILE is only 30 rows, so area TWO cannot exist and in effect becomes 0 rows (effectively null).

Now if we define another area as follows:

we end up with the following actual definitions:

This is because, first, all specified area dimensions are added up to figure the size of FILE. So 30 plus 5 makes FILE 35 rows by 80 columns. Next, the areas are placed on FILE: ONE begins at (1,1) on FILE and takes 30 rows; TWO begins at the next row, which is 31, and, because no size was specified expands to fill the rest of the possible space, which in this case is 5 lines; THREE is then begun at the next line which is 36, but because this is outside the possible size of FILE, it is defined as 0.

If we redefine area THREE, giving it a specific starting point within FILE as follows:

it would occupy the last five lines of FILE and TWO would be of zero length because it is still defaulting to "X" which doesn't exist. Size and placement specifications actually given on the DEFINE AREA command are considered first; default calculations are made afterward, and then in the order in which the DEFINE AREA commands were issued.

The above examples illustrate that when defining areas on flexible areas (FILE and HLCA), size adjustments can result in very different actual definitions, particularly if you allow defaults to take effect. It is recommended that you make your definitions as specific as possible.

Attribute Adjustments

Attributes can only be accepted for an area if the containing area allows it. Consider the following area definitions:

The ODATA assignment for area TWO cannot be accepted because ONE is only assigned IDATA. So the actual definition of area TWO becomes:

However, if we then redefine ONE as follows:

area two can now have its ODATA assignment because area ONE is now capable of accepting the ODATA function.

Area Attributes in Overlapping Areas

When an area overlaps another area, the attributes of the area are affected by the attributes of the area on which it lies. In the case of overlapping areas, the order in which the areas are defined determines the characteristics of the background fields in the space shared by two or more areas.

Any field that is common to overlapping areas receives its basic attributes from the last area defined that contains the field. Consider the following:

A picture of these areas looks like this:

           5       10        15       20       25
   1+-------------------------------------------+
   2|-------------------------+                 |
   3|                         |        A        |
   4|           B             |                 |
   5|                         |                 |
   6|               +---------|-----------------|
   7|---------------|---------+         C       |
   8|               |                           |
   9|      A        |                           |
  10+-------------------------------------------+

Background fields are assigned attributes as follows: The sections marked A have A's attributes. The sections marked B and C overlap A, but since they were declared after A, they have their own attributes. The small box in the middle takes C's attributes since C was the last area defined that contains the box. If B and C had been declared first, and then A, all background fields would be unprotected, even those in C. Only foreground fields in C would be protected.

Overlaying Protected Fields in Full-Screen Applications

Fields can be protected or unprotected by a combination of area attributes and format statements. There are three ways to set field protection:

 - The PROTECT|BGUNPROTECT|BGPROTECT area attribute
 - The DISPLAY = PROTECT|UNPROTECT statement in a label group
 - The SET PROTECT|UNPROTECT Uproc in a format's frame declaration section

If the containing area is assigned the PROTECT attribute, then all fields are protected (except when the contained area is BGUNPROTECT and overlapping rather than hierarchical, in which case the background fields are unprotected).

If the containing area is BGPROTECT or BGUNPROTECT with an overlaying area that is either BGPROTECT or BGUNPROTECT, then:

  1.  By default, all foreground fields are unprotected unless
      a "DISPLAY = PROTECT" statement is included in the label group.
  2.  If SET PROTECT Uproc is included, all foreground fields
      are protected, but can be unprotected with a "DISPLAY = UNPROTECT"
      statement.
  3.  If SET UNPROTECT Uproc is included, all foreground fields
      are unprotected, unless a "DISPLAY = PROTECT" statement is
      in the label group.

In any of the above three situations, the protection of the background fields varies as follows:

  1.  If the containing area is BGUNPROTECT, then all background fields
      are unprotected, unless overlaid with an area that is
      BGPROTECT or PROTECT.
  2.  If containing area is BGPROTECT, then all background fields are
      protected unless an area that is BGUNPROTECT is defined to overlap
      it, in which case background fields are unprotected.

For example, assume the following definitions:

The last 10 characters of ALPHA are BGUNPROTECT; therefore, any background field within this space would be unprotected.

:B  Appendix B: Valid Commands for the "IN areaname" Prefix

The following commands are valid for the "IN areaname" prefix, and can be used to place data in an area or read data from an area.

 General Commands
    EXPLAIN
    SHOW SYNTAX
    SHOW SPIRES MAIL
    SHOW SUBFILES
    SHOW EVAL
    SHOW EXAMPLE

 Searching
    SHOW INDEXES
    SHOW ELEMENTS
    SHOW SEARCH
    SHOW SUBFILE SIZE
    BROWSE

 Display
    TYPE
    DISPLAY

 Formatted Updating
    ADD
    UPDATE
    TRANSFER
    MERGE

 Formats
    SHOW FORMATS
    SHOW FRAMES
    XEQ FRAME frame-name

 Protocols
    -
    *

 Variables
    SHOW {STAVAR|DYNVAR|ALLOCATED}

 File Owner
    SHOW ARCHIVE
    SHOW FILE {STATUS|ACTIVITY}
    SHOW RECORD OVERHEAD
    SHOW SUBFILE {LOG|TRANSACTION}
    STATUS {ALL|record-number|DEFQ}
    AVSPREC

:29  SPIRES Documentation

I. Primers

II. User Language

III. Application Development

IV. Reference Guides (Cards)

V. Prism

VI. SPIRES Aids and Study Materials

VII. Other Related Documents

(The following documents are not SPIRES documents per se, but describe utilities and programs that may be useful in developing SPIRES applications.)

Obtaining Documentation

The above documents (except any marked "in preparation") may be obtained through the PUBLISH command on the Forsythe computer at Stanford University. If you do not use SPIRES at Stanford, contact your local system administrator to find out how SPIRES documents are made available there.

Updates to SPIRES Manuals

SPIRES manuals are updated regularly as changes are made to the system. This does not mean that all manuals are out of date with each new version of SPIRES. The changes to the documentation match those made to SPIRES: they are usually minor and/or transparent. Not having the most current version of a manual may mean you do not have all the most recent information about all the latest features, but the information you do have will usually be accurate.

A public subfile, SPIRES DOC NOTES, contains information about changes to SPIRES manuals. Using this subfile, you can determine whether the manual you have has been updated and if so, how significant those updates are. You need to know the date your manual was published, which is printed at the top of each page. For details on the procedure, issue the command SHOW SUBFILE DESCRIPTION SPIRES DOC NOTES.


INDEX


$AREA FUNCTION   4.3
$AREANAME VARIABLE   4.3
$CHANGED VARIABLE   5.6.2
$ECOL VARIABLE   5.6.3
$EROW VARIABLE   5.6.3
$EVENTZONE VARIABLE   3.6
$GETAREA FUNCTION   6.7
                    5.8.6
                    4.3
                    4
$GETAREA FUNCTION, AND ZONES   3.6
$HTML FUNCTION   7.7.7
$HTML, ENCODE AND DECODE OPTIONS   7.7.7
$HTML, MODE OPTION   7.7.7
$HTML, TEXT MODE OPTION   7.7.8
$HTML, TRANSLATE OPTION   7.7.7
$MSG PROC   5.6.3
            5.1.3
$NODATA VARIABLE   4.1.1.1
$OVERFLOW VARIABLE   5.8.2
$PUTAREA FUNCTION   4.4
                    4
$SCRNAREA VARIABLE   4.3
$SETAREA FUNCTION   4.5
                    4
$SETAREA FUNCTION, ATTRIBUTES FOR SPECIFIC TYPES OF FIELDS   6.1.0
$TERMPAD VARIABLE   6.9.4
                    5.3
$ZONEDEF FUNCTION   3.6
ACTIVE AREA   2.12
ACTIVE FILE   2.12
              1.1
ACTIVE FILE, ASSIGN   7.2
ALPHANUMERIC ATTRIBUTE   6.5
                         3.1
ALTCHAR ATTRIBUTE   6.3
                    3.1
ALTERNATE CHARACTER SETS   6.3
ALTERNATE CHARACTER SETS, FOR THE TEKTRONIX TERMINAL   6.10.3
APPLICATION, MESSAGES   5.5
AREA ATTRIBUTES   3
AREA ATTRIBUTES, COPYING   4.2
AREA DIMENSIONS   3.1
AREA FUNCTIONS   3.4
                 3.1.1
                 3
AREA FUNCTIONS, DEFAULT   3.3
AREA PLACEMENT   :A
                 3
AREA PLACEMENT, ALIGN BOTTOM   3.1
AREA PLACEMENT, ALIGN LEFT   3.1
AREA PLACEMENT, ALIGN RIGHT   3.1
AREA PLACEMENT, ALIGN TOP   3.1
AREA PLACEMENT, CENTER   3.1
AREA PLACEMENT, MIDDLE   3.1
AREA SIZE   3
AREAS   5.3
        5.1.3
        3
        1.1
AREAS, AND ZONES   3.6
AREAS, ATTRIBUTE ADJUSTMENTS   :A
AREAS, CHAINING   3.1.3
AREAS, CONTAINED   3.5
                   3.1
                   1.1
AREAS, CONTAINING   3.5
AREAS, COPYING   4.2
AREAS, DEFINING   5.5.1
                  3.2
                  3.1
AREAS, HIERARCHICAL   3.5
                      3.4
                      2
AREAS, INDEFINITE CAPACITY   :A
AREAS, NULL   :A
AREAS, OVERFLOW   4.8.1
                  3.1.3
AREAS, OVERLAPPING   7.1
                     5.5.1
                     3.5
AREAS, OVERLAYING   4.1
AREAS, PARTIALLY DEFINED   3.4
                           3.1.4
                           3.1.3
                           3.1
AREAS, PROTECTED   5.3
AREAS, REDEFINING   3.2
AREAS, REDEFINING DEFAULTS   3.1.1
AREAS, SIZE ADJUSTMENTS   :A
                          3.4
AREAS, STORING   4.10
AREAS, SYSTEM-DEFINED   2
                        1.1
AREAS, UNCONTAINED   3.1
                     2
                     1.1
AREAS, UNDEFINING   3.1
AREAS, USER-DEFINED   3
                      1.1
ASK AREA COMMAND   4.9
ASK COMMAND   5.5.1
ASK COMMAND, FOR FULL-SCREEN PROTOCOLS   4.9
ASK UPROC, DEFAULT AREA FOR   6.1a
ASSIGN AREA COMMAND   7.2
                      2.8
                      2.6
                      2.3
                      2.2
ATTN OPTION, FOR READ, WRITE, AND BLANK COMMANDS   4.7.1
ATTRIBUTES, FOR SPECIFIC TYPES OF FIELDS   6.1.0
AUTOTAB   6.6
BELL, RINGING TERMINAL   4.3
BGPROTECT ATTRIBUTE   3.1.2
                      3.1
BGUNPROTECT ATTRIBUTE   3.1.2
                        3.1
BLANK COMMAND   4.8.1
                4.6.3
                4
                1.1
BLANK COMMAND, ATTN OPTION   4.7.1
BLANK COMMAND, CURSOR OPTION   4.7.2
BLANK COMMAND, NULL OPTION   4.7.3
BLANK COMMAND, OPTIONS   4.7
BLANK COMMAND, READ OPTION   4.7.4
BLANK COMMAND, WITH NO AREA SPECIFIED   4.6.4
BLINKING ATTRIBUTE   6.2
BLUE ATTRIBUTE   6.3
BRIGHT ATTRIBUTE   6.2
C, SAMPLE HLI PROGRAM FOR   8.7
CLOSE AREA COMMAND   7.3
                     2.8
                     2.6
                     2.3
                     2.2
COBOL, SAMPLE HLI PROGRAM FOR, WITH DYNAM OPTION   8.4.2
COBOL, SAMPLE HLI PROGRAM FOR, WITH STATIC OPTION   8.4.1
COLOR   6.3
COMMAND FIELD   5.5.1
                5.5
                5.2.3
COMMAND LANGUAGE   5.5.2
COMMAND PARSING   5.6.1
                  5.5.2.2
                  5.5.2.1
                  5.5.1
                  5.4
COMMAND TYPE AREA   6.1a
CONTINUE OPTION   5.8.4
CRT AREA   2.13
           2.1
CURSOR OPTION, FOR READ, WRITE, AND BLANK COMMANDS   4.7.2
CURSOR POSITIONING, FROM KEYBOARD   5.1.1
CURSOR POSITIONING, HOME KEY   6.1a
CURSOR POSITIONING, WRITE COMMAND   4.7.2
CURSOR SELECT KEY   6.9.3
                    5.8.6
CYAN ATTRIBUTE   6.3
DASH COMMAND, WITH IN AREANAME PREFIX   4.1.2
DATA ATTRIBUTE   6.1.0
DATA SETS, OS   7.2
DATASETS   1
DEFAULT STATEMENT   5.7
                    5.3
DEFINE AREA COMMAND   3.1
DEFINE ZONE COMMAND   3.6
DESIGNATOR CHARACTERS, FOR THE IBM 3270 TERMINALS   6.9.3
DETECT ATTRIBUTE   6.8
                   5.8.6
                   3.1
DETECT ATTRIBUTE, FOR THE IBM 3270 TERMINALS   6.9.3
DEVICE SERVICES   1.1
DEVICES   1
DIRECT/BUFFER SWITCH, FOR THE TEKTRONIX TERMINAL   6.10.1
DIRECTION STATEMENT   4.1
DISPLAY ATTRIBUTES   6
DISPLAY ATTRIBUTES, SPECIFYING   6.1
DISPLAY ATTRIBUTES, TER AREA   6.1.5
DISPLAY COMMAND   5.8.3
DISPLAY STATEMENT   6.5
                    6.4
                    6.3
                    6.2
                    6.1.1
                    5.6.3
                    5.4
                    5.3
                    3.1.2
DISPLAY STATEMENT, ATTRIBUTES FOR SPECIFIC TYPES OF FIELDS   6.1.0
DISPLAY UPROCS   3.1.2
DOCUMENTATION, BIBLIOGRAPHY   :29
DUPLICATE AREA COMMAND   4.2
                         3.1.4
DUPLICATE OPTION   4.2
                   3.1
DUPLICATE OPTION, OF DEFINE AREA COMMAND   3.1.4
DUPLICATE OPTION, RESETTING   3.2
ELENGTH STATEMENT   6.1.4
                    5.1.3
EMPHASIS ATTRIBUTE   6.2
                     3.1
EMPHASIS LEVELS   6.2
EMPHASIS LEVELS, FOR THE IBM 3270 TERMINALS   6.9.1
EMPHASIS LEVELS, FOR THE TEKTRONIX TERMINAL   6.10.2
ENTER KEY   5.1.1
            5.1
ERRORS ATTRIBUTE   6.1.0
ESTART STATEMENT   5.6.3
                   5.1.3
                   3.1.2
FAC   5.1.3.0
FIELD ATTRIBUTE CHARACTER   5.1.3.0
FIELD ATTRIBUTES   3
FIELD PROTECTION   5.6.1
                   5.5.1
                   5.4
                   5.3
                   5.1.3
                   3.1.2
FIELDS   4.3.1
         5.2.3
         5.1.3
         3
         1.1
FIELDS, BACKGROUND   3
FIELDS, FOREGROUND   3.1.2
                     3
FIELDS, PLACING   5.1.3.0
FILE AREA   2.13
            7.1
            7
            2.2
FILE AREAS, DEFINING   7.1
FILE AREAS, FOR JOB SUBMISSION   7.6
FILE AREAS, READING   7.5
                      4.8.2
FILE AREAS, WRITING   7.4
FILE DEFINITION   5.1.2
FILE DEVICES   7
FILE DEVICES, INPUT   7.5
FILE DEVICES, OUTPUT   7.4
FILES   1
FILES, NON-SPIRES ORVYL   7.3
                          7.2
                          7
FILES, OS   7.2
FIL2 AREA   2.13
            2.3
FORMAT FRAMES   5.4
                5.3
                5.2.3
FORMATS   5.1.3
          5.1.2
          1.1
FRAME-DIM STATEMENT   5.1.3
FULL-SCREEN PROGRAMMING   5.1
FULL-SCREEN PROGRAMMING, APPLICATION DESIGN   5.2
FULL-SCREEN PROGRAMMING, APPLICATION-SPECIFIC FUNCTIONS   5.2.2
FULL-SCREEN PROGRAMMING, AREAS AND FORMATS   5.1.3
FULL-SCREEN PROGRAMMING, COMMAND FIELD   5.5.2
                                         5.4
                                         5.2.2
FULL-SCREEN PROGRAMMING, COMMAND LANGUAGE   5.4
                                            5.2.2
FULL-SCREEN PROGRAMMING, COMMAND PARSING   5.5.2
FULL-SCREEN PROGRAMMING, ERROR HANDLING   5.8.5
                                          5.8.1
                                          5.7
                                          5.6.3
                                          5.6
FULL-SCREEN PROGRAMMING, ERROR HANDLING, MULTIPLY OCCURRING ELEMENTS   5.8.8
FULL-SCREEN PROGRAMMING, ERROR MESSAGES   5.6.3
FULL-SCREEN PROGRAMMING, EXPLAIN FACILITIES   5.8.7
FULL-SCREEN PROGRAMMING, HELP FACILITIES   5.8.7
FULL-SCREEN PROGRAMMING, INCLOSE RULES   5.8.1
FULL-SCREEN PROGRAMMING, MERGE COMMAND   5.6
FULL-SCREEN PROGRAMMING, MULTI-RECORD SCREEN DISPLAY   5.8.4
FULL-SCREEN PROGRAMMING, MULTI-RECORD SCREEN UPDATING   5.8.5
FULL-SCREEN PROGRAMMING, MULTI-SCREEN RECORD DISPLAY   5.8.2
FULL-SCREEN PROGRAMMING, MULTI-SCREEN RECORD UPDATING   5.8.3
FULL-SCREEN PROGRAMMING, RECORD ADDING   5.8.1
                                         5.7
                                         5.6
FULL-SCREEN PROGRAMMING, RECORD DISPLAY   5.8.4
                                          5.8.2
                                          5.7
                                          5.6.1
                                          5.3
FULL-SCREEN PROGRAMMING, RECORD INPUT   5.6.2
FULL-SCREEN PROGRAMMING, RECORD UPDATING   5.8.5
                                           5.8.3
                                           5.8.1
                                           5.6.1
                                           5.6
FULL-SCREEN PROGRAMMING, SCREEN DESIGN   5.2.3
FULL-SCREEN PROGRAMMING, UPDATE COMMAND   5.6
FULL-SCREEN TERMINALS   2.1
FUNCTION KEYS   6.7
GENERATE REFERENCE COMMAND   5.8.3
GETDATA STATEMENT   5.7
                    5.6.2
GETELEM STATEMENT   5.3
GREEN ATTRIBUTE   6.3
HIDE ATTRIBUTE   6.2
HLCA AREA   2.13
            8.2.3
            2.5
HLI   8
HLI AREAS, READING   8.2.3
HLI AREAS, WRITING   8.2.3
HLI, COMMAND PASSING   8.2.2
HLI, DATA TRANSFER   8.2.3
HLI, DEBUGGING AID   8.2.5
HLI, ERROR MESSAGES   8.3
HLI, JCL FOR   8.2
HLI, PRINT OUTPUT   8.2.4
HLI, RESPONSE BUFFER   8.2.1
HLI, SPIRES CALL   8.2.2
HLI, SPISET CALL   8.2.1
HLI, SPIXIT CALL   8.2.6
HLI, USE OF FROM C   8.7
HLI, USE OF FROM COBOL, WITH DYNAM OPTION   8.4.2
HLI, USE OF FROM COBOL, WITH STATIC OPTION   8.4.1
HLI, USE OF FROM PL/I, MULTIPLE PATH   8.5.2
HLI, USE OF FROM PL/1, SINGLE PATH   8.5.1
HLI, USE OF FROM PL360   8.6
HLIO AREA   2.13
            8.2.3
            2.4
HOME CURSOR POSITION   6.1a
HOST LANGUAGE INTERFACE   8
                          2.5
                          2.4
                          1
HTML AREA   2.13
            2.6
HTML AREA, DEFINING   7.7
HTML COLOR ATTRIBUTES   7.7.3
HTML DISPLAY ATTRIBUTES   7.7.1
HTML RECOMMENDATIONS   7.7.11
HTML STYLE ATTRIBUTES   7.7.9
HTML, $HTML FUNCTION   7.7.7
HTML, ALT ATTRIBUTE   7.7.5
HTML, CENTER ATTRIBUTE   7.7.2
HTML, HN ATTRIBUTES   7.7.2
HTML, HREF ATTRIBUTE   7.7.4
HTML, IMG ATTRIBUTE   7.7.5
HTML, MAILTO ATTRIBUTE   7.7.4
HTML, NAME ATTRIBUTE   7.7.4
HTML, NBSP ATTRIBUTE   7.7.2
HTML, RAW ATTRIBUTE   7.7.6
HTML, TAG ATTRIBUTE   7.7.4
HTML, UNDERLINE ATTRIBUTE   7.7.2
HTML, WRAP ATTRIBUTE   7.7.2
HTML, XN ATTRIBUTES   7.7.10
IBM 3270 TERMINALS   6.9
IDATA FUNCTION   3.1.1
                 3.1
IDATA FUNCTION, DEFAULT AREA   3.3
IDATA, DEFAULT AREA   4.1
IN ACTIVE PREFIX, WITH DEVICE SERVICES   2.12
IN AREANAME PREFIX   :B
                     5.1.3
                     4.1
                     4
                     3.3
                     1.1
IN-AREA STATEMENT, AND DEVICE SERVICES AREAS   4.11
INDEFINITE ROW CAPACITY   3.1
INOUT FRAMES   5.8.8
INPUT CAPABILITY   3.1.1
INPUT FORMAT FRAME   5.6.3
                     5.5.1
                     5.4
INVALID ASSIGN MESSAGE   7.2
IODATA FUNCTION   3.1.1
                  3.1
JOB OPTION, ASSIGN AREA COMMAND   7.6
KEYPAD, VT100-TYPE TERMINALS   6.7.1
LABEL GROUPS   5.6.3
               5.4
               5.3
               5.2.3
               5.1.3
LENGTH STATEMENT   5.6.2
                   5.3
                   5.1.3
LIGHT-PEN DETECTION   6.9.3
                      5.8.6
LOOP STATEMENT   5.6.2
                 5.3
MARGINS STATEMENT   5.6.2
MAXROWS STATEMENT   5.6.2
MEM AREA   2.13
           2.7
MEMORY WORKSPACE   2.7
                   1
MENU-DRIVEN APPLICATIONS   5.8.6
MERGE COMMAND   5.8.5
                5.8.3
MODEL TERMINAL   6
MSG AREAS   5.1.3
            4.8.1
            3.1.1
MSG FUNCTION   3.1.1
               3.1
MSG FUNCTION, DEFAULT AREA   3.3
MSG PROC   5.1.3
NIO AREA   2.13
           2.8
NIO AREA, DEFINING   7.8
NOCOLOR ATTRIBUTE   6.3
NODATA FUNCTION   3.1.1
                  3.1
NODATA OPTION   5.7
NODATA OPTION, USING FRAME PREFIX   4.1.1.1
NODETECT ATTRIBUTE   6.8
                     3.1
NOEMPHASIS ATTRIBUTE   6.2
                       3.1
NOMSG FUNCTION   3.1.1
                 3.1
NOUNDERLINE ATTRIBUTE   6.4
                        3.1
NOWRITE   5.5.1
NOWRITE, GLOBAL   4.8
                  3.3
NOWRITE, LOCAL   4.8
                 3.3
NULL AREA   2.13
            3.1.4
            3.1.3
            2.9
NULL OPTION, FOR READ, WRITE, AND BLANK COMMANDS   4.7.3
NULL, DUPLICATE TO   3.1.4
NULL, OVERFLOW TO   3.1.3
NUMERIC ATTRIBUTE   6.5
                    3.1
NUMERIC FIELD EDITING   6.5
NUMERIC FIELD EDITING, FOR THE IBM 3270 TERMINALS   6.9.2
NUMERIC FIELD EDITING, FOR THE TEKTRONIX TERMINAL   6.10.4
ODATA FUNCTION   3.1.1
                 3.1
ODATA FUNCTION, DEFAULT AREA   3.3
ODATA, DEFAULT AREA   4.1
OPTIONAL ATTRIBUTE   6.1.0
OS DATA SETS   7.2
OUTPUT CAPABILITY   3.1.1
OUTPUT FORMAT FRAME   5.7
                      5.6.1
                      5.5.2
OVERFLOW OPTION   3.1
OVERFLOW OPTION, OF DEFINE AREA COMMAND   3.1.3
OVERFLOW OPTION, RESETTING   3.2
OVERLAY OPTION   5.8.4
PAD CHARACTER   6.9.4
PAD CHARACTER, USE IN FULL-SCREEN FORMATS   5.3
PADCHAR STATEMENT   6.9.4
PARTIAL RECORD PROCESSING   5.8.3
PINK ATTRIBUTE   6.3
PL/I, SAMPLE HLI PROGRAM FOR, MULTIPLE PATH   8.5.2
PL/1, SAMPLE HLI PROGRAM FOR, SINGLE PATH   8.5.1
PL360, SAMPLE HLI PROGRAM FOR   8.6
PROTECT ATTRIBUTE   3.1.2
                    3.1
PROTOCOLS   5.5.2
            5.5.1
            5.5
            5.1.2
PTDETECT ATTRIBUTE   6.8
                     3.1
PTNUMERIC ATTRIBUTE   6.5
                      3.1
PTPROTECT ATTRIBUTE   3.1.2
PTUNDERLINE ATTRIBUTE   6.4
                        3.1
PTUNPROTECT ATTRIBUTE   3.1.2
PUTDATA STATEMENT   5.8.2
                    5.3
PUTELEM STATEMENT   5.6.2
READ COMMAND   5.5.1
               4.8.2
               4.6.2
               4
               1.1
READ COMMAND, ATTN OPTION   4.7.1
READ COMMAND, CURSOR OPTION   4.7.2
READ COMMAND, IMPLICIT   4.8.2
READ COMMAND, NULL OPTION   4.7.3
READ COMMAND, OPTIONS   4.7
READ COMMAND, WITH NO AREA SPECIFIED   4.6.4
READ OPTION, FOR WRITE AND BLANK COMMANDS   4.7.4
RECORD DISPLAY   5.2.3
RECORD UPDATING   5.3
RED ATTRIBUTE   6.3
REDEFINE AREA COMMAND   3.2
                        3.1
REFERENCE COMMAND   5.8.3
REMELEM STATEMENT   5.6.2
REPORT FORMATS, AND DEVICE SERVICES AREAS   4.1.3
REPROMPT OPTION, FOR WRITE COMMAND   5.8.1
                                     4.7.5
REPROMPT UPROC   5.7
                 5.6.3
                 4.7.5
REQUIRED ATTRIBUTE   6.1.0
RESTORE AREA COMMAND   4.10.3
RETURN KEY   5.5.2
             5.4
             5.1.1
REVERSE ATTRIBUTE   6.2
RULING ATTRIBUTE   6.3.1
RULING FONT   6.3
              5.1
RULING FONT CHARACTER SET   6.3.1
RULING FONT CHARACTER SET AND COLOR   6.3
SBF AREA   2.13
SBF DEVICE AREA   2.10
SCREEN ATTRIBUTES   6
SET AREA COMMAND   3.3
                   3.1.1
SET AREA NULL COMMAND   3.3
SET AUTOTAB UPROC   6.6
SET CRT COMMAND   6.1a
SET CRT MODE COMMAND   6.1a
SET DISPLAY UPROC   6.4
                    6.3
                    6.2
                    6.1.2
SET DISPLAY UPROC, ATTRIBUTES FOR SPECIFIC TYPES OF FIELDS   6.1.0
SET EDISPLAY UPROC   6.4
                     6.3
                     6.2
                     6.1.4
SET EDISPLAY UPROC, ATTRIBUTES FOR SPECIFIC TYPES OF FIELDS   6.1.0
SET ELENGTH UPROC   6.1.4
SET NOREAD COMMAND   4.8
SET NOWRITE COMMAND   4.8
SET PADCHAR UPROC   6.9.4
                    5.6.2
                    5.6.1
SET PADCHAR UPROC, USE IN FULL-SCREEN FORMATS   5.3
SET PATH ECHO COMMAND   8.2.5
SET PROTECT|UNPROTECT UPROC   5.3
                              3.1.2
SET READ COMMAND   4.8
SET REMOVEL UPROC   5.6.2
SET SKIPEL UPROC   5.7
SET TDISPLAY UPROC   6.4
                     6.3
                     6.2
                     6.1.3
SET TDISPLAY UPROC, ATTRIBUTES FOR SPECIFIC TYPES OF FIELDS   6.1.0
SET TERMINAL COMMAND   6
SET UCODE UPROC   5.6.3
                  5.1.3
SET WIDTH COMMAND   2.11
SET WRITE COMMAND   4.8
SHOW AREA COMMAND   3.4
SHOW CRT COMMAND   6.1a
SHOW DATS COMMAND   3.7
SHOW FIELDS COMMAND   4.3.1
SHOW STORED AREAS COMMAND   4.10.2
SHOW ZONES COMMAND   3.6
STAR COMMAND, WITH IN AREANAME PREFIX   4.1.2
START STATEMENT   5.6.2
                  5.3
                  5.1.3
                  3.1.2
STORE AREA COMMAND   4.10.1
SYSTEM MESSAGES   3.3
TAB KEY   5.7
          5.1.1
TEKTRONIX TERMINAL   6.10
TER AREA   2.13
           2.11
TER AREA, DISPLAY ATTRIBUTES   6.1.5
TERMINAL SCREENS   5.2.3
TERMINAL TYPES   6
TERMINALS   1
TERMINALS, FULL-SCREEN   5.1.1
                         5.1
                         1.1
                         1
TERMINALS, LINE-BY-LINE   2.11
                          1.1
                          1
TEXT ATTRIBUTE   6.1.0
THROWAWAY DATA   2.9
                 1
TITLE ATTRIBUTE   6.1.0
TITLE STATEMENT   5.7
                  5.3
                  5.1.3
                  3.1.2
TSTART STATEMENT   5.3
                   5.1.3
                   3.1.2
UNDERLINE ATTRIBUTE   6.4
                      3.1
UNPROCESSED DATA STREAM   1
UPDATE COMMAND   5.8.3
USAGE STATEMENT   5.7
                  5.6
USING FRAME PREFIX, WITH IN AREANAME PREFIX   4.1.1
VALUE STATEMENT   5.3
VARIABLES   5.5
            5.4
            5.1.2
VGROUP   5.1.2
WAIT INDICATOR   6.1a
WARNING ATTRIBUTE   6.1.0
WHITE ATTRIBUTE   6.3
WRITE COMMAND   5.6.3
                5.5.2
                5.5.1
                4.8.1
                4.6.1
                4
                1.1
WRITE COMMAND, ATTN OPTION   4.7.1
WRITE COMMAND, CURSOR OPTION   4.7.2
WRITE COMMAND, IMPLICIT   4.8.1
WRITE COMMAND, NULL OPTION   4.7.3
WRITE COMMAND, OPTIONS   4.7
WRITE COMMAND, READ OPTION   4.7.4
WRITE COMMAND, REPROMPT OPTION   4.7.5
WRITE COMMAND, WITH NO AREA SPECIFIED   4.6.4
XEQ FRAME COMMAND   5.5.2
XEQ FRAME COMMAND, WITH IN AREANAME PREFIX   4.1.1
XESTART STATEMENT   5.8.8
YELLOW ATTRIBUTE   6.3
ZENTEC TERMINAL   6.11
ZONES, DEFINING   3.6