Introduction to JYACC FORMAKER

 

                                    Contents

 

 

 

1  About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

 

 

2  JYACC FORMAKER Tools  . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

 

 

3  Getting Started with JYACC FORMAKER . . . . . . . . . . . . . . . . . . . . 1

3.1  Setting Up Your Environment . . . . . . . . . . . . . . . . . . . . . . . 2

3.2  JYACC FORMAKER Function Keys  . . . . . . . . . . . . . . . . . . . . . . 3

 

 

4  A JYACC FORMAKER Glossary . . . . . . . . . . . . . . . . . . . . . . . . . 4

 

Appendix A  Sample Key Assignments . . . . . . . . . . . . . . . . . . . . . . 7

 

Appendix B  List of Supported Terminals and Emulators  . . . . . . . . . . . . 8


 


 

1 About This Manual

 

Congratulations on your purchase of JYACC FORMAKER. Your documentation includes

the following chapters:

 

     The Introduction to JYACC FORMAKER (this chapter) describes the rest

     of the documentation, and tells how to get started with JYACC

     FORMAKER.

 

     The JYACC FORMAKER Author's Guide describes in detail how to create

     screens.

 

     The JYACC FORMAKER Programmer's Guide explains some of JYACC

     FORMAKER's internal operation, shows how to code application routines,

     and describes in detail the support functions supplied with JYACC

     FORMAKER.

 

     The JYACC FORMAKER JPL Programmer's Guide describes the JYACC

     Procedural Language, a specialized interpreted programming language.

 

     The JYACC FORMAKER Configuration Guide explains how to create and

     alter configuration files for terminals and displays, and run various

     utility programs.

 

2 JYACC FORMAKER Tools

 

This section summarizes the authoring and programming tools supplied with JYACC

FORMAKER.

 

The authoring utility, xform, is a screen editor which you use to create display

data, fields and their edits. It is documented in the JYACC FORMAKER Author's

Guide.

 

The JYACC FORMAKER library is an extensive collection of functions for reading

and writing data contained in screens. There are functions for displaying

screens, getting keyboard input, moving data to and from the screen, etc. Much

more information, and a description of each entry point, are available in the

Programmer's Guide.

 

The following utility programs are described in the Configuration Guide.

 

All configuration files come in an ASCII format, which you can modify with a

text editor, and a binary format, which JYACC FORMAKER uses at runtime. msg2bin,

key2bin, var2bin, and vid2bin convert ASCII message, key, setup, and video files

to binary. Modkey is a specialized editor for keyboard configuration files.

There is a utility named f2r4 to convert Release 3 screens to Release 4 format.

There are also utilities for managing the configuration of JYACC FORMAKER

applications: bin2c provides for the creation of memory-resident screens and

configuration files, while f2struct creates programming language data structures

from screens. You can get listings of your screens with lstform, and create

libraries of screens with formlib.

 

3 Getting Started with JYACC FORMAKER

 

If JYACC FORMAKER has not yet been installed on your computer, please refer to

the Installation Notes for guidance, and return to this section when you are

ready to try out the newly installed software.

 

Sit down at your computer or terminal and invoke the JYACC FORMAKER authoring

utility by typing

 

     xform


 

at the system prompt. If all is well, the screen will clear, you will be

prompted for the name of a screen to edit, and you are ready to go. If, on the

other hand, the computer prints only a single error message, there are some

things to set up in your environment.

 

3.1  Setting Up Your Environment

 

Execution Path

 

If the message you see resembles one of the following:

 

        Bad command or filename       (MS-DOS)

        jxform not found         (UNIX/XENIX)

        Not found. XFORM (std$cp)     (PRIMOS)

 

then the directory where JYACC FORMAKER resides is not in your execution path,

and you must add it. Here are some examples of how to do this:

 

        PATH=$PATH:/usr/sm/util; export PATH    (UNIX, Shell)

        set path=($path /usr/sm/util)           (UNIX, C shell)

        PATH c:\bin;c:\usr\bin;c:\usr\sm\util   (MSDOS)

 

MS-DOS note: you must type in the old value of the path by hand; it can be

obtained by typing 'path' with no argument.

 

PRIMOS note: there is no environment; you must either install xform in CMDNC0,

or define an abbreviation to run it from the installation directory.

 

JYACC FORMAKER Configuration Variables

 

If the message you see is

 

     SMMSGS not found

 

then you need to define JYACC FORMAKER configuration variables. (If it is

SMVIDEO not found or SMKEY not found, you probably just need to set SMTERM; but

bear with us for a moment.) Here are the variables and their meanings:

 

   SMMSGS         pathname of a file containing error message text SMKEY

                  pathname of a keyboard configuration file SMVIDEO

                  pathname of a display configuration file SMVARS

                  pathname of an abbreviation file containing all three

                  SMTERM

                  abbreviates your terminal's make and model

 

The first three are the ones you really need. They tell JYACC FORMAKER where to

find its configuration files: one with error message text, another that maps

your terminal's keys to JYACC FORMAKER's logical keys, and a third that tells

JYACC FORMAKER how to control your terminal's display. These files are normally

installed in a subdirectory named config of the directory where JYACC FORMAKER

was installed. The default message file is called "msgfile.bin". The video and

keyboard files come in pairs; their names consist of a prefix corresponding to

the terminal type followed by "vid.bin" and "keys.bin" respectively, as in

 

     vt100keys.bin     vt100vid.bin

 

for the DEC VT-100. The "config" subdirectory contains files named smvars and

smvars.bin, with pathnames of all the configuration files qualified by the

terminals to which they belong.

 

Anyway, once you've found the files you need, the easiest thing to do is to

assign their full pathnames to the SMMSGS, SMKEY, and SMVIDEO variables. (An

alternative is to set the SMVARS variable to the pathname of the smvars.bin file

in the JYACC FORMAKER config directory, and your SMTERM to your terminal

abbreviation. Then, JYACC FORMAKER will find the files flagged with your

terminal type in the SMVARS file.)

 

PRIMOS note: the configuration files are in a top-level directory named

FORMAKER*, and there is no environment; JYACC FORMAKER will prompt for your

terminal type.

 

MSDOS/XENIX note: for consoles, the key file is "IBMkeys.bin"; the video file is

"bwvid.bin" for monochrome monitors, and "colvid.bin" for color monitors.

 

If Your Terminal Isn't Configured

 

There is a list of terminals for which JYACC distributes configuration files in

an Appendix to this chapter. If you cannot find distributed configuration files

for your specific model, check for emulations. Many popular terminals, for

instance, emulate the DEC VT-100; others may support the ANSI standard escape

sequences. If that doesn't work, you will need to create your own; the JYACC

FORMAKER Configuration Guide will help you through that process.

 

3.2  JYACC FORMAKER Function Keys

 

JYACC FORMAKER interprets a number of keys specially. Here is a list of their

names and functions. To find out how these logical functions are assigned to

your terminal's keys, examine the key translation file, or run the modkey

utility on it. That utility, described in the Configuration Guide, contains a

key translation test screen that you can use to check your key mappings. To find

the key files, see the previous section; listings for the IBM PC and WYSE-85 are

appended to this chapter as examples. There is a detailed summary of special

keys in the Author's Guide, in the section on data entry.

 

   JYACC FORMAKER Functions

   Transmit      Menu selection or end of data entry Exit

                 Abort data entry, return to previous screen

 

   Cursor Motion

   Up Arrow      Cursor up one line or field Down Arrow

                 Cursor down one line or field Left Arrow

                 Cursor left one column or field Right Arrow

                 Cursor right one column or field Tab

                 Next field Backtab

                 Previous field Return

                 Next field on following line Page Up

                 Scroll data up in scrolling field Page Down

                 Scroll data down in scrolling field

 

   Data Editing

   Insert        Toggles insert/overwrite mode Delete

                 Deletes character under cursor Backspace

                 Deletes character to left of cursor Field Erase

                 Erase from cursor to end of field Clear Screen

                 Erase all unprotected fields

 

   Application Functions

   PF1-PF24      These are commonly assigned to the otherwise APP1-APP24

                 unnamed function keys on a terminal. SPF1-SPF24


 

4 A JYACC FORMAKER Glossary

 

array                 Several fields grouped together in one place, that  can be

                      treated as a unit. The elements of an array share all

                      characteristics, such as scrolling, and can be referred

                      to as occurrences of the first field in the array.

 

attached function     An application routine associated with a field that is

                      called with certain parameters whenever the cursor enters

                      or exits the field. Also, an application routine

                      associated with a screen and called upon screen entry or

                      exit.

 

border                Text or highlighting used to mark the outline of a

                      screen.

 

character edits       A field's character edit defines what type of character

                      may be entered in a field, such as digits, letters, or a

                      yes-or-no answer.

 

display               A physical screen, such as a terminal on a multi-user

                      computer or the monitor on a personal computer.

 

display attribute     Visible characteristics of data on the screen, such as

                      color, highlighting, underlining, or blinking.

 

display data          The fixed part of a screen: text, borders, and graphics

                      that do not change. Distinct from fields, which may be

                      altered by the program or by data entry.

 

element               A field that is part of an array. An array element may be

                      referred to either by its own field number, or by the name

                      of the array plus its element number. A non-array field is

                      considered to have a single element.

 

element number        A field's element number is its position within the array

                      it belongs to. The element number of a simple field is 1.

 

field                 A variable area of a screen, used for the exchange  of

                      data between an application and its user. A single field

                      occupies part or all of one line. It may be extended

                      horizontally through shifting, and vertically through

                      scrolling. Fields may have many characteristics and

                      actions associated with them, known variously as edits,

                      attachments, and validations.

 

field attachment      An item associated with but distinct from a field.

                      Examples include a help screen, a prompt, an attached

                      function, a calculation, or a menu of possible items for

                      data entry.

 

field edits           Field edits either restrict the data that can be entered

                      into a field, or alter its appearance. Examples include a

                      range of permissible values, right justification,

                      conversion to upper case, and dollar amount format.

 

field number          JYACC FORMAKER numbers fields according to their positions

                      within a screen, from left to right then top to bottom,

                      beginning at 1. When a field is spoken of as "next" or

                      "following" another field, this is the ordering that

                      applies.

 

field validation      An action associated with a field that checks data entered

                      there for correctness.

form                  A screen that occupies the entire display and does not

                      overlay another screen, as opposed to a window. Often used

                      loosely as synonymous with screen.

 

function key          A key that has some special function other than data

                      entry, for instance cursor motion. JYACC FORMAKER treats

                      such keys as logical keys, referring to what they do

                      rather than to their labels on the keyboard, since the

                      labels are different for the many keyboards it supports.

 

function list         A list of pairs of function names and addresses, compiled

                      into JYACC FORMAKER applications to provide necessary

                      linkage.

 

help screen           A screen containing any information helpful to the user of

                      a JYACC FORMAKER application. Help screens may be attached

                      to JYACC FORMAKER screens and fields; they appear when the

                      HELP or FORMHELP function keys are struck.

 

item                  Data entered into a scrolling field, or into one field of

                      a scrolling array.

 

item number           The position of an item within its scroll list. The item

                      number does not depend on the item's position on the

                      screen.

 

justification         Data in JYACC FORMAKER fields may be either right- or

                      left-justified, that is, pushed all the way to the right-

                      or left-hand end of the field.

 

library               The JYACC FORMAKER function library, which contains

                      routines application programmers can use to access data in

                      screens and the local data block.

 

logical key           JYACC FORMAKER's interpretation of a function key, as

                      opposed to the physical key on a terminal. Physical keys

                      are mapped to logical keys by a configuration file.

 

menu                  A screen containing a list of choices, from which the user

                      may select one.

 

occurrence            A general term covering simple fields, array elements, and

                      items of scroll lists. In a scrolling field or array,

                      occurrence is equivalent to item; in a non-scrolling

                      array, it is equivalent to element.

 

occurrence number     A data item's element number or item number, whichever

                      applies. If the field is neither scrolling nor part of an

                      array, the occurrence number is 1.

 

parallel array        Scrolling arrays placed next to one another will scroll in

                      parallel, i.e. whenever one array is scrolled with the

                      cursor or page keys the associated arrays scroll

                      simultaneously.

 

prompt                Text associated with a field that appears on the

                      terminal's status line whenever the cursor enters the

                      field. Also called status text.

 

protected field       A field into which no data may be entered from the

                      keyboard.

 

screen                Data to be displayed on a computer's terminal or display,

                      such as menus and data entry forms. When the hardware

                      display itself is meant, the terms physical screen or

                      display are used.

 

screen editor         A JYACC FORMAKER tool used to create and alter screens.

 

scrolling             JYACC FORMAKER screens may contain data lists that are too

                      long to fit in available space; such lists may be

                      scrolled, either in a single field or in an array of

                      fields. The cursor motion keys cause different parts of

                      the list to appear on the screen.

 

scroll list           A data list displayed through a scrolling field or array.

 

shifting              A data item too wide to fit in a field may be shifted

                      horizontally; the cursor motion keys will cause different

                      parts of the item to appear in the field.

 

status line           JYACC FORMAKER sets aside one line of the physical screen,

                      usually the bottom one, for error and status messages; it

                      is called the status line.

 

status text           See prompt.

 

system date           The current date, as stored in the computer. JYACC

                      FORMAKER date fields can be automatically initialized to

                      the system date.

 

system time           The current time, as stored in the computer. JYACC

                      FORMAKER time fields can be automatically initialized to

                      the system time.

 

user date             A date entered into a JYACC FORMAKER date field by the

                      user of an applciation.

 

user time             A time entered into a JYACC FORMAKER time field by the

                      user of an application.

 

window                A screen that normally does not cover the whole physical

                      screen, and overlays some other screen or screens.

 

word wrap             Fields and scrolling arrays may have a word wrap edit,

                      which will cause whole words to be kept together on the

                      same line of text. (JYACC FORMAKER's default is to fill

                      the field with characters, without regard to word

                      spacing.)

 

zoom                  Shifting and scrolling fields may be viewed and edited as

                      a whole, in a pop-up window, using a special zoom key.


 

 

Appendix A  Sample Key Assignments

 

You will find explanations of the key names used here in the section of the

Author's Guide entitled Data Entry.

 

JYACC FORMAKER key assignments for the IBM PC family:

 

EXIT         = Esc TRANSMIT

             = End HELP

             = control-F1 FORM HELP

             = alt-F1 LOCAL PRINT

             = control-P RETURN

             = Enter TAB

             = Tab BACKTAB

             = shift-Tab BACKSPACE

             = control-H HOME

             = Home PAGE UP

             = Pg Up PAGE DOWN

             = Pg Dn INSERT MODE

             = Ins INSERT LINE

             = control-K DELETE CHAR

             = Del ERASE

             = control-Pg Up CLEAR ALL

             = control-Pg Dn ZOOM

             = control-Z PF1

             = F1 ... PF10

             = F10 SPF1

             = shift-F1 ... SPF10

             = shift-F10

 

JYACC FORMAKER key assignments for the Wyse 85:

 

EXIT         = F11 TRANSMIT

             = Do HELP

             = Help TAB

             = Tab or control-I

             BACKTAB

             = F12 HOME

             = F14 BACKSPACE

             = control-H DELETE CHAR

             = Remove INSERT MODE

             = Insert Here ERASE

             = Select CLEAR ALL

             = control-Z PAGE DOWN

             = Next Scrn PAGE UP

             = Prev Scrn RESCREEN

             = Find ZOOM

             = control-E PF2

             = F6 ... PF6

             = F10 PF7

             = F17 ... PF10

             = F20 SPF1

             = PF4 1 ... SPF9

             = PF4 9


 

 

Appendix B  List of Supported Terminals and Emulators

 

The following list is subject to constant revision, usually by having more

things added to it. The mnemonics listed can be found as prefixes to key and

video files in the config subdirectory of your JYACC FORMAKER distribution. As

distributed by JYACC, names of video files end in vid and names of key files end

in keys. You may find that you need to shorten or otherwise alter some of the

names, to suit your operating system or your own naming conventions.

 

   Terminal mnemonic        Description

 

   5425t                    AT&T 4425 terminal.

 

   7900                     NCR 7900 M1+ terminal.

 

   FT                       Fortune Systems terminal.

 

   TV9220                   TeleVideo 9220 terminal. Also found as NTV9220,

                            WTV9220 for 80- and 132-column modes

                            respectively.

 

   TVO                      TeleVideo 955 terminal with onscreen attributes.

 

   W85                      Wyse 85 terminal. Also found as NW85, WW85 for

                            80- and 132-column modes respectively.

 

   a219                     Ampex 219 terminal (in native mode).

 

   ansi                     Color PC console for SCO XENIX.

 

   avt                      HDS AVT terminal.

 

   bw                       Monochrome monitor on MS-DOS system.

 

   c108                     Concept 108 terminal.

 

   col                      Color monitor on MS-DOS system.

 

   cpt200                   Color PC with PCLINK emulating a PRIME PT200

                            terminal.

 

   d214                     Data General Dasher 214 terminal (in DG mode).

 

   f100                     Freedom 100 terminal.

 

   h0                       Honeywell VIP 7300 terminal.

 

   hds                      HDS model 200 terminal.

 

   host                     Basic ANSI terminal or emulator, with color.

 

   hostpc                   Stratus PCTERM emulator, monochrome or color.

 

   hp                       Hewlett-Packard 2392a terminal.

 

   iii                      TeleVideo 955 terminal, with onscreen attributes

                            and color.

 

   j8, j8c                  Monochrome and color PC, respectively, with JYACC

                            jterm emulator and 8-bit control sequences.

 

   jterm, jtermc            Monochrome and color PC, respectively, with JYACC

                            jterm emulator.

   opus220                  Opus 220 terminal.

 

   pc                       Either monochrome or color PC with generic VT-100

                            emulator.

 

   pt200, pt132             PRIME pt200 terminal, in 80- or 132-column mode;

                            also monochrome PC with PCLINK emulator.

 

   pt200w                   PRIME pt200 in 48-line mode.

 

   svt200                   Sperry SVT1220 terminal.

 

   ti931                    Texas Instruments 931 terminal.

 

   tvi921                   TeleVideo 921 terminal with onscreen attributes.

 

   tvi950                   TeleVideo 950 terminal with area attributes.

 

   tvi955                   TeleVideo 955 terminal with area attributes.

 

   v101                     Stratus V101 terminal.

 

   v102                     Stratus V102 terminal.

 

   vt100                    DEC VT-100 terminal or emulator.

 

   vt200                    DEC VT-200 terminal or emulator.

 

   vt220                    DEC vt220 terminal or emulator.

 

   wy30                     Wyse 30 terminal, or HP 700/41 emulating the

                            same.

 

   wy50                     Wyse 50 terminal.

 

   wy75                     Wyse 75 terminal.

 

   x100, x100c              Monochrome or color PC with Crosstalk emulating a

                            VT-100.


 

skipsomething


 

 

 

 

 

 

 

                                        Index

 

 

 

 

 

                      In this Index, library functions are

                      displayed in  boldface,  without the

                      prefixes  specific  to  the language

                      interface.  Video  and   setup  file

                      entries appear in ELITE CAPS,  while

                      utility  programs  and  JPL commands

                      are  in  elite  lower-case. Function

                      key names are in ROMAN CAPS.

 

 

 

 

                                             field attachment

                 A                              definition 1-4

                 array                       field edits

                    definition 1-4              definition 1-4

                 attached function           field number

                    definition 1-4              definition 1-4

                 authoring utility           field validation

                      1-1                       definition 1-4

                                             form

                 B                              definition 1-5

                 bin2c utility 1-1           formlib utility

                 border                           1-1

                    definition 1-4           function key

                                                definition 1-5

                 C                           function library

                 character edits                  1-1

                    definition 1-4           function list

                 configuration 1-1              definition 1-5

 

                 D                           H

                 display                     help screen

                    definition 1-4              definition 1-5

                 display attribute

                    definition 1-4           I

                 display data                item

                    definition 1-4              definition 1-5

                                             item number

                 E                              definition 1-5

                 element

                    definition 1-4           J

                 element number              justification

                    definition 1-4              definition 1-5

                                             JYACC FORMAKER

                 F                              getting started

                 f2r4 utility 1-1                 with 1-1

                 f2struct utility

                      1-1                    K

                 field                       key2bin utility

                    definition 1-4                1-1


 

                                             SMMSGS setup

                 L                                variable 1-2

                 library                     SMTERM setup

                    definition 1-5                variable 1-2

                 logical key                 SMVARS setup

                    definition 1-5                variable 1-2,

                 lstform utility                  1-3

                      1-1                    SMVIDEO setup

                                                  variable 1-2

                 M                           status line

                 menu                           definition 1-6

                    definition 1-5           status text

                 Modkey utility                 definition 1-6

                      1-1, 1-3               system date

                                                definition 1-6

                 O                           system time

                 occurrence                     definition 1-6

                    definition 1-5

                 occurrence number           U

                    definition 1-5           user date

                                                definition 1-6

                 P                           user time

                 parallel array                 definition 1-6

                    definition 1-5

                 prompt                      V

                    definition 1-5           var2bin utility

                 protected field                  1-1

                    definition 1-5           vid2bin utility

                                                  1-1

                 S

                 screen                      W

                    definition 1-5           window

                 screen editor                  definition 1-6

                    definition 1-6           word wrap

                 scroll list                    definition 1-6

                    definition 1-6

                 scrolling                   Z

                    definition 1-6           zoom

                 shifting                       definition 1-6

                    definition 1-6

                 SMKEY setup

                      variable 1-2