![]() | ||
VISUALPQL | ![]() ![]() ![]() ![]() ![]() ![]() ![]() | Execution Window |
When using the execution window, data can be read either as individual keystrokes or multiple data fields can be entered with control returning to the program under particular circumstances.
The execution window is automatically created when a program that requires it is executed. A flag is set during compilation if any full screen commands are found and this flag is stored with the executable program. The execution window is removed at the end of the command stream, which could include many programs and utility commands, or when an explicit SCREEN OFF
command is found. The WRITE
command (see Reading and
Writing.) sends output to the scrolled output window not the execution window.
The NREAD
and SREAD
functions and the interactive READ
command, pop up a box for data entry which is independent of the execution window.
Execution window commands control both the placement of elements in the window and the appearance of the displayed elements. Elements are placed in the window using a screen rows and columns. References to screen locations are by a row and column coordinate system, where the row number is the first reference and the column number is the second reference. Row 1 is the top row of the screen. Column 1 is the leftmost position on the screen. The bottom right coordinate is 30 , 80.
Some commands create two dimensional displays such as a box. These commands require two coordinates, a top left and bottom right coordinate. The second coordinate must be greater than (or equal to) the first coordinate. References to rows and columns may be numeric constants, names of numeric variables and array references. These references are in the form:
The visual treatment of any display element is specified with the
The video value is a 23 bit number, where each bit represents one attribute (e.g. a colour, underline, inverse, etc.) that can be turned on or off. By turning several bits on, a combination of attributes can be specified. For example, by turning on both the underline bit and the inverse bit, the display would be underlined in inverse.
Some bits are reserved for future use and several have been set aside for user definition. The currently assigned bits and their functions are:
Combinations of "primary" colours produce other colours. Red and blue produce magenta, red and green produce yellow and blue and green produce cyan.
When any foreground/background setting is ON, then the other foreground/background settings come into effect. The default background is white but bits 12,13,14 all off correspond to black. Thus just turning on any of bits 8,9,10 r 11 gives a black background. To have a white background in combination with some foreground settings, turn on bits 12,13 and 14. To have a grey background, turn on bits 12,13,14 and 16.
Internally each key is identified by a numeric value in the range 1-512. This
value is returned by VisualPQL commands such as
row1 , col1 , row2 , col2
Video Attributes
The appearance (colours, inverse, underline, etc.) of display elements are defined in
terms of video attributes.VIDEO
option . The syntax of the VIDEO
clause on all commands is :command .... VIDEO video_value
The video value is a numeric value which may be a numeric constant, a variable name or an array reference. If no VIDEO
clause is specified, the default video value 0 is used which is black on white.
Bit Value Attribute 1 +2 Blue 2 +4 Inverse 4 +16 Underline 5 +32 Dim foreground 6 +64 Dim background 8 +256 Blue foreground 9 +512 Green foreground 10 +1024 Red foreground 11 +2048 Bright foreground 12 +4096 blue background 13 +8192 Green background 14 +16384 Red background 16 +65536 Dim background
COMPUTE VIDEOVAL = (2 ** 8) + (2 ** 13)
Keys and Application Programs
An execution window program may need to reacts to the keys that users press. The program must know which key was pressed and then execute the appropriate part of the program. The VisualPQL commands that accept interactive function keys, refer to these by a key value.
SIR Key Values
The values of the standard keys (letters, numbers, etc.) plus the 33 standard
ASCII keys plus any defined Logical Function Keys are available.ACCEPT CHARACTER
.
The following VisualPQL program displays the key value of a key as it is pressed and
may be useful when developing applications. Note that the carriage return key
(key value 305) terminates the program:(ctrl-E)
is 5.LFK
number
plus 256). SIR uses a numbered Logical Function Key (LFK) to identify
each special function performed under user control. For example, logical
function 1 goes up a line and is usually associated with the up arrow key. Physical keys
are mapped to a logical function number through a key map file. This is only of relevance
when the execution window is being used. If the file does not exist and is required, the
system will initiate a program to request basic keymapping information. Use the Settings -
Keymap option to alter these settings. Note that there are some physical keys
which the operating system intercepts and which cannot be used by SIR2002.PROGRAM
INTEGER*2 KEYVAL
ERASE SCREEN
LOOP
. ACCEPT CHARACTER KEYVAL AT 10,10
. DISPLAY TEXT [FORMAT(KEYVAL,3)] AT 10,15
. IF(KEYVAL = 305) EXIT LOOP
END LOOP
END PROGRAM
ASCII standard character values are:
Character Set Decimal Range Control characters 0 - 31 blank ! " # $ % & ' ( ) * + , - . / 32 - 47 Numbers 0 -9 48 - 57 : ; < = > ? @ 58 - 64 Upper case letters A - Z 65 - 90 [ \ ] ^ _ ` 91 - 96 Lower case letters a - z 97 - 122 { | } ~ 123 - 126 backspace 127
AT
| Specifies the screen location where either the prompt, if one is specified, or the input cursor is positioned. |
PROMPT
| Specifies the prompt to display. There is no default prompt. |
VIDEO
| Specifies the video treatment of the prompt. |
ECHO
| Specify either 0 or 1. 0 turns echo off, 1 turns echo on. The default is 0. Echo on means that the input key character is displayed on the screen. The echoed value is the marked value of the key. Non-printing keys such as arrows, control keys or the backspace key are not echoed. |
TIMEOUT
| The numeric value is a positive integer and specifies The number of tenths of seconds to wait for a keypress. If the user does not press a key within the specified time, the program moves on to the next command and sets the specified variable to the value 30002. |
Makes a sound. The higher the number, the longer the sound.
BELL
BELL num_value
AT | OVER
|
AT draws the box at the specified location,
overwriting any previously displayed line characters. OVER
draws the box at the specified location, using appropriate line
intersection characters wherever two lines intersect.
|
VIDEO
|
Specifies the video treatment
of the box.
Use the FILL command
to fill the inside of the box.
|
CHARACTER
| Specifies an alternate character with which to draw the box. Specify a single character in quotes. |
PROGRAM . BOX AT 5,20,15,60 | draw one box . BOX OVER 10,30,20,70 | draw overlapping box . WAIT 30 | wait 3 seconds END PROGRAM
Turns the cursor on or off depending on the keyword. One of the keywords must
be specified.
The cursor is only displayed during read operations such as
CURSOR
CURSOR ON | OFF
ACCEPT
CHARACTER
and FIELD INPUT
commands. Turn the
cursor back on before ending any procedure, as it may be left off accidentally.
AT
| Specifies the coordinates at which the first character of the text is displayed. This is required. |
VIDEO
| Specifies the video treatment of the displayed text. |
PROGRAM . STRING *8 STR1 . INTEGER*4 INT1 . DATE DAT1 ('DD/MM/YY') . COMPUTE STR1 = 'String'; INT1 = 1; DAT1 = '01/01/93' . DISPLAY TEXT 'No video attribute' AT 10 25 . DISPLAY TEXT STR1 AT 11 25 VIDEO 2 | bold . DISPLAY TEXT INT1 AT 12,25 VIDEO 4 | inverse . DISPLAY TEXT DAT1 AT 13,25 VIDEO 22 | Bold/inverse/underline . WAIT 30 END PROGRAM
Clears the screen. The cursor
position is not affected.
ERASE SCREEN
ERASE SCREEN
AT
| Specifies the screen location of the beginning of the input field. |
WIDTH
| Specifies the display width of the field and the maximum length of the input string (max_input_length). If the maximum length is greater than the display width, then the field is scrolled horizontally as the cursor attempts to move past either end of the input area. |
ARROWS
| Specifies the key values that move the cursor one character to the right or to the left. By default, these are 259 and 260. (The Right Arrow and Left Arrow keys.) |
AUTOTAB
|
Specifies that input terminates when the maximum input length is
reached. Without AUTOTAB , the user must specifically
terminate input.
|
BACKSPACE
| Specifies the key value that deletes the character to the left of the cursor. This default is 304. |
DEFAULT
|
Specifies the variable or string constant that is displayed in the
input field area upon entering the FIELD INPUT command. This
string may then be edited by the user. If using a variable, it may be the same
as the first parameter on the command.
|
DELETE
| Specifies the key value that deletes the character where the cursor is positioned. The default is 276. |
EDITMODE
|
Alternative method of specifying INSERT | OVERSTRIKE
option. Specify a numeric integer variable or constant. 0 equates to
INSERT , 1 equates to OVERSTRIKE .
|
EDITSIDE
|
Alternative method of specifying LEFT | RIGHT
option. Specify a numeric integer variable or constant. 0 equates to
RIGHT , 1 equates to LEFT .
|
HELP
|
Specifies a help page that is displayed if the user presses
(Help) while positioned on this
field. The page must be in html format in the help directory. The page name can
contain directory names using forward slashes to delimit. Enclose the
name in quotes. The system will convert this to a file name prefixed with a path
pointing to the help directory and suffixed with the file
extension .htm .
|
INSERT | OVERSTRIKE
|
INSERT (the default) specifies that characters are
inserted at the cursor location. OVERSTRIKE specifies that
input characters overwrite existing characters.
|
LEFT | RIGHT
|
LEFT specifies that characters are entered starting
at the leftmost column of the field and moving to the right.
RIGHT specifies that characters are entered starting
at the rightmost column of the field and moving to the left. If using a
language which requires entry of text from right to left, specify, RIGHT,
OVERSTRIKE and optionally set ARROWS (304,260).
LEFT is the default.
|
POSITION
| Performs two functions. When the command is executed, it specifies the position within the field to place the cursor. If the value is undefined or 0, the cursor is placed at field position 1. After input is terminated, it contains the position within the field where the cursor was located when the terminator key was pressed. |
TABMODE
|
Alternative method of specifying AUTOTAB option.
Specify a numeric integer variable or constant.0 equates to NOAUTOTAB , 1 equates to AUTOTAB .
|
TERMINATOR
|
Specifies a variable that receives the key value that terminated
input processing. It optionally specifies a list of key values that terminate
input processing. The list of key values may be constants or numeric variables
within parentheses. A maximum of 16 terminator values may be specified in the
list. If a terminator list is specified, only those referenced in the list
terminate input. Other control or function key characters sound a warning. If
no list is specified, then any special key not used for editing causes
termination of input.
If the termination is caused by an |
TIMEOUT
|
Specifies the amount of time to wait for the user's input, in tenths
of a second. Zero (the default) puts no time limit on the user. If the user
does not enter a value in the specified amount of time, and a variable is
specified on the TERMINATOR , it is set to the "time out"
character value which is 30002 and execution continues.
|
VIDEO
| Specifies the video treatment of the input field. |
FIELD INPUT TEXTLINE at 11 , 40 width 20 , 20 video 4
VIDEO
| Specifies the video treatment of the fill character. |
CHARACTER
| Specifies a single character to fill the area. Specify either a string variable or a single character string constant. The default character is the blank (' '). |
PROGRAM . COMPUTE BLUONYEL = 2**2 + 2**8 + 2**13 + 2**14 . BOX AT 5 20 15 60 VIDEO BLUONYEL . FILL 6 21 14 59 CHARACTER '*' VIDEO BLUONYEL . WAIT 50 END PROGRAM
AT
| Specifies the coordinates at which the first line character in the list is placed. This is required. |
VIDEO
| Specifies the video treatment of the line characters. |
ARROWS
| Specifies the character values for arrow key movement. By default, arrow key movement for vertical menus is defined as the down Arrow and up Arrow keys (key values 258 and 257), and arrow key movement for horizontal menus is defined as the left Arrow and right Arrow keys (key values 260 and 259). |
BOX
|
Draws a box at the specified coordinates with the specified video attribute. Row1 and col1 specify the upper left corner of the box, and row2 and col2 specify the lower right corner of the box. The boxtype specifies which line drawing characters to use when the current box overlaps another box; a boxtype of 1 causes intersections of one box with another to use intersection characters (equivalent to a BOX OVER ); a boxtype of 0 ignores
intersections with another box (equivalent to a BOX AT ). |
ENTER
|
Specifies the character value of the keys to use for selecting and unselecting menu items, respectively (see the SELECT and EXIT clauses). There are no default ENTER keys. |
EXIT
|
When the user presses a key to exit the menu, the key_varname
variable contains the character value of the key pressed to exit the menu. The element_varname contains the position of the menu item being prompted for at the time the menu was exited. The top_varname variable contains the position of the item at the top of the menu when the terminator key was pressed. The last_item_varname contains the string value of the menu item where the prompt was positioned when the menu was exited. The TERMINATORS clause defines which key or keys cause termination of the menu. |
FAMILY
| Fills the menu with the names of the families specified in the list. The values of the first and last families may be either numeric or string values. The null family occupies a space in the menu but displays no text. By specifying the first family as 'A' and the last family as 'ZZZZZZZZ', all named families in the procedure file are displayed. |
FILL
| Fills any area of the menu that is not part of a menu item's field, plus leading and trailing blanks in horizontal menus, with the specified character and video attribute. |
GROUP
| Specifies the size of multiple line scrolling jumps (equivalent to a page-up and page-down function). Specifies which keys (page up, page down) move the prompt the specified number of menu items. The default page up/page down values are 296 for up and 273 for down. |
HELP
|
Specifies a help page that is displayed when the user
presses the (Help). The page must be in html format in the help directory. The page name can
contain directory names using forward slashes to delimit. Enclose the
name in quotes. The system will convert this to a file name prefixed with a path
pointing to the help directory and suffixed with the file
extension .htm .
|
HOTKEYS
| Specifies that the menu supports hot-keys. If a menu supports hot keys, the first capital letter in each menu item is the hot key. Pressing this from any point in the menu invokes the item. If the menu does not support hot keys, it supports alpha positioning. This means that when the user types in characters, the menu position is set to the item beginning with those characters. The menu should be in alphabetic sequence for alpha positioning. |
KEEPMENU
| Specifies whether the menu remains on the screen after termination. By default, the menu is cleared from the screen when the user exits from it. A non-zero value keeps the menu on the screen, zero or undefined clears the menu. The value 1 leaves the last prompted for item highlighted. The value 2 'un-highlights' the last prompted for item. |
LIST
|
Specifies a list of items to display as menu choices. The
video
specifies the video display when the items are not being
prompted for. The list is:
|
MEMBER
| Fills the menu with the names of the members implied in the first member and last member specification. The first and last member referenced may be either numeric or string. |
PASTEONLY
|
Specifies that the menu is displayed on the screen, but not
executed. A non-zero value displays with no execution; a zero or undefined
value displays and executes. This is normally used in conjunction with
KEEPMENU which leaves the menu on the screen after it is
displayed and when program execution continues past the menu command.
|
PROMPT
|
Displays the prompt string at the specified columns of the menu. The
prompt string moves from item to item according to the user's directions. (In
most applications, either the PROMPT or the
PROMPTVIDEO clause is used.)In vertical menus, col1 and col2 refer to the columns on the execution window where the prompt string is displayed. These can have the same value resulting in a single character prompt. In horizontal menus, col1 and col2 refer to the positions within an item's field that contain the prompt string, where the field width is equal to the width plus any leading or trailing blanks. |
PROMPTVIDEO
| Specifies the video treatment of the menu item being prompted for. |
RECTYPE
| Fills the menu with the names of the record types implied by the range of record types specified. |
SCREENOK
|
Specifies that the appearance of the screen is as required and that
the menu is not re-displayed. A non-zero value specifies that the screen is OK
and is not re-displayed; a zero or undefined value specifies that the menu
display is displayed. This is often used with the KEEPMENU
option allowing the program to go out of the menu and perform some
task and then return to the menu transparently to the user.
|
SELECT
|
Specifies the manner in which selected menu items in a multiple
select menu are 'marked'. The specified string is displayed at the specified
columns next to selected items. The ENTER option and the
TERMINATORS option must be used to allow multiple choice
menus. The SELECTARRAY option must also be specified so that
the program can tell which items were selected after the menu is exited.
|
SELECTARRAY
|
Names the array or first variable of a numeric variable list used to indicate which items have been selected. The number of elements in the array must be at least as great as the number of items in the menu. When an item is selected, the array element corresponding to the ordinal position of the menu item is set to 1. When an item is un-selected (see ENTER ), the corresponding array element is set to 0. Any select array element containing a non-zero or non-null value at the time the menu is first executed treats the corresponding menu items as having been selected.
|
SELECTVIDEO
|
Specifies the video
treatment of selected menu items.
Either the SELECTVIDEO , SELECT or both are
used for multiple choice menus.
|
SPACING
|
Specifies the number of spaces before and after each menu item on a
HORIZONTAL MENU .
|
START
|
Specifies how the menu items are displayed within the menu when the
command is executed. The first argument specifies the item to display at
the top of the menu. The second argument specifies the item highlighted. Both
arguments are numeric and may be variables or constants. If
START is not specified, the first menu item is placed at the
top and the prompt points to the first item.
|
TERMINATORS
|
Specifies a list of legal terminators by their character
values. When this clause is specified only the keys defined in the list cause
termination of the menu. If the user presses a key not defined as a terminator
key or as a special key by one of the other clauses, the bell rings and the menu
is not terminated. The maximum number of terminator values that can be
specified is 254. If hot-keys are supported these are terminators by definition.
The key values may be numeric constants or variables. If this clause is not
specified, any key, except those which are defined to take a specific action,
causes termination of the menu. The EXIT clause stores which
key caused termination of the menu.
|
TIMEOUT
| Specifies the amount of time to wait for a user to press a key after the menu is displayed, in 1/10 of a second increments. If the user does not press a key in that period of time, the "time out" terminator value is set (char_value = 30002) and the menu is terminated. |
VARNAME
|
Fills the menu with a list of variable names for the specified
record type, with the specified
video attribute.
The variable references may be either string or numeric.
Strings refer to variable names, numbers refer
to DATA LIST order number.
|
VIEW
| Specifies when scrolling occurs as the user moves up and down the menu. Specifies how many rows at the top and bottom of the menu are always displayed away from the prompted item. The default is 0 for both top and bottom, meaning that the menu does not begin scrolling until the user reaches the bottom (or top) of the menu area. |
WIDTH
| Specifies the maximum width of each item on a horizontal menu. If an item is longer than the width specified, then it is truncated to fit the width; if the item is shorter, it is padded with blanks. A width of 0 uses the minimum width needed for each item. |
c This program demonstrates two very simple menus, a c VERTICAL MENU and a HORIZONTAL MENU. The user c selects an item from the first menu, the choice is c redisplayed, and the second menu allows the user to c do it all again or exit the program. PROGRAM STRING * 80 MESSAGE LOOP VERTICAL MENU 5 , 30 , 10 , 45 list ( 'First Menu Item' 'Second Menu Item' 'Third Menu Item' 'Fourth Menu Item') , 0 promptvideo 4 exit KEYVAR,ELEMVAR,TOPVAR,LASTSEL COMPUTE MESSAGE = 'You have selected the ' + LASTSEL + ' ' DISPLAY TEXT MESSAGE AT 15 , 20 HORIZONTAL MENU 20,30,20,50 spacing 2 , 2 list ('Do Again' 'Exit') ,0 promptvideo 4 box 19,29,21,51,0,0 exit KEYVAR,ELEMVAR,TOPVAR,LASTSEL IF(ELEMVAR NE 1) EXIT LOOP END LOOP END PROGRAM
START
| The screen coordinates of the mouse cursor when the command is executed. The values of the starting row and column may be either explicit numbers or variable names. |
END
| The variables which hold the screen coordinates of the mouse when the command is completed. |
BUTTON
| The variable which contains the numeric value of the button that was pressed. 0 - No button (the command is terminated with a keypress); 1 - primary button; 2 - secondary button. |
CHARACTER
| The variable which contains the character value of the key that was pressed. 0 - if mouse button pressed. |
Two consecutive SENSE MOUSE
commands may not give the user
enough time to release the button from the first command. Specify a short delay,
with the WAIT
command, before executing the second
SENSE MOUSE
. The following example allows the user to draw a
box on the screen by using the mouse to specify the top left and then bottom
right coordinates of the box.
PROGRAM SENSE MOUSE START 10 40 END R1 C1 BUTTON BN CHARACTER CHN DISPLAY TEXT '*' AT R1 C1 | mark corner until box is drawn WAIT 1 | wait for user SENSE MOUSE START R1 C1 END R2 C2 BUTTON BN CHARACTER CHN BOX AT R1 C1 R2 C2 WAIT 10 END PROGRAM
Waits for a specified number of tenths of a second.
Any stored template
may be restored to its original location
or to another location on the execution window during execution of a program.
Templates may be stored in one of three places. First, during execution of a
program, a template may be stored temporarily in memory. Second, a template may
be stored permanently as a member in the procedure file. Third, a template may
be stored permanently on a special file called the Template file.
WAIT
WAIT n
Templates
The execution window commands control the appearance of the screen. It is possible to
save the way the window or part of the window looks. A stored window or portion
of window is called a Template. There are commands VisualPQL and options from
Tools
in the pre version 4
menu system to create and save
templates.Templates Stored in Memory
Since stored templates must save every character and the video attribute of the
characters, a potentially large amount of memory may be needed if many screens
are stored. The MEMORY
option forces templates to be in memory rather than on the template file. The system parameter, MMRYTMPL
, forces all temporary template storage to memory rather than the template file. This parameter can be set on the execution statement, with the SET
command and with an environment setting from the pre version 4 menu system.
'SYSTMPLT'
or a file specified on the execution statement. Several commands store templates on
this file. It is not automatically deleted upon terminating a session. The
size of this file grows as each command that stores a template is executed and
it should be deleted on a regular basis.
TEMPLATE
option on the
routine commands specifies
that templates are stored with the executable.
The default is NOTEMPLATE,
.
If the templates needed in the program are stored either in the procedure file
or on the read only template file, there is never a problem. If they were
stored on SYSTMPLT
and have since been deleted, the executable program does not find the template and execution is terminated with an error message. The solution is to recreate and store the templates once again.
REDRAW
|
Displays the template on the screen. If the AT clause is not specified, it is re-drawn at its original location.
|
AT
| Specifies the placement of a re-drawn template by specifying the location of the upper left hand corner of the template. |
IOSTAT
| Specify a numeric variable which receives a return value. A zero indicates success. A non-zero value is the number of the associated error message. |
MEMORY
| Specifies that the template is stored in memory rather than on the template scratch file. This speeds up execution at the expense of memory. |
LOCAL
| Restores a template stored on a template file or in memory, depending on where it was last stored. The name may be specified as a quoted string or as a variable that contains the name of the template. |
MEMBER
| Restores a template stored as a member in the procedure file. The member name may be fully qualified with procfile name, family name and passwords. The member must be a 'template' type, with the suffix ':P'. |
AT
| Specifies the placement of the upper left corner of the template. If this is not specified, the template is restored to its original location. A template that exceeds the boundaries of the execution window gives unpredictable results. |
IOSTAT
| Specify a numeric variable which receives a return value. A zero indicates success. A non-zero value is the number of the associated error message. |
VIDEO
| Specify a video value to change all video values on the restored template to the specified value. |
UP | DOWN
|
UP moves the template up the specified number of
rows. DOWN moves the template down the specified number of
rows. |
ROWS
| Specifies that the unit of movement is rows and is a required keyword. |
FILLCHAR
| Specifies a character with which the vacated rows are filled. |
FILLSTRING
| Specifies a string with which the vacated rows are filled. |
VIDEO
| Specifies the video treatment of the fill character or string. |
LOCAL
|
Stores the template either on the template scratch file or in memory.
It is stored in memory if the system setting MMRYTMPL is
ON or if the MEMORY keyword is specified.
The template name may be a string in quotes or as a string variable.
|
MEMORY
|
Specifies that the template is stored in memory rather than on the template file.
|
MEMBER
| Stores the template as a member. The member name may be fully qualified with procfile, family name and passwords. The member is given the suffix ':P'. The name may be specified as a string in quotes or as a string variable. |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |