Start TFR software reference manual at next page T F R ======= Software Reference Manual Version V1.1 November 1983 This document describes how to use the Terminal Form Routines (TFR). It provides the information required to design forms for display on a video terminal and to develop programs that use TFR-forms for gathering and displaying data. Contents CHAPTER 1 Introduction to TFR 1.1 Overview . . . . . . . . . . . . . . . . . . . . . 1-1 1.2 Forms source file . . . . . . . . . . . . . . . . 1-2 1.3 Forms compiler . . . . . . . . . . . . . . . . . . 1-2 1.4 Form driver subroutines . . . . . . . . . . . . . 1-2 CHAPTER 2 Forms source file 2.1 Overview . . . . . . . . . . . . . . . . . . . . . 2-1 2.2 Terminology . . . . . . . . . . . . . . . . . . . 2-2 2.2.1 Screen form . . . . . . . . . . . . . . . . . . 2-2 2.2.2 Form description . . . . . . . . . . . . . . . . 2-2 2.2.3 Field . . . . . . . . . . . . . . . . . . . . . 2-2 2.2.4 Forms source file . . . . . . . . . . . . . . . 2-2 2.2.5 Forms library file . . . . . . . . . . . . . . . 2-2 2.2.6 Forms document list file . . . . . . . . . . . . 2-2 2.3 Video attributes . . . . . . . . . . . . . . . . . 2-3 2.4 Form description language . . . . . . . . . . . . 2-3 2.4.1 FRM-record . . . . . . . . . . . . . . . . . . . 2-4 2.4.2 FIX-record . . . . . . . . . . . . . . . . . . . 2-4 2.4.3 DON-record . . . . . . . . . . . . . . . . . . . 2-5 2.4.4 UPD-record . . . . . . . . . . . . . . . . . . . 2-6 2.4.5 DEF-record . . . . . . . . . . . . . . . . . . . 2-6 2.4.6 HLP-record . . . . . . . . . . . . . . . . . . . 2-7 CHAPTER 3 Forms compiler 3.1 Running the compiler . . . . . . . . . . . . . . . 3-1 3.2 Output from the compiler . . . . . . . . . . . . . 3-2 3.2.1 Forms library file . . . . . . . . . . . . . . . 3-2 3.2.2 Forms document list file . . . . . . . . . . . . 3-2 3.2.3 Error messages . . . . . . . . . . . . . . . . . 3-3 CHAPTER 4 Introduction to the form driver subroutines 4.1 Form driver subroutine interaction with forms source file . . . . . . . . . . . . . . . . . . . 4-1 4.1.1 Program access to forms . . . . . . . . . . . . 4-2 4.1.2 Defining forms and fields by name . . . . . . . 4-2 4.1.3 Displaying the form . . . . . . . . . . . . . . 4-2 4.1.4 The HELP function . . . . . . . . . . . . . . . 4-3 4.1.5 Storage of field values: field copy record (FCR) 4-3 4.1.6 The order in which the fields are processed . . 4-3 4.1.7 Default values . . . . . . . . . . . . . . . . . 4-3 4.2 Form driver subroutines interaction with terminal operator . . . . . . . . . . . . . . . . . . . . . 4-4 4.2.1 Field editing principles and functions . . . . . 4-4 4.2.1.1 Erasing a character: DELETE . . . . . . . . . . 4-6 4.2.1.2 Erasing a field: LINEFEED . . . . . . . . . . . 4-6 4.2.1.3 Moving cursor to the right: Right-arrow key . . 4-6 4.2.1.4 Moving cursor to the left: Left-arrow key . . . 4-7 4.2.2 Switching the modes: INSERT / OVERSTRIKE . . . . 4-7 4.2.3 Field terminating fuctions . . . . . . . . . . . 4-8 4.2.3.1 Signaling form is complete: ENTER and RETURN . . 4-9 4.2.3.2 Moving cursor to the next field: TAB . . . . . . 4-9 4.2.3.3 Moving cursor to the previous field: BACKSPACE 4-10 4.3 Simultaneous display of multiple forms . . . . . 4-10 CHAPTER 5 Form driver subroutine calls 5.1 TFRCLR - clear screen . . . . . . . . . . . . . . 5-1 5.2 TFRDEF - fill/change default field value . . . . . 5-2 5.3 TFRFLD - output field value . . . . . . . . . . . 5-2 5.4 TFREND - close library and clear video attributes 5-2 5.5 TFRFLD - output field value . . . . . . . . . . . 5-2 5.6 TFRGET - get all field values from screen . . . . 5-3 5.7 TFRMES - put message on screen . . . . . . . . . 5-3 5.8 TFROPN - open forms library file . . . . . . . . . 5-4 5.9 TFRPOS - choose a form from the forms library . . 5-4 5.10 TFRPUT - output all values . . . . . . . . . . . . 5-4 5.11 TFRRES - return values to application program . . 5-5 CHAPTER 6 Software example 6.1 Create forms source file . . . . . . . . . . . . . 6-1 6.2 Create forms library file . . . . . . . . . . . . 6-2 6.3 Write FORTRAN IV application program . . . . . . . 6-2 CHAPTER 7 System internals 7.1 System subroutines . . . . . . . . . . . . . . . . 7-1 7.2 System size . . . . . . . . . . . . . . . . . . . 7-1 7.3 Overlay requirements . . . . . . . . . . . . . . . 7-2 CHAPTER 1 Introduction to TFR 1.1 Overview TFR is a set of Terminal Form Routines. TFR software contains the tools for developing form applications and running them on a video terminal. Printed forms have been the most common tool for collecting and transmitting data in an orderly manner. TFR software now brings the speed, convenience, accuracy and low cost of computerized processing to users who have been using printed forms. TFR is written in FORTRAN IV for RT11/RSTS and FORTRAN IV+ for RSX-11M. The functions of TFR are very much alike DIGITAL's FMS-package but they use less memory and are therefore very useful under circumstances where memory is a bottleneck. Although TFR is developed for use on a VT100-compatible terminal, it is not complicated to modify the package to be used with other scope terminals. Forms are designed by the use of a form description language described furtheron in this manual. TFR associates constant data with the form, not with the application program, resulting in simplified application program maintenance and increased application program flexibility. Forms can later be modified without the need to recompile the application program. TFR software has three main components for developing and executing form application programs: - forms source file - forms compiler - form driver subroutines Introduction to TFR page 1-2 1.2 Forms source file The forms source file contains records which describe the forms as a whole by defining the fields (name, length, video attributes etc.). These records are legible ASCII-character strings (form description language), and can be created and/or modified by any available text editor. To help terminal operators, you can include in the form descriptions short, helpful explanations about the individual fields. When designing forms, you assign form names, field names, and refer to data that will be used by the form driver subroutines, when the form is used by an application. The desired operator response to information displayed or data to be entered on forms is controlled by the actual design of the form and the specific application requirements. 1.3 Forms compiler The forms compiler TFR allows you to create and modify forms libraries and versions of form descriptions that are suitable for hard-copy listings (forms document list file). 1.4 Form driver subroutines The form driver subroutines are a set of routines that permits your application program to access forms from a forms library created by the forms compiler. Application programs access forms by issuing form driver subroutine calls that are embedded in the program and are written in the source language of the program. All form driver subroutine calls refer to specific forms and/or fields within the forms by the names you assigned to them in the forms source file. The form driver subroutines also responds to operator HELP requests by displaying help text associated with the field being processed. CHAPTER 2 Forms source file 2.1 Overview Using any text editor available on your system and the form description language, you can create, modify and store customized forms. Your application programs can then use these forms to collect data entered by an operator at a video terminal. Creating or editing a form is an interactive and iterative process. You can test the various possibilities by observing the forms document list file or by testing your design using a small test program (see software example elsewhere). The product of your editor work is one or more form descriptions in the forms source file, that can be translated by the forms compiler into the forms library file. The form descriptions can be retrieved from the forms source file for additions or modifications. You can change individual fields or text portions of the form without affecting other fields or text. For example, you might want to translate the text of a form into another language, reposition items on the screen to make the form more attractive to the eye or easier for an operator to handle, add or remove fields, or supply additional help text or default values. You can make these and other changes by editing the forms source file and recompile it into the forms library file. The purpose of the form description is to provide information to another software component: the form driver subroutines. These routines handle the interaction of the terminal operator with the form displayed on the screen and with the application program. Forms source file page 2-2 2.2 Terminology 2.2.1 Screen form The screen form looks like a paper form but is instead a video display. The computer displays a form by using a form description that specifies to the computer which characters to display on the screen. 2.2.2 Form description The form description is the computer's specifications of a screen form. It specifies which characters to display on the screen as well as the location, size and other characteristics of each field. The name of the form and how the form and its fields are processed are also part of the specification. 2.2.3 Field A field is a set of contiguous screen positions with defined starting position, field length and video attributes. A field can be a fix text string or a formatted blank for some of the information that a form has been designed to work with. 2.2.4 Forms source file The forms source file is a computer file that contains one or more form descriptions in legible ASCII format (form description language). It can be modified by the use of any text editor and must be compiled by the forms compiler in order to make the form description(s) processable by the form driver subroutines. 2.2.5 Forms library file The forms library file is a computer file containing at least one form description. It is a binary file is arranged so individual form descriptions can be accessed by name for use by form driver subroutines. 2.2.6 Forms document list file The forms document list file is a legible ASCII file showing full documentation on the contents of a forms library file (form names, form screen lay-outs, field-name, -length, -video attributes, help text and default values). Forms source file page 2-3 2.3 Video attributes Video attributes are terminal dependant. If a specified attribute is unknown for the terminal type in use, the coded mnemonic will have no effect. Video attributes for fields must be coded according to the form description language as follows: BL - blink : displays the characters of the field in alternately increasing and decreasing screen brightness. BO - bold : displays the characters of the field in bold face. UL - underline : underlines the characters of the field. RV - reverse video: displays the characters of the field on a reverse screen background. If the screen is white-on-black, characters in reverse video appear in black-on-white; if the screen is black-on-white, the characters appear in white-on-black. These mnemonics can be combined by adding them together to one string with or without any separating character (not a comma!) (e.g. ULBORV or UL+BO+RV or UL/BO/RV). 2.4 Form description language The form description language is the language used to describe forms in the forms source file. It is legible ASCII format and can be created and/or modified by any text editor available on the system. Every form description record contains a record type code and one or more data items which hold the describing information. Record type code and data items within one record are mutually separated by comma's. Text-, data- and help-strings (always the last data item in a description record) may contain comma's without being considered as data item separators. Description records may have a maximum length of 126 characters. Record type code, form name, field name and video attributes may appear in upper-case, lower-case or mixed-case, and are transferred to upper-case by the forms compiler. Text-, data- and help-strings are not modified in any way. Forms source file page 2-4 2.4.1 FRM-record The FRM-record defines the start of a new form description in the forms source file and has following format: FRM , name where: FRM is the record type code. name is the name of the form (max. 6 characters). This is the name by which the form is referred to by the application program. 2.4.2 FIX-record The FIX-record defines a text-string at a fixed location and has following format: FIX , location , video-att , text-string where: FIX is the record type code. location is the definition of row and column where the text-string starts. Two integer values (row: 1-23, column: 1-80) separated by any non-numeric character except a comma (e.g. row 3 column 5: 3 5 or 3/5 or 3;5 etc.). video-att video attribute mnemonics string (see elsewhere). An empty string (spaces) specifies normal characters. text-string string to be printed (max. 79 characters), leading and trailing spaces are discarded,except when inbedded in apostrophes. Forms source file page 2-5 2.4.3 DON-record The DON-record defines a display-only field, where data can be displayed by the application program. It has following format: DON , name , length , location , video-att where: DON is the record type code. name is the name of the field (max. 6 characters). This is the name by which the field is referred to by the application program. length is the number of characters in the field. location is the definition of row and column where the field starts. Two integer values (row: 1-23, column: 1-80) separated by any non-numeric character except a comma (e.g. row 3 column 5: 3 5 or 3/5 or 3;5 etc.). video-att video attribute mnemonics string (see elsewhere). An empty string (spaces) specifies normal characters. Forms source file page 2-6 2.4.4 UPD-record The UPD-record defines an update field (=data entry field), where data can be entered and/or displayed the application program. It has following format: UPD , name , length , location , video-att where: UPD is the record type code. name is the name of the field (max. 6 characters). This is the name by which the field is referred to by the application program. length is the number of characters in the field. location is the definition of row and column where the field starts. Two integer values (row: 1-23, column: 1-80) separated by any non-numeric character except a comma (e.g. row 3 column 5: 3 5 or 3/5 or 3;5 etc.). video-att video attribute mnemonics string (see elsewhere). An empty string (spaces) specifies normal characters. 2.4.5 DEF-record The DEF-record defines the default data of the preceding UPD-record. Only one DEF-record per update field is permitted. Because defining default data is optional, this record may be omitted. It has following format: DEF , data-string where: DEF is the record type code. data-string is the string representing the default data (max. number of characters defined by the length of the associated update field). Leading and trailing spaces are discarded,except when inbedded in apostrophes. Forms source file page 2-7 2.4.6 HLP-record The HLP-record defines the help text for the preceding UPD-record which will be displayed as soon as the operator uses the help function when processing that field. Only one HLP-record per update field is permitted. Because defining help text is optional, this record may be omitted. It has following format: HLP , help-string where: HLP is the record type code. help-string is the help text to be displayed at the help message screen position (max. 79 characters). Leading and trailing spaces are discarded,except when inbedded in apostrophes. CHAPTER 3 Forms compiler The forms compiler is the only program that creates and modifies forms library files. The compiler should be used when you want to examine the contents of a forms library file. The compiler provides following sevices: - Translates a (legible ASCII) forms source file into a (binary) forms library file. - Creates a forms document list file, showing the contents of the forms library file. 3.1 Running the compiler To run the compiler type: RUN TFR The compiler returns with an identification and asks for a source file name and whether a forms library file and/or document list file should be made. The programs for RSX and RT11 ask their questions differently. RSX asks wether the output files must be created or not, while RT11 asks for the device where the output files must be written to. Both create the output files with fixed filenames depending on the source filename. For RT11 : Source file : If a name is entered without extension, the compiler will search for the existence of a file with extension ".FRM". Forms compiler page 3-2 Device Library file : Enter the divice where the compiler must write its library file with extension ".FEX". Default is no library file. Device Document file : Enter the divice where the compiler must write its document list file with extension ".FLS". Default is no document file. For RSX : Source file : If a name is entered without extension, the compiler will search for the existence of a file with extension ".FRM". Library file : If Yes is entered the compiler will create a library file with extension ".FEX". Default entry is "Y". Document file: If Yes is entered the compiler will create a forms document list file with extension ".FLS". Default entry is "Y". Now the compiler prints all the names of the forms encountered in the forms source file and the eventual error messages. 3.2 Output from the compiler 3.2.1 Forms library file The forms library file is the only file used by the form driver subroutines, and must have the extension ".FEX" in order to be acessable. 3.2.2 Forms document list file The forms document list file is a legible ASCII printfile showing the contents of the forms library file. For every form in the library file it shows two types of information: - screen lay-out with fix text, update and display-only fields (represented by the text itself, U- resp. D-characters). - field description data, default data and help texts. Forms compiler page 3-3 3.2.3 Error messages If the compiler discovers soft or hard errors during compilation of the forms source file, it can issue three kinds of messages to the terminal screen and to the forms document list file (if active): W (warning) invalid data replaced by compiler defaults. E (error) invalid data send to the library (if active) which will result in erroneous execution of the form driver subroutines. F (fatal error) non-recoverable error, resulting in compiler execution halt. Error messages have following lay-out: ?TFR-t-[record type code/[field name/]] message-text where: t is the error type code: W, E or F. record type code is the identification of the form description record where the error was found. field name is the name of the field where the error was detected, or the name of the associated field in case of record type code being DEF or HLP. CHAPTER 4 Introduction to the form driver subroutines The form driver subroutines are a set of routines that is a subcomponent of your program. In an application that uses video images of forms on the terminal screen, using the form driver subroutines can reduce your programming effort by manipulating the screen and displaying help messages and forms when the operator requests them. This chapter discusses how the form driver subroutines interact with: - the form description as created in the forms source file. - the terminal operator, who completes the fields in a displayed form. Throughout the chapter, programming requirements are mentioned and specific subroutine calls are mentioned occasionally but not fully described. In the next chapter the calls are arranged in alphabetical order and full description is presented for each one. 4.1 Form driver subroutine interaction with forms source file This section describes how the form driver subroutines uses forms to display information for the operator, guide the operator through a form, and collect the responses that the operator types in. The term "form" refers to the image that the operator sees and to the computerized form description that the form driver subroutines handle internally. Introduction to the form driver subroutines page 4-2 4.1.1 Program access to forms Your program uses form descriptions by reading them from the forms library file that has been stored on a mass storage volume, such as a disc. Form descriptions created in the forms source file must be translated by the forms compiler into the forms library file, in order to be accessable by the form driver subroutines. 4.1.2 Defining forms and fields by name The name that you assign to a form in the forms source file is the only information that the form driver subroutines need to read the form from the forms library file. The name that you assign to a field in the forms source file is all the form driver subroutines require, regardless of where you locate the field within the form. As long as changes to form and field characteristics have no effect on the logic of your programs, you can change the characteristics without having to modify your programs. 4.1.3 Displaying the form A typical procedure for displaying a form at the beginning of an TFR application is as follows: 1. For all applications, open the forms library file. This is done with the TFROPN call. 2. Position the library file at the desired form. This is done with the TFRPOS call. 3. Change, if you wish so, the default values of the form. This is done with the TFRDEF call. 4. Display the form by using the TFRPUT call. The form driver subroutines TFRCLR and TFRPUT provide a mechanism to clear the screen partially. If you use short forms, you can use several TFRPUT calls to create a screen display for the operator that is composed of more than one form or part of a form. In this case, only one form will be active for the operator, but you can use sophisticated programming techniques to simulate more than one form being active at a time. Introduction to the form driver subroutines page 4-3 4.1.4 The HELP function Whenever your program issues a call for an operator response, the form driver subroutines can display a help text for the field in which the cursor is located. When the operator uses the help function (i.e. push the PF2 key) the form driver subroutines try to access the help text as defined in the forms source file for the current field. If no such text was defined a message will be displayed accordingly. 4.1.5 Storage of field values: field copy record (FCR) When you position the library file at a specific form (TFRPOS), a buffer is available (in the forms library file) for the storage of the field data, the so called field copy record (FCR). When you issue a call to get or display data values, identify fields and complete other processes, the form driver subroutines use and update this FCR-buffer as well as displaying information for the operator and providing values to your program. The FCR-buffer is strictly for use by the form driver subroutines. You can, however, use the TFRRES call to obtain any field value as stored in the FCR. 4.1.6 The order in which the fields are processed The order in which the fields within a form are defined in the forms source file is the same order as the form driver subroutine TFRGET uses to get through the fields. Although the operator has complete control over the order in which he wants to enter data, the next and previous field of any field is defined by the order in the forms source file. 4.1.7 Default values Default values for fields, as defined in the forms source file, will be filled in the first time the form is displayed on the terminal screen (TFRPUT). If the default must be reset each time a TFRGET call is issued, the default value in the FCR can be restored by the TFRCLR call for update fields (keyword: UPD, VAR or UPD) before the TFRGET call is issued. Introduction to the form driver subroutines page 4-4 4.2 Form driver subroutines interaction with terminal operator While working with a TFR application, the terminal operator may feel that he is constantly in control of the form that is displayed on the screen. In fact, the operator has no control until your program allows it by issuing the form driver subroutine call for operator response: TFRGET This call put the operator in control until the requirements of the call are satisfied. For example, after your program issues the TFRGET call for a form, the operator can type and correct the responses on all the fields in the form as long as he wishes. The operator can also request help by using the help function. When the operator terminates the form by using the form terminating functions ENTER or RETURN, the form driver subroutines return control to the program. Then, until the program issues another call for operator response, the operator has nothing to do. After the application calls this routine, the cursor will be positioned at the field as specified in the argument list of the TFRGET call. Of no field name is specified the cursor will position at the first field of the form as defined by the order in the forms source file. 4.2.1 Field editing principles and functions Table 1 summarizes the field editing functions that the form driver subroutines provide, and lists the keys that control the functions. These functions are executed entirely by the form driver subroutines. The described function keys are available on any VT100-compatible terminal, without using the alternate key-pad mode. Introduction to the form driver subroutines page 4-5 Table 1: Field editing keys, functions, and usage for the form driver subroutines. ------------------------------------------------------------ Key Function Usage ------------------------------------------------------------ Left-arrow Cursor left Moves the cursor to the prece- ding character position within the field. Right-arrow Cursor right Moves the cursor to the next character position within the field. DELETE Erase character In the INSERT mode, erases the character at the cursor's left and closes the space. In the OVERSTRIKE mode, moves the cursor to the preceding character position within the field but erases it only when it is the last character in the field. LINEFEED Erase field Erases the entire field. PF1 INSERT/ Switches from the INSERT mode OVERSTRIKE to the OVERSTRIKE mode, or vice versa. PF2 HELP Display help text for the cur- sor's field. Most Insertion Keys for the printing charac- keyboard ters on the keyboard insert keys their characters. ------------------------------------------------------------ Introduction to the form driver subroutines page 4-6 4.2.1.1 Erasing a character: DELETE VT100 key: The Delete key on the keyboard. The DELETE function normally erases the character that is to the left of the cursor. The function has different effects, however, in the INSERT and OVERSTRIKE modes. The modes are explained in detail furtheron in this manual. In the INSERT mode, the DELETE function erases the character to the left of the cursor and closes up the space. In the OVERSTRIKE mode, the DELETE function always moves the cursor one character to the left. However, to prevent an operator from accidentally introducing errors, the function does not erase a character in the OVERSTRIKE mode except for the rightmost character. Errors: The Delete function is invalid when the cursor is at the leftmost position of the field. 4.2.1.2 Erasing a field: LINEFEED VT100 key: The Linefeed key on the keyboard. Regardless of the cursor's position in a field, the LINEFEED function erases all of the characters that are in that field. The form driver subroutines then display the field with spaces. When the function is complete, the cursor is located at the initial position (the leftmost character) for the field. Errors: The Linefeed function is always valid input in a field. 4.2.1.3 Moving cursor to the right: Right-arrow key VT100 key: The right-arrow key (->) on the keyboard. The right-arrow function moves the cursor one character to the right within the field. Errors: The right-arrow function is invalid when the cursor is to the right of the rightmost character in the field. Introduction to the form driver subroutines page 4-7 4.2.1.4 Moving cursor to the left: Left-arrow key VT100 key: The left-arrow key (<-) on the keyboard. The left-arrow function moves the cursor one character to the left within the field. Errors: The left-arrow function is invalid when the cursor is on the leftmost character of a field. 4.2.2 Switching the modes: INSERT / OVERSTRIKE VT100 key: The PF1 key on the keypad. While the operator is typing a field value, the INSERT and OVERSTRIKE insertion modes control how the form driver subroutines display the characters. The operator can control the insertion mode by using the INSERT/OVERSTRIKE function. When either the operator or your program moves the cursor to a field, the form driver subroutines set the default insertion mode: OVERSTRIKE. While the operator types in the INSERT mode, the form driver subroutines insert each character at the cursor's position. The cursor, the cursor's character, and all characters within the field that are to the right of the cursor are shifted to the right. In the OVERSTRIKE mode, the form driver subroutines replace the cursor's character with the character tyuped and moves the cursor to the right. The INSERT/OVERSTRIKE function switches the insertion mode from one to the other. For example, when the initial setting is OVERSTRIKE mode, pressing the PF1 key once switches to INSERT mode and pressing it again switches back to OVERSTRIKE mode. Errors: The INSERT/OVERSTRIKE function is always valid input in a field. Introduction to the form driver subroutines page 4-8 4.2.3 Field terminating fuctions The field terminating functions for the form driver subroutines are the functions with which the operator signals that he wants to work with a different field or a different form. Next sections describe the effects of the terminal functions. Table 2 summarizes the field terminating functions that the form driver subroutines provide, and lists the keys that control the functions. The described function keys are available on any VT100-compatible terminal, without using the alternate key-pad mode. Table 2: Field terminator keys, functions, and typical effects. ------------------------------------------------------------ Key Function Usage or meaning ------------------------------------------------------------ ENTER Return control Terminates all entries in the or RETURN form and returns control to the application program. TAB Cursor to Moves the cursor to the initial next field position of the next field, or acts like ENTER and RETURN according to the arguments in the form driver subroutine call Valid only when the current field is not the last field in the form that is not diplay- only. BACKSPACE Cursor to Moves the cursor to the initial previous field position of the previous field, or is not accepted according to the arguments in the form driver subroutine call. ------------------------------------------------------------ Introduction to the form driver subroutines page 4-9 4.2.3.1 Signaling form is complete: ENTER and RETURN VT100 keys: The Enter key on the keypad and the Return key on the keyboard both control this terminator. The ENTER and RETURN functions signal that the operator has completed the current form. The operator uses either function when he does not want to enter or change any field values. After the operator types one of these keys, control is returned to the program which issued the TFRGET call. Errors: The Enter and Return function is always valid input in any field. 4.2.3.2 Moving cursor to the next field: TAB VT100 key: The Tab key on the keyboard. The effect of the TAB function depends on the argument settings for the form driver subroutine call being executed. According to the argument values, the form driver subroutines can process the function directly and moves the cursor to the initial position of the next non display-only field (normal action). The order in which the form driver subroutines move from field to field is described elsewhere in this manual. If the argument setting indicates so, the form driver subroutines transfer control to the application program as soon as the operator uses the TAB function. In this case the TAB function acts exactly the same as the ENTER, RETURN and BACKSPACE function. Errors: The Tab function is invalid when the cursor is in the last non display-only field of the form and normal action (go to next field) is requested. Introduction to the form driver subroutines page 4-10 4.2.3.3 Moving cursor to the previous field: BACKSPACE VT100 key: The Backspace key on the keyboard. The effect of the BACKSPACE function depends on the argument settings for the form driver subroutine call being executed. According to the argument values, the form driver subroutines can process the function directly and moves the cursor to the initial position of the previous non display-only field (normal action). The order in which the form driver subroutines move from field to field is described previously in this manual. If the argument setting indicates so, the form driver subroutines transfer control to the application program as soon as the operator uses the BACKSPACE function. In this case the BACKSPACE function acts exactly the same as the ENTER, RETURN and TAB function. Errors: The Backspace function is invalid when the cursor is in the first non display-only field of the form and normal action (go to previous field) is requested, or when argument setting indicates so. 4.3 Simultaneous display of multiple forms You can, if you wish, display more than one form at the same time. If the forms do not use the same screen positions, it is possible to display two ore more forms simultaneously by using the TFRPUT call with partial clearance of the screen. Keep in mind, however, that the form driver subroutines know about only the last form specified by the TFRPOS call, which therefore must be used for switching the forms when alternately references are made to the fields of different forms. CHAPTER 5 Form driver subroutine calls A flexible set of form driver subroutines provide functions that display forms, display data in fields, and handle terminal input. The descriptions below show what each call does, what input arguments it requires, and what output it returns to your program. For each call, syntax is indicated. 5.1 TFRCLR - clear screen The form driver subroutine clears the terminal screen and the FCR entirely or partially. CALL TFRCLR (keyword) where: keyword is an INTEGER value indicating the row number from which the screen must be cleared (if zero no clearance will be done), or a STRING containing one of the following keyword parameters: ALL - clear the entire screen VAR - clear display-only and update fields and reset default field values. DON - clear display-only fields. UPD - clear update fields and reset default field values. Form driver subroutine calls page 5-2 5.2 TFRDEF - fill/change default field value The form driver subroutine fills/overrides the contents of the FCR with given data. CALL TFRDEF (field, data) where: field is a STRING containing the name of the field. data is a STRING containing data to fill the FCR with. 5.3 TFRFLD - output field value The form driver subroutine displays data in a specified field and, in case of an update field, puts that data in the FCR. 5.4 TFREND - close library and clear video attributes This routine should be the last TFR-call in the program before the program exits and must be used under RT11 before chaining to another program. CALL TFREND 5.5 TFRFLD - output field value The form driver subroutine displays data in a specified field and, in case of an update field, puts that data in the FCR. CALL TFRFLD (field, data) where: field is a STRING containing the name of the field. data is a STRING containing the data to be displayed and eventually the FCR being filled with. Form driver subroutine calls page 5-3 5.6 TFRGET - get all field values from screen The form driver subroutine takes care of all keyboard handling until a field terminating character is entered by which control is returned to the application program. CALL TFRGET (field, flag, [retchar]) where: field is a STRING containing the field name on which leftmost character the cursor is positioned. If it is a null-string, the first field of the form is assumed. flag is an INTEGER flag indicating: 0 - full screen entry : normal TAB and BACKSPACE function (cursor to next resp. previous field). 1 - single field entry : TAB and BACKSPACE function acts the same as ENTER and RETURN function retchar is an INTEGER catching the ASCII value of the terminating character. This argument is only used as flag=1 5.7 TFRMES - put message on screen The form driver subroutine displays a message on the error/help-message screen position (row 24 column 1). After any entered field terminating character, when executing TFRGET, the message will be cleared. If the message is a null-string, the help text for the specified field will be displayed, in which case the field name must be present. CALL TFRMES (message, field) where: message is a STRING containing the message or a null-string. field is a STRING containing the field name whose help text, as defined in the forms source file, must be displayed. Must be filled if message is a null-string, may be a null-string if message is not a null-string. Form driver subroutine calls page 5-4 5.8 TFROPN - open forms library file The form driver subroutine opens the specified forms library file on a given logical unit number. CALL TFROPN (file, unit) where: file is a STRING containing the name (max. 6 characters), eventual with device but without the extension of the forms library file wanted. The extension ".FEX" will be assigned by the subroutine. unit is the INTEGER logical unit number for the file. 5.9 TFRPOS - choose a form from the forms library The form driver subroutine searches the forms library file for the specified form and initializes the FCR. CALL TFRPOS (form) where: form is a STRING containing the form name (max. 6 characters). 5.10 TFRPUT - output all values The form driver subroutine displays fix and update fields, and eventually initialized (=blank) display-only fields. CALL TFRPUT (keyword, row) where: keyword is a STRING containing one of the following keyword parameter: ALL - display fix, blank display-only and update fields. FIX - display fix fields. DON - display blank display-only fields. UPD - display update fields. VAR - display blank diplay-only and update fields. row is an INTEGER row number from which the screen will be cleared before displaying any fields. If less or equal zero no clearance will be done. Form driver subroutine calls page 5-5 5.11 TFRRES - return values to application program The form driver subroutine returns a data string of one field or a string with the concatenated data strings of all fields. CALL TFRRES (field, result, trimflag) where: field is a STRING containing the name of the field, or a null-string. result is a STRING containing the data of the specified field (field is not a null-string), or the concatenated data strings of all fields (field is a null-string). trimflag is a INTEGER to indicate whether "result" is trimmed (i.e. trailing spaces are deleted) or not (1 resp. 0). CHAPTER 6 Software example TFR programs must be written according to the rules of the specific language used. Programmers should consult their language reference manual for this information. The next step to running an TFR application is linking the program to the form driver subroutines library so that the calls to the form driver subroutines will be processed. 6.1 Create forms source file Create a forms source file (DEMO.FRM), using any available text editor, with following contents: FRM , EMPLOY FIX , 3/10,, Employee information FIX , 4/10,, ==================== FIX , 7/1 ,, Salary number: FIX , 8/1 ,, Employee name: FIX , 9/1 ,, Street : FIX ,10/1 ,, Town : FIX ,11/1 ,, Salary : UPD , SALNUM , 4 , 7/16, RV UPD , NAME , 25 , 8/16, BO UPD , ROADNR , 25 , 9/16 UPD , CITY , 20 ,10/16 DEF , London W-1 UPD , SALARY , 8 ,11/16, BL HLP , Enter salary per month Software example page 6-2 6.2 Create forms library file Compile this forms source file using the TFR compiler, creating a library file (DEMO.FEX) with one form, and the forms document list file (DEMO.FLS). RUN TFR TFR-forms compiler - V1.1 dd-mmm-yy time hh:mm:ss RT11 RSX Source file : DEMO Source file : DEMO Device Library file : DK: Library file : Device Document file : DK: Document file: EMPLOY EMPLOY 6.3 Write FORTRAN IV application program Now create a FORTRAN IV test program: PROGRAM TFRDEM C BYTE SALNR(9) C CALL TFROPN ('DEMO',20) ! open library CALL TFRPOS ('EMPLOY') ! position at form CALL TFRPUT ('ALL',1) ! display form 10 CALL TFRGET ('',0) ! get field data CALL TFRRES ('SALNUM',SALNR,0) ! read key IF (ISCOMP(SALNR,'E') .EQ. 0) GOTO 20 C C Search in data base for existing data. C if not present: create entry in data- C base on key SALNR C if present : modify data C CALL TFRCLR ('UPD') ! clear screen GOTO 10 20 CALL TFREND END Compile this program and link it with the form driver subroutines library. CHAPTER 7 System internals Information on the TFR package, as described in the previous chapters, might in most cases do for understanding and using the form driver subroutines properly. For maintenance on the package and in special cases where linking in overlay is required, more information of the system internals might be useful. 7.1 System subroutines Besides the form driver subroutines previously described, there are two more subroutines in the package used by the form driver subroutines: TFRRU - reads a display-only/update field record and/or, in case of an update field record, the associated FCR. TFRFS - reads one to three text records and concatenates them in the string buffer in the TFRCOM common area. 7.2 System size The TFR subroutines use alltogether about 3.5 K words of memory plus .25 K words per I/O buffer used (=open logical unit number). Because not all form driver subroutines are necessarely used, this size can be reduced according to the specific application requirements. TFR uses a common area with the name TFRCOM and a size of 308 bytes (154 words) for the communication between the various form driver subroutines. System internals page 7-2 7.3 Overlay requirements All of the form driver subroutines may overlay one another. Only the two system subroutines TFRFS and TFRRU, which can overlay each other and which are called for in most of the form driver subroutines, must be accessable next to the largest form driver subroutine (TFRGET). If the linkage editor does not automatically places the common area TFRCOM in the root of the overlay structure, a common area as described in the previous section must be declared in the root-segment of the program. Table 3 shows which form driver subroutines issue calls for TFRFS/TFRRU, USERLIB- and/or SYSLIB-subroutines. Table 3: Subroutine calls of the form driver subroutines: cal \ by| TFR TFR TFR TFR TFR TFR TFR TFR TFR TFR -led \ | CLR DEF END FLD GET MES OPN POS PUT RES --------+------------------------------------------ TFRFS | X X X X TFRRU | X X X X X X X X | FATAL | X X X X X X X X X IGTJSW | X IGTKEY | X INPMOD | X PUTJSW | X RSWRIT | X X SCVTLU | X X X X X X X X SWRITE | X X X X X X X X TTBCLR | X | ISCOMP | X X X X X X X LEN | X X X X X X X SCOPY | X X X X X X X INDEX Backspace function, functions, 4-5 4-9 to 4-10, 5-3 keys, 4-5 BACKSPACE key, 4-10 principles, 4-4 Field terminating function, Change default, 5-2 4-4, 4-8 Clear screen, 5-1 Field terminator keys, 4-8 Common area, 7-1 to 7-2 File name, 5-4 Cursor movement, 4-4, extension, 3-1 to 3-2, 5-4 4-6 to 4-7, 4-9 to 4-10 Fix text, 2-2, 3-2 Form, 1-2, 4-1 Data item, 2-3 Form description, 1-2, separator, 2-3 2-1 to 2-2, 4-1 to 4-2 Default language, 1-1 to 1-2, data, 2-6, 3-2 2-1 to 2-3 value, 2-1 to 2-2, 4-2 to 4-3 record, 2-3 Delete function, 4-6 Form driver subroutines, DELETE key, 4-6 1-1 to 1-2, 2-1, 4-1, 4-4, 7-2 Display library, 6-1 to 6-2 data, 4-3 Forms field, 5-2 compiler, 1-1 to 1-2, 2-1, form, 4-2, 5-1 3-1, 6-2 help message, 4-1 document list file, 1-2, help text, 1-2, 4-3 2-1 to 2-2, 3-2, 6-2 multiple forms, 4-2, 4-10 library, 1-2, 2-2, 3-2, 5-4, Display-only field, 2-5, 3-2 6-2 source file, 1-1 to 1-2, Enter function, 4-9 to 4-10 2-1 to 2-2, 6-1 ENTER key, 4-9 Erasing Help a character, 4-6 function, 2-7, 4-3 to 4-4 a field, 4-6 message, 4-1, 5-3 Error, 3-3 request, 1-2, 4-4 fatal, 3-3 text, 1-2, 2-1 to 2-2, 2-7, message, 3-3, 5-3 3-2, 4-3, 5-3 warning, 3-3 Initial position, 4-6, FCR see field copy record 4-9 to 4-10 Field, 1-2, 2-1 to 2-3, 4-2 INSERT/OVERSTRIKE mode, data, 4-3 4-6 to 4-7 length, 2-2 name, 1-2, 2-2 to 2-3, 4-4 Left-arrow value, 4-3 function, 4-7 Field copy record (FCR), 4-3, key, 4-7 5-1 to 5-2, 5-4, 7-1 Linefeed function, 4-6 Field description data, 3-2 LINEFEED key, 4-6 Field editing Open forms library, 5-4 Order of processing, 4-3 to 4-4 Overlay requirements, 7-1 to 7-2 PF1 key, 4-7 PF2 key, 4-3 Record type code, 2-3 Return function, 4-9 to 4-10 RETURN key, 4-9 Right-arrow function, 4-6 key, 4-6 Screen form, 2-2 lay-out, 3-2 Size of the system, 7-1 System subroutine, 7-1 Tab function, 4-9 to 4-10 TAB key, 4-9 Text editor, 1-2, 2-1 to 2-3, 6-1 Update field, 2-6, 3-2, 4-3 Video attributes, 2-2 to 2-3