******************************************************************
* *
* 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
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:
SPIRES Formats SPIRES Protocols
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.
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.
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.
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.
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.
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';
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.
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.]
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:
DEFINE AREA SCREEN (0,0) ON CRT (1,1) BGPROTECT
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.
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.]
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.]
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.]
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.
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.]
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.]
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.]
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:
-> for stack -> in null show keys last
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.
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.]
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.
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.
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 | | +---------------------------------------------------------------------------+
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.
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:
DEFINE AREA A(5,79) ON CRT DEFINE AREA B(15,79) ON CRT(6,1) DEFINE AREA C(10,30) ON B(5,49)
0 10 20 30 40 50 60 70 80
+------------------------------+
| A |
5 |------------------------------|
| |
10 | +-----------|
| B | |
15 | | C |
| | |
20 |------------------------------|
| |
+------------------------------+
Or, as another example:
DEFINE AREA A (20,60) ON CRT (1,1) DEFINE AREA B (10,40) ON A (CE,R) DEFINE AREA C (5,10) ON B (MIDDLE,MIDDLE)
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.
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).
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.
Several Uprocs exist that can be placed in a format to affect field protection. They are:
UPROC = SET {PROTECT|UNPROTECT}
UPROC = SET DISPLAY = {PROTECT|UNPROTECT}
UPROC = SET TDISPLAY = {PROTECT|UNPROTECT}
UPROC = SET EDISPLAY = {PROTECT|UNPROTECT}
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.]
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:
OVERFLOW [TO] {NULL|areaname3}
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.
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:
DUPLICATE [TO] {NULL|areaname3}
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.
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.
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:
SET AREA areaname [FUNCTION DEFAULTS] functions
"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
-> set area crt odata
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:
-> define area errors (4,79) on crt (20,1) msg -> in errors set nowrite -> set area errors msg
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.]
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:
SET AREA NULL {NODATA|NOMSG}
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.
The SHOW AREA command lists the hierarchy, definitions, and available functions of all areas that have been defined. The syntax is:
SHOW AREAS [areaname] [NAMES]
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:
DEFINE AREA areaname1 (#lines,#cols) ON areaname2 (sline,scol)
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:
DEFINE AREA HELP (0,0) ON CRT (29,1) PROTECT, IODATA, MSG; Null
If an area defined on a FILE area has been assigned to a physical file, this will be indicated as follows:
DEFINE AREA RECORD (5,80) ON FILE (1,1) IDATA, NOMSG; Assigned
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,
DEFINE AREA SYSMSG (5,60) ON CRT (1,1) IODATA, MSG; M
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.
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:
DEFINE AREA A (24,79) ON CRT (1,1) DEFINE AREA B (15,60) ON CRT (10,1) DEFINE AREA C (10,50) ON CRT (15,1)
or
DEFINE AREA A (24,79) ON CRT (1,1) DEFINE AREA B (15,60) ON A (10,1) DEFINE AREA C (10,50) ON B (5,1)
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.
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.]
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:
$ZONEDEF(areaname, zonename, row, column, height, width)
and the syntax of the DEFINE ZONE command is:
DEFINE ZONE zonename (height, width) ON areaname (row, column)
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:
UPROC = Eval $ZONEDEF(Input.Screen,Student.Name,3,1,1,50);
or
DEFINE ZONE Student.Name(1,50) ON Input.Screen(3,1)
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.
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.
[IN areaname1] SHOW ZONES [ON areaname2]
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:
> show zones DEFINE ZONE MEALZONE (1,15) ON GUIDED.INPUT (1,52) DEFINE ZONE $CHOICE (1,1) ON SUBAREA1 (1,1)
Here, MEALZONE was defined by the Prism application, but $CHOICE was defined by Prism itself.
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.]
The SHOW DATS command is only used by systems programmers to examine a Device ATtributeS chain for areas like CRT.
SHOW DATS FOR <areaname>
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.
The "IN areaname" prefix is used when writing data to an area, or reading data from an area. The syntax is:
IN areaname [options] command
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:
DEFINE AREA ONE (3,79) ON CRT (1,1) DEFINE AREA TWO (20,35) ON CRT (4,1) DEFINE AREA THREE (20,35) ON CRT (4,40) DEFINE AREA FOUR (1,79) ON CRT (24,1)
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.
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:
DEFINE AREA ONE (5,79) ON CRT (1,1) DEFINE AREA TWO (10,79) ON CRT (1,1)
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:
FRAME-ID=FRAME.ONE; LABEL; GETELEM=A; START=1,1; PUTDATA;
LABEL; GETELEM=B; START=2,1; PUTDATA;
FRAME-ID=FRAME.TWO; LABEL; GETELEM=C; START=6,10; PUTDATA;
LABEL; GETELEM=D; START=8,10; PUTDATA;
Assuming that SET NOWRITE [See 4.8.] is in effect, if we issue the commands
IN ONE, USING FRAME.ONE, DISPLAY KEY1 IN TWO, USING FRAME.TWO, DISPLAY KEY2 WRITE CRT
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:
IN TWO, USING FRAME.TWO, DISPLAY KEY2 IN ONE, USING FRAME.ONE, DISPLAY KEY1 WRITE CRT
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.
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:
IN SCREEN, USING OUT, DISPLAY 123
This is interpreted as: USING the OUT frame, place data INside the SCREEN area by displaying record 123.
IN SCREEN, USING INP, MERGE 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,
IN SCREEN, XEQ FRAME INPUTTER
will invoke the frame INPUTTER to process the data in the SCREEN area.
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.
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.
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.]
The DUPLICATE AREA command allows the same data to be copied from one area to another. The syntax is:
[IN dest-area] DUPLICATE [AREA] source-area [ALL]
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.
The $GETAREA function provides status information and data from device services areas. The syntax is:
$GETAREA(areaname[,code,n1,n2,n3])
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:
Value Returned Key Pressed
0 ENTER key or RETURN key
130 BREAK key
131 WRAP field, or Trigger field
160 TEST REQUEST key
161 CLEAR key
162 Immediately detectable field
163 Clear partition
166 Data from card reader
167 Magnetic card reader
168 Inbound structured fields
169 No action (printer)
170 No action (operator)
171 PA1 key
172 PA2 key
173 PA3 key
200 - 255 PF key 0 - PF key 55
In the following examples of $GETAREA, "x" can be one of these four codes:
"U" - for unprotected, non-expandable fields "X" - for expandable fields "P" - for protected fields "A" - for all fields, including background fields
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:
-> set nowrite -> define area x (50,100) on mem (4,11) -> sel addresses -> display 100 Helen Ease 145 Hint Street Paduka, IL 23456 -> in x dis 100 -> let area = $getarea(x,area) -> let srow = $getarea(x,srow) -> let scol = $getarea(x,scol) -> let rows = $getarea(x,rows) -> let cols = $getarea(x,cols) -> / * AREA X: (#rows,#cols) ON #area (#srow,#scol) * AREA X: (50,100) ON MEM (4,11) -> let read = $getarea(x,read,1,1,30) -> show eval #read Helen Ease -> let read = $getarea(x,read,3,13,30) -> show eval #read 23456 ->
The command SHOW FIELDS will display basic information about all the fields in an area:
[IN area] SHOW FIELDS [FOR 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.
-> sho fields in guided.data
Fields for area GUIDED.DATA
Num Row Col Len Characteristics/Value
--- --- --- --- ---------------------
1. 1 1 79 Protect
2. 2 1 7 Protect
3. 2 8 29 Protect, Cyan
"Layout Name Description"
4. 2 37 43 Protect
5. 3 1 7 Protect
6. 3 8 12 Unprotect, Yellow, Underline, Autotab
"Unnamed"
7. 3 20 6 Protect
8. 3 26 48 Unprotect, Green, Underline, Autotab
9. 3 74 6 Protect
10. 4 1 79 Protect
11. 5 1 3 Protect
12. 5 4 1 Unprotect, Yellow, Underline, Autotab, Wrap
"1"
13. 5 5 1 Protect
14. 5 6 68 Protect, Cyan
"<-- Choose how you want fields to be displayed in
your report (1-2)."
15. 5 74 6 Protect
16. 6 1 9 Protect
17. 6 10 2 Protect, White
"1."
18. 6 12 1 Protect
19. 6 13 61 Protect, Reverse, Yellow
"ACROSS: Fields next to each other in columns across
the page."
20. 6 74 6 Protect
21. 7 1 9 Protect
22. 7 10 2 Protect, White
"2."
23. 7 12 1 Protect
24. 7 13 52 Protect, White
"DOWN: Fields under each other in rows down the page."
(etc.)
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:
$PUTAREA(areaname,string,row,column)
"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.
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:
$SETAREA(areaname,fieldnumber,string1,string2,...stringn)
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:
ALTCHAR=n An or altchar-terms EMPHASIS=n En or emphasis-terms field-term AUTOTAB AU EXPANDABLE EXP DETECT D NUMERIC NU PROTECT P TRIGGERS TRI UNPROTECT U UNDERLINE UND
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
$SETAREA(areaname,fieldnumber,PROTECT,#X,DETECT)
would be equivalent to
$SETAREA(areaname,fieldnumber,PROTECT,A3,E16,UND,DETECT)
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.]
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.]
The WRITE command is used to write data from an area to a device. The syntax is:
WRITE areaname [options]
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.
The READ command will move data from a device (a terminal screen or disk file, for example) into an area. Its syntax is:
READ areaname [options]
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.
The BLANK command will clear all data from an area or a device. The syntax is:
BLANK areaname [EXTERNAL|INTERNAL|UNPROTECTED] [options]
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.
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,
READ, CURSOR (2,5) WRITE, ATTN = '* ATTN key pressed' BLANK
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.
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.
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.
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)
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.
The WRITE and BLANK commands may also be followed with a READ option. The syntax for this combination is:
{WRITE|BLANK} areaname [options] READ [options]
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.
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 REPR