Dec 192017
 
MS-C5 Data entry screen design library v2.0.
File SCRNLIB2.ZIP from The Programmer’s Corner in
Category C Source Code
MS-C5 Data entry screen design library v2.0.
File Name File Size Zip Size Zip Type
BARMENU.C 4746 1471 deflated
BIOS.LNK 104 70 deflated
EXAMPLE.C 1831 684 deflated
EXAMPLE.EXE 29408 18774 deflated
EXAMPLE.LNK 86 57 deflated
EXAMPLE.STR 1263 439 deflated
MANUAL.DOC 63717 17135 deflated
MBIOS.OBJ 267 256 deflated
MSCREEN.LIB 12967 5673 deflated
README.DOC 1360 634 deflated
SBIOS.OBJ 258 247 deflated
SCREEN0.C 2524 982 deflated
SCREEN1.C 5265 1513 deflated
SCREEN2.C 2958 1001 deflated
SCREEN3.C 2840 949 deflated
SCRNLIB.H 6732 2251 deflated
SSCREEN.LIB 12967 5480 deflated
SURVEY.DOC 1163 420 deflated

Download File SCRNLIB2.ZIP Here

Contents of the README.DOC file



December 1987


Requirements:

Microsoft C compiler, version 5.0
small or medium memory model
LINK.EXE version 3.60+
The linkage editor (LINK) provided with most versions of
MS/PC DOS <> be used.



This package contains object module libraries of function
to use when creating C programs using Microsoft's C compiler.

Files EXAMPLE.C, SCREEN1.C, SCREEN2.C and SCREEN3.C are the
source code files for the example program that is included.
The example program also documents screen function design and
data entry program design.


File "manual.doc" is the manual for the functions.

The design shown in the example program is simple. A "real
world" application will require a complex control center,
probably with database function calls.


To create the example program, compile the four C source code files.
(Microsoft's C compiler version 5.0 was used to create the functions
in the library. Use the small memory model.) Link the files using the
command:

LINK @EXAMPLE.LNK

The linkage editor response file EXAMPLE.LNK assumes SSCREEN.LIB is in
the current directory or that an environment variable has been set
so that the linkage editor can locate the file SSCREEN.LIB.



Contents of the MANUAL.DOC file



December 1987


Requirements:

Microsoft C compiler, version 5.0
small or medium memory model
LINK.EXE version 3.60+
The linkage editor (LINK) provided with most versions of
MS/PC DOS <> be used.



This package contains object module libraries of function
to use when creating C programs using Microsoft's C compiler.

Files EXAMPLE.C, SCREEN1.C, SCREEN2.C and SCREEN3.C are the
source code files for the example program that is included.
The example program also documents screen function design and
data entry program design.


File "manual.doc" is the manual for the functions.

The design shown in the example program is simple. A "real
world" application will require a complex control center,
probably with database function calls.


To create the example program, compile the four C source code files.
(Microsoft's C compiler version 5.0 was used to create the functions
in the library. Use the small memory model.) Link the files using the
command:

LINK @EXAMPLE.LNK

The linkage editor response file EXAMPLE.LNK assumes SSCREEN.LIB is in
the current directory or that an environment variable has been set
so that the linkage editor can locate the file SSCREEN.LIB.







SCREEN PROGRAM DESIGN AND SOFTWARE LIBRARY

VERSION 2.0

December 1987

DAR Research
P.O. Box 11095
Milwaukee, WI

Copyright (c) 1986, 1987 by Dean A. Roth
All Rights Reserved


Screen Lib is a set of functions for C software to create screens
that perform (limited) edited data entry. The programmer is
freed from repeating code to test the validity of a field's
contents on a character basis. The programmer must still provide
range tests. This software is oriented toward the experienced
applications developer.

Two methods are available for writing to the screen: direct video
memory access and BIOS functions. Direct video memory access is
very fast, producing almost instantaneous displays. However, this
mode is not compatible with all non-IBM[1] computers. Screen
access through BIOS functions is compatible with all non-IBM
computers, but much slower than direct video memory access.
























____________________

[1]International Business Machines Corporation


- i -










Table of Contents

WARRANTY.................................................. IV

LICENSE................................................... V

VERSION AND REVISION INFORMATION.......................... VI

INTRODUCTION.............................................. VII

COMPILER OPTIONS.......................................... 3
Small Memory Model...................................... 3
Medium Memory Model..................................... 3
LINK.................................................... 3
BIOS Level I/O.......................................... 4

EFINPUT() - EDITED FIELD INPUT............................ 5

CONTROL KEYS.............................................. 7
Programmer Defined...................................... 7
Pre-Defined............................................. 8

INPUT FIELD ATTRIBUTES.................................... 10

OUTPUT FIELD ATTRIBUTES................................... 15

DISPS() - DISPLAY SCREEN.................................. 16

DISPIF() - DISPLAY INPUT FIELD............................ 17

DISPOF() - DISPLAY OUTPUT FIELD........................... 18

DISP_HELP() - DISPLAY HELP SCREEN......................... 19

PRINTEM() - PRINT ERROR MESSAGE........................... 20

PRINTMSG() - PRINT ERROR MESSAGE WITHOUT BELL............. 21

GETKEY() - RETURN CHAR OR CONTROL KEY (SCREEN LIB CODE)... 22

DISPLAY ATTRIBUTES........................................ 23

LIMITS AND RESTRICTIONS................................... 24

CAUTIONS - HOW TO STAY OUT OF TROUBLE..................... 25

EXAMPLE PROGRAM........................................... 26

MISCELLANEOUS FUNCTIONS................................... 27
dmprint() - Direct Memory PRINT......................... 27
barmenu() - Create Horizontal "Bar" Menu................ 28
access()................................................ 30
beep().................................................. 31



- ii -









UPDATES AND SUPPORT....................................... 32

ORDER FORM................................................ 33

INDEX..................................................... 34



















































- iii -







WARRANTY


DAR Research and Dean A. Roth make no warranties, either express
or implied, that this software will be error free. DAR Research
and Dean A. Roth make no warranties concerning the suitability of
this software for any particular application. In no event shall
DAR Research or Dean A. Roth be held liable for any direct or
indirect damages claimed to be caused by use of this software.
This includes, but is not limited to, loss of profit, business,
interruption of business, or anticipation of profit.

If you do not like the software, erase it.











































- iv -









LICENSE


The software in the object module libraries can be included in
commercial software without any royalties. The complete set of
software, source and object, included in this package can be
reproduced and shared with other people on the condition that
there is NO CHARGE for any copy and that all associated files are
included.

No donations, royalities or other fees are requested or required
to use this software in personal or commercial software.

Corporations are not required to purchase any "site license".
However, purchasing a copy of the source code is recommended.
See the "Updates and Support" chapter for details.

A purchaser of the source code is restricted from copying Screen
Lib source code in any manner with the intention of selling the
source code. The source code cannot be distributed via any medium
(diskette, bulletin board service, etc.) with or without charge
except by DAR Research.

Correspondence should be directed to the address shown below.

DAR Research
C/O
Dean A. Roth
P.O. Box 11095
Milwaukee, WI 53211

The files listed below should be included:

- readme.doc
- survey.doc
- manual.doc
- sscreen.lib
- mscreen.lib
- scrnlib.h
- barmenu.c

- example.c
- example.str
- example.lnk
- example.exe
- screen0.c
- screen1.c
- screen2.c
- screen3.c

- bios.lnk
- sbios.obj
- mbios.obj



- v -









VERSION AND REVISION INFORMATION


The software contained in the object module library is intended
for C software compiled with Microsoft's[2] C compiler version
5.0, and Microsoft's linkage editor (LINK) version 3.60 or
higher. Other linkage editors may be compatible.

Version 1.0 July 1986
Initial release.

Version 1.1 August 1986
Corrected error with input fields having "Y,N" attribute.
Under version 1.0, neither Y or N would be accepted.

Version 1.2 July 1987
Eliminated "snow" on CGA/EGA displays. Writing directly to
the display buffer for CGA and EGA displays can cause
"snow/static" to appear on the display.

Changed named of file "console.h" to "efinput.h".

Function clrscr() (clear screen) now also homes the cursor
(upper left corner).

Version 2.0 December 1987
Ported to Microsoft's MS-DOS C compiler version 5.0.

Combined "efinput.h" and "ibmpc.h" into one include file,
"scrnlib.h".

Added "medium" model library.

Functions Added:

- barmenu() - create "bar" menus as in EXAMPLE.EXE

- disp_help() - display help screen

- getkey() - return character or Screen Lib code for
control key

- printmsg() - print msg on "message line" without bell

- BIOS video access support. Functions sbios and mbios use
BIOS routines rather than direct video memory access.
This is compatible with all DOS computers, though slower
than direct video memory access.



____________________

[2]Microsoft Corporation


- vi -









INTRODUCTION


Screen Lib is a collection of functions to simplify creating data
entry screen. The functions are "table driven", with the
objective to simplify software creation and maintenance.

A screen is composed of fields. "Output" fields can only be
displayed, such as prompts like "Last Name". "Input" fields are
fields where data will be entered by a computer user.

Each field in a screen is assigned attributes, such as whether is
it an output or input field. Other attributes include the row and
column where a field will begin display, the length of the field
and the video display mode (normal, reverse, blink, etc.)

Input fields have attributes to define and limit the set of legal
characters. For example, the character set for numeric fields
should be restricted to digits 0 - 9, "+" and "-", and possibly a
decimal point.

The console interface functions bypass the operating system's
console I/O and write directly to the screen buffer to produce
nearly instantaneous screen displays and updates.

One structure, "struct outfield", defines an output field. An
array of output field structures defines an "output screen", or
the prompts for a screen. Structure "infield" defines an input
field. An array of input fields defines an "input screen", or the
data entry fields of a screen. Input and output fields together
define a data entry screen.

An output screen (an array of output fields) can be defined and
used separately from input fields. For example, a help screen
would consist of only output fields.

A function is provided to display an output screen (output
fields): dispof(). Function dispif() displays an input screen
(input fields). Function disps() displays a data entry screen:
input and output screen/fields.

Function efinput() is used for "edited" data entry. It will
permit only the characters of the specified character set to be
entered for a particular input field, and only the number of
specified characters can be entered. Also, additional attributes
that can be assigned to a field can make a field "required",
meaning a value must be entered or efinput() will signal that an
error has occured. (See the chapter on input field attributes for
a description of all input field attributes.)

The software is provided in two object module libraries:
SSCREEN.LIB and MSCREEN.LIB, which correspond to Miscrosoft's
small and medium memory models. Also see the chapter "Compiler
Options".


- 1 -









Screen Lib uses direct video memory access by default. This is
not compatible with all non-IBM DOS computers, such as the AT&T
6300. Incompatibility amounts to the screen not appearing
correctly or nothing being displayed at all.

BIOS access functions are provided with Screen Lib as an
alternative to direct video memory access. BIOS access is
compatible with all non-IBM computers. Screen displays will be
slower, though, as the BIOS functions are much slower than direct
video memory access.

The linkage editor command file BIOS.LNK can be used to link the
example program in small memory model using the alternative BIOS
function.

See the "compiler" chapter for more information about using the
BIOS functions rather than direct video memory access.

File "scrnlib.h" will be required in your applications. It
contains structure definitions and #defines.

One of the Screen Lib libraries (MSCREEN.LIB for "medium" memory
model, and SSCREEN.LIB for "small" memory model) must be
specified as the first library to be searched by the linkage
editor when creating your own programs. See file "example.lnk"
for an example LINK command file.






























- 2 -









COMPILER OPTIONS


Screen Lib is provided in "SMALL" and "MEDIUM" memory models, in
SSCREEN.LIB and MSCREEN.LIB, respectively. The compiler options
listed below must be used in order to successfully compile, link,
and execute a program using Screen Lib.



SMALL MEMORY MODEL

Small memory model allows 64KB for code and 64KB for data.

The following Microsoft compiler (version 5.0) options were used
to create the object module library:

-G0 -AS -Za -Zp -Ox

Details on each option can be found in your compiler's manual.



MEDIUM MEMORY MODEL

Medium memory model allows 1MB of program and 64KB of data.
Programs are actually limited to less than 1MB since DOS can only
address 640KB.

The compiler options listed below must be used in order to
successfully compile, link, and execute a program using the
medium memory model of Screen Lib.

-G0 -AM -Za -Zp -Ox

Details on each option can be found in your compiler's manual.



LINK

Use the linkage editor (LINK) supplied with the C compiler.
Version 3.60 (or higher) *MUST* be used. The version of LINK
supplied with DOS may not work correctly. Specify the appropriate
memory model version of the Screen Lib library (SSCREEN.LIB or
MSCREEN.LIB) to be the first library, as in the example program
link command file "EXAMPLE.LNK".









- 3 -









BIOS LEVEL I/O

Direct video memory writes are not compatible with all computers.
A replacement function is provided that uses BIOS functions to
put characters on the screen. This is compatible with all IBM
compatibles.

File SBIOS.OBJ is for use by small memory model programs. File
MBIOS.OBJ is for use by small memory model programs. You must
specify the appropriate file as one of the object modules to be
linked into your program: the files are not in the libraries.
See file BIOS.LNK for an example LINK command (response) file
that specifies SBIOS.OBJ.

You must use the LINK option "/NOE" when either BIOS function is
to be be used, as in the example linker command file BIOS.LNK.








































- 4 -









EFINPUT() - EDITED FIELD INPUT


Efinput() performs character level editing. It detects when an
illegal character has been entered. Programmer written code must
detect range errors (value too small, too large, etc.).

Input fields are defined as an array of structures of type
"infield". Each input field is assigned several attributes when
it is defined. For example, one attribute specifies the legal
character set. (Character set options are described in chapter
"INPUT FIELD ATTRIBUTES" under topic "Icharset".) Another
attribute specifies if decimal places are permitted. If a
character is not a member of the specified character set, a
message will be printed on the error message line (line 24) and
the bell will beep. For example, only digits, "-", "+" and
sometimes a decimal point are valid for numeric fields. All other
characters are illegal for numeric fields.

Fields will be processed in the order in which they are defined.

Function efinput() operates in two modes. One mode is the typical
data entry mode. The cursor stops at each active input field and
the program pauses until data is entered. A second mode, called
fast forward, causes each field to be edited, but the program
will not pause for data entry until the end of the current screen
is reached or an edit error is detected. The fucntion can detect
certain types of errors, such as an empty field that requires
data to be entered. Programmer written code must detect other
types of errors, such as range errors.

SYNOPSIS

int efinput(fieldptr, field, nfields, error)

struct infield *fieldptr; /* pointer to input field structure */
int *field; /* current field being processed */
int nfields; /* total number of fields */
int error; /* When non-zero, exit fast forward mode */

Arguments to efinput() are:

fieldptr
Pointer to the first "infield" structure in an array.
Typically this would simply be the name of the input field
array. If a screen has one input field rather than several
fields, then use the "&" operator (address of).

field
Pointer to an int which records the current field being
processed. Fields are always numbered from zero (beginning
with offset zero into the array of input field structures).
Notice that the address, not the value, is passed to
efinput(). The value of "field" can be altered by efinput().


- 5 -










nfields
The number of fields in the input field array. The value must
always be the total number of fields, not the number ON
(active) or anything else. This value is best calculated by
the compiler using a macro like:

#define NFIELDS(x) (sizeof(x)/sizeof(x[0]))

The value will always be determined at compile time, and it
will always be correct nomatter how many changes are made to
the input fields.

error
The "error" argument to efinput() must be non-zero when
programmer written code detects an error, and zero to
indicate "no error". A non-zero value signals efinput() to
deactivate fast forward mode if the mode is active.

The "error" variable should be reset to zero immediately
after return from efinput().

The "error" variable can be used in any manner. One possible
implementation is for it to contain to number of an error
message. An error message function could then retrieve the
appropriate message from a message database. (Putting error
messages in a file helps assure consistency between
programs.)

See the chapter "INPUT FIELD ATTRIBUTES" for a detailed
description of structure "infield" and all input field
attributes.
























- 6 -









CONTROL KEYS


Some control keys must be implemented by the programmer. Other
control keys have a pre-defined meaning. The source code for the
example program shows one implementation of programmer defined
control keys.



PROGRAMMER DEFINED

Escape
Cancel operation command. The original contents, if any, of
current field are restored and control returns to the
function that called efinput() with the return code "CANCEL".
Escape, therefore, also acts as an "undo" command. Case
"CANCEL" must be defined in the switch statement for
efinput()'s return code, as in the example program, for
CANCEL to be active.

The programmer must decide how to process CANCEL. It can be
ignored by making an entry in the switch statement on the
return value from efinput() for CANCEL that is a "continue"
statement. Data entry will then continue with the same field,
and escape will be an "undo" command.

PgUp
"PgUp" is often used to signal that the previous screen, if
any, is wanted. The example program shows one possible
implementation. The programmer can choose a different
implementation for PgUp. When PgUp is pressed, the actions
listed below will occur for any and all programmer defined
implementations for PgUp.

The original contents, if any, of the current field are
restored and control is returned to the function that called
efinput() with the return code "PREVSCREEN". PgUp,
therefore, acts as an "undo" command, too.

PgDn
"PgDn" is usually used to signal that the next screen is
wanted, and it activates "fast forward" mode. PgDn also acts
like RETURN and terminates data entry, unless an input field
attribute rule is violated or edit code in the user written
function that calls efinput() detects an error. The function
returns with the return code RETURN.

An error detected in user written code is passed to efinput()
through argument "error". The argument is an int, and
"error" should be non-zero to indicate that an error occured.
The "error" argument should be reset to zero immediately
after return from efinput(), as in the example screen
functions.


- 7 -










F1 - F10
Function keys must be programmer implemented. Function keys
must be enabled by specifying FFKEY in the Iflags attribute.
If FFKEY is not specified for a field, keys F1 through F10
will be ignored.

When function keys are enabled, pressing a function key will
produce this action: the original contents of the current
field will be restored and control will be returned to the
function that called efinput(). The return code will be F1KEY
through F10KEY, whatever is appropriate. Function keys,
therefore, can also act as an "undo" command.

See file "screen1.c" for an example of a simple
implementation of F1 as a context sensitive help key.



PRE-DEFINED

Home
"HOME" is used to go to the first input field of the current
screen. Case "HOME" must be defined in the return code switch
statement for efinput(), as in the example program, in order
for "HOME" to be active.

The original contents, if any, of the current field are
restored, the "current field" variable (argument "field" to
efinput()) is set to zero (first field), and control is
returned to the function that called efinput() with return
code "HOME".

Up arrow
The "up arrow" key is used to select a prior field (move the
cursor to the first previous active field). This is a "go to
previous field" command.

The original contents of a field are always restored before
any action is undertaken. Therefore, "up arrow" acts as an
"undo" command.

The first field must never be turned OFF (Ionoff must always
be ON).

Down arrow
The "down arrow" key is treated exactly as the RETURN/ENTER
key.

Return/Enter
The RETURN/ENTER key is used to signal the end of data entry.
If a field has the REQ attribute, an error occurs if no data
has been entered.



- 8 -









The down arrow and tab keys act exactly the same as the
RETURN/ENTER key.

Tab
Acts exactly the same as the RETURN/ENTER key.

BackTab
Acts exactly the same as the up arrow (previous field) key.
Backtab is shift-tab.

Backspace
Erases the character to the left of the cursor. If the cursor
is at the left margin of the field, then the character under
the cursor will be erased.

Del
Erases the character under the cursor, if any. Characters to
the right of the cursor will be moved left.

space - numeric fields
The space bar acts the same as the "Del" key for numeric
fields.


































- 9 -









INPUT FIELD ATTRIBUTES


Structure "infield" is listed below. It defines an input field.
Each structure member is an attribute. Each attribute is
described below.

struct infield
{
char Ionoff;
char Irow;
char Icolumn;
char Iwidth;
char Idattr;
char Ifieldtype;
char Idecimals;
char Icharset;
char Iflags;
char *Ivalid;
union alltypes *Ivarptr;
};

Ionoff
Two legal values: ON and OFF. The contents of an input field
will be displayed when a field is ON and the contents of
Ivalid is non-zero (field has valid data). Data entry is
enabled when ON. Data entry is disabled when OFF (cursor will
skip field).

ON and OFF are defined in file "scrnlib.h".

Irow
The row on the screen where display will occur. Rows are
numbered 1 through 25. A field should reside on one row.

Icolumn
The column on the screen where display will begin. Columns
are numbered 1 through 80.

Iwidth
The width - maximum number of characters that can be entered
- of a field.

Caution must be exercised. If a field is an integer value
and ints have a range of 32767 to -32768, then an int field
should be restricted to four characters. A five character int
field may not return the expected result. If a field is a
character array, the variable must be one greater than the
width for the NULL ('\0') character.

Fields can vary from one to eighty characters. It is expected
that a field will reside on one row.

The width of a field will be delineated whenever a display


- 10 -









attribute is used that is visible when a space is printed.
For example, if display attribute UDIM (underscored dim) is
specified and a monochrome display controller is used, then a
field's width will be delineated by an underscore even when
the field does not contain any data.

Trailing spaces in character array fields are truncated to
the first non-space character.

Idattr
The display attribute for a field. The result of an attribute
depends upon the type of monitor that is installed. See
chapter "Display Attributes" for attribute options and
detailed information.

The width of a field will be delineated whenever a display
attribute is used that is visible when a space is printed.
For example, if display attribute UDIM (underscored dim) is
specified and a monochrome display controller is used, then a
field's width will be delineated by an underscore even when
the field does not contain any data.

Ifieldtype
This attribute identifies the data type associated with the
field. The data will be converted to this type. For example,
if a field is specifed to be type INT (int), then data will
be converted to int (binary) before being stored at the
location pointed to by attribute "Ivarptr".

The character set for a field must be consistent with the
data type. Therefore, a field type if INT (int) can consist
of digits and an optional sign: all other characters are
illegal. Also, the field width must not allow illegal
values. For example, if an "int" is two bytes, then a five
character wide INT field will allow values to 99999.
However, anything over 32767 would be invalid for a two byte
"int".

Field type tags are #defined in file "scrnlib.h" and listed
below.

TAG MEANING

INT Integer (int)
SHORT Short integer (short)
UNSIGNED Unsigned integer (unsigned)
LONG Long integer (long)
FLOAT Single precision floating point (float)
DOUBLE Double floating point (double)
CHAR Single character (char)
CARRAY Character array (string)





- 11 -









Idecimals
The number of decimal places for floating point values. If a
field's width is five and two decimal places are specified,
then two digits to the left of the decimal point can be
entered. Entry of a decimal point where it is illegal is
detected. Entry of more digits to the right of a decimal
point is detected and disallowed.

The position of a decimal point is automatically adjusted if
a negative or positive sign (- or +) is entered.

A decimal point is allowed in a numeric field when a value
other than zero is specified for the number of decimal
places. Otherwise a decimal point is not allowed in numeric
fields.

Icharset
This attribute specifies the valid character set for a field.
For example, a floating point field can include digits and a
decimal point, or only digits. Codes are:

CHARACTER SET
CODE DESCRIPTION COMMENT

0 Digits and '.' only Decimal places specified
-or-
Digits only No decimal places

1 Letters, digits or spaces
2 Letters or digits
3 Letters or spaces
4 Letters A-Z and a-z
5 Any printable character
6 Y or N Always uppercase

Letters are automatically converted to uppercase when the
FUCASE flag is specifed in the Iflags attribute.

If a character is not a member of the specified character
set, then one of the messages listed below will be printed on
line 24, the error message line. Error messages are:

ERROR MESSAGES

Digits and '.' only
Digits only
Letters, digits or spaces
Letters or digits
Letters or spaces
Letters A-Z and a-z
Any printable characters
Y or N
Decimal point already entered
Decimal point required


- 12 -









Max digits to right of decimal entered
Unknown character set type
'+' and '-' must be first character when used

When a non-supported key is pressed, the message is:

Key not supported

Function keys are active when FFKEY is specified in the
Iflags attribute. See screen function screen1.c for an
example usage of the F1 key as a help key (context sensitive
help).

Iflags
Six flags can be specifed. All can be specified at once,
though FNONE should be used alone.

FREQ
The FREQ flag indicates that data must be entered before
efinput() will relinquish control (except for certain
"control" function keys).

The message "A value must be entered" will be displayed
on the error message line (line 24) if data is entered
and the Return/Enter, Tab, down arrow or PgDn key is used
to exit a FREQ field.

FRREQ
The FRREQ flag specifies that the RETURN/ENTER key must
be pressed to exit the field. This is usually used with
FREQ.

If FRREQ is not specified, data entry will be terminate
for a field when the maximum number of characters for the
field, as specified in Iwidth, have been entered.

The message "Press RETURN/ENTER to continue" will be
displayed on the error message line (line 24), but the
bell will not beep.

FUCASE
The FUCASE flag forces all letters to be converted to
uppercase.

FFKEY
The FFKEY flag is used to indicate that function keys F1
through F10 are active for a field. A function key, such
as F1, might be used as a "help" key. See example screen
function screen1.c for an example help key
implementation.






- 13 -









FMFILL
Requires that the number of characters specified in
Iwidth be entered. Therefore if Iwidth is 4, four
characters must be entered. If not enough characters are
entered, the error message "Field must be filled" will be
displayed.

This flag implicitly makes a field required (FREQ). An
empty FMFILL field will be trapped when efinput() is in
"FAST FORWARD" mode, and reported as "Value required". An
FMFILL field can only have zero or Iwidth number of
characters.

FNONE
Use the flag FNONE when no flags are wanted.

Multiple flags can be specified through use of the bit-wise
OR operator (FREQ|FRREQ|FFKEY).

Ivalid
This attribute will be non-zero when a field has valid data,
and zero when a field contains garbage. This attribute should
always be tested before a field is used in a calculation or
report. The contents of the field are valid only when Ivalid
is non-zero.

Attribute Ivalid is a pointer. Consequently, whenever
reference is made the Ivalid being zero or non-zero, it
actually means the CONTENTS of Ivalid must be zero or
non-zero. Correct code to test for zero or non-zero would be:

if (*iscreen[field].Ivalid) /* field have valid data? */

For example, a character array field may contain a string,
but if the Ivalid attribute is zero, the data is not valid.
This is especially important when differentiating between
values of zero and garbage data. (Many programmers have used
zero to indicate a "missing" or garbage value. However,
there was no way to differentiate between an intentional
value of zero and zero meaning missing data.)

The value in Ivalid has no other meaning and should not be
used for any other purpose.

Ivarptr
Pointer to the variable where a field's data will be stored.
This pointer should be cast using macro "AD" for scalar
variables (non-arrays) and "ADA" for arrays. For example,
ADA(varname). Also see the example "screen" source code
files.






- 14 -









OUTPUT FIELD ATTRIBUTES


Structure "outfield" is listed below. The members of the
structure define the attributes for an output field.

struct outfield
{
char Oonoff;
char Orow;
char Ocolumn;
char Odattr;
char Owidth;
char *Otextptr;
};

Oonoff
Specifies whether the field should be displayed or ignored.
If the field is turned OFF, a width must be specified in
order for the field to be erased. A width of zero means to
display the field until all characters in the string pointed
to by Otextptr have been displayed (until the NULL character
- '\0' - is encountered).

Orow
The row on the screen where display is to begin. Rows are
numbered 1 through 25. An output field is expected to reside
on a single row.

Ocolumn
The column on the screen where display is to begin. Columns
are numbered 1 through 80.

Odattr
Display attribute. See chapter "Display Attributes" for
attribute options (DIM, BRIGHT, RDIM, etc.) and detailed
information.

Owidth
The maximum width for a field. Zero has the special meaning
to display until end-of-string (NULL character '\0'). Owidth
can range from 0 to 80.

If the specified width is greater than the length of the
string pointer to by Otextptr, the field will be padded with
spaces using the field's display attribute. This is
equivalent to "erase to end-of-field".

Otextptr
Pointer to a NULL terminated string (normal C string). The
string can be a NULL string. A NULL (empty) string can be
used to erase a field when a field width is also specified.




- 15 -









DISPS() - DISPLAY SCREEN


Displays a "screen". A screen is composed of output and input
fields. Functions dispif() and dispof() can be used to display
input and output fields, respectively, also.

SYNOPSIS

void disps(out, n_out, in, n_in);

struct outfield *out;
int n_out; /* number of fields */
struct infield *in;
int n_in; /* number of fields */


Typical usage:

static struct outfield oscreen[] =
{
(definition of fields)
};

static struct infield iscreen[] =
{
(definition of fields)
};


disps(oscreen, NFIELDS(oscreen), iscreen, NFIELDS(iscreen));


Macro "NFIELDS" is defined in file "scrnlib.h" to calculate the
number of fields (oscreen and iscreen are arrays of structures).





















- 16 -









DISPIF() - DISPLAY INPUT FIELD


Displays an "input" field as defined by structure "infield" in
file "scrnlib.h". Attributes for input fields are defined by
members of the structure "outfield". For a description of input
field attributes, see the chapter on function efinput().

Structure "infield" defines a field in which data will be
entered. Usually several fields will be defined in an array of
"infield" structures.

Function dispif() can be used to display all or any number of
fields in an array of infield structures.


SYNOPSIS

void dispif(fieldptr, nfields)

struct outfield *fieldptr;
int nfields; /* number of fields to display */


Typical usage:

static struct infield iscreen[] =
{

(definition of fields)

};


dispif(iscreen, sizeof(iscreen)/sizeof(iscreen[0]));
-or-
dispif(&iscreen[4], 1);
-or-
dispif(iscreen, NFIELDS(iscreen));

Macro "NFIELDS" is defined in file "scrnlib.h" to calculate the
number of fields.














- 17 -









DISPOF() - DISPLAY OUTPUT FIELD


Displays an "output" field (prompt) as defined by structure
"outfield" in file "scrnlib.h". Attributes for output fields are
defined by members of the structure "outfield".

Structure "outfield" defines an output only, or prompt, field.
These fields are usually the labels for data entry fields, such
as "Last Name". Usually several fields will be defined in an
array of outfield structures.

Function dispof() can be used to display all or any number of
fields in an array of outfield structures.

SYNOPSIS

void dispof(fieldptr, nfields)

struct outfield *fieldptr;
int nfields; /* number of fields to display */


Typical usage:

static struct outfield oscreen[] =
{

(definition of fields)

};


dispof(oscreen, sizeof(oscreen)/sizeof(oscreen[0]));
-or-
dispof(&oscreen[4], 1);
-or-
dispof(oscreen, NFIELDS(oscreen));

Macro "NFIELDS" is defined in file "scrnlib.h" to calculate the
number of fields.















- 18 -









DISP_HELP() - DISPLAY HELP SCREEN


Displays a "help" screen, which can be any "output" screen.

The sequence of events is:

1. Clear screen.

2. Display output screen using dispof().

3. Display prompt "Press RETURN/ENTER to continue." on error
message line.

4. Disable cursor (make cursor disappear).

5. Wait until RETURN/ENTER pressed.

6. Enable cursor (return cursor to normal DOS shape).

7. Clear screen.

See example screen "screen1.c" for usage.

SYNOPSIS

void disp_help(fieldptr, nfields)

struct outfield *fieldptr;
int nfields; /* number of fields to display */


Typical usage:

static struct outfield help_screen[] =
{

(definition of fields)

};


disp_help(help_screen, NFIELDS(help_screen));

Macro "NFIELDS" is defined in file "scrnlib.h" to calculate the
number of fields.










- 19 -









PRINTEM() - PRINT ERROR MESSAGE


Prints an error message on the "error message line", line 24, and
beeps the bell. The message is printed with display attribute
BRIGHT.

SYNOPSIS

void printem(msg);

char *msg;


Typical usage:

printem("Valid range is 5.00 - 99.99");

-or-

static char emsg[] =
{
"", /* never used - 0 == no error */
"message 1",
"message 2",
"message 3"
};

if (error)
printem(emsg[error]);

See the source code for the example screen functions (screen1.c,
screen2.c and screen3.c) for another example.























- 20 -









PRINTMSG() - PRINT ERROR MESSAGE WITHOUT BELL


Prints a message on the "message line", line 24, but does not
beeps the bell like printem(). The message is printed with
display attribute BRIGHT.

SYNOPSIS

void printmsg(msg);

char *msg;


Typical usage:

printmsg("No help available for this field");







































- 21 -









GETKEY() - RETURN CHAR OR CONTROL KEY (SCREEN LIB CODE)


Function getkey() reads the keyboard and returns one character or
a Screen Lib #defined code for a control key (RETURN, CANCEL,
F1KEY, etc.).

The DOS code for function keys actually consists of two
characters. Function getkey() will return a #defined (see
scrnlib.h) code for a function key, such as F1KEY.

One use for getkey() is to pause until the user presses a
specific key to resume. For example, wait until the RETURN/ENTER
key has been pressed after displaying a message.


printf("...message... Press RETURN/ENTER to continue.");

while (getkey() != RETURN)
;


SYNOPSIS

int getkey(void);































- 22 -









DISPLAY ATTRIBUTES


Six display attributes are defined.

EFFECT
ATTRIBUTE MONOCHROME DISPLAY COLOR DISPLAY
FOREGROUND BACKGROUND

DIM normal white on black normal white black
BRIGHT high intensity white on black red black
UDIM normal white underscored normal white blue
UBRIGHT high intensity white on black bright white blue
RDIM black on normal white normal white black
RBRIGHT black on normal white bright white black

The attributes are defined in two external arrays of data type
"int". The monochrome attributes are defines in A_MONO. The
color display attributes are defined in A_COLOR. Each array
consists of six integers. Each element has the meaning as the
order of attributes listed above (subscript zero is DIM,
subscript five is RBRIGHT).

New values can be assigned to the attributes, if desired. See a
technical manual for attribute options for monochrome and color
display controllers. New values could be assigned as indicated in
the code fragment listed below:

extern int A_MONO[6];

/* RBRIGHT is now non-display on monochrome displays */
A_MONO[5] = 0;
























- 23 -









LIMITS AND RESTRICTIONS


1. Values are not checked. Invalid attributes will cause
unpredictable behavior.

2. The first input field of each screen must always be ON.

3. The last input field of each screen must always be ON.

4. An input field must fit on one row.

5. An input field is limited to 80 characters.

6. A FRREQ field needs one extra space at its end. The cursor
will stop at that position when the field is filled with
characters until the RETURN/ENTER key is pressed.

7. Always check the Ivalid attribute of a field before using the
data. Attribute Ivalid is a pointer. Consequently, whenever
reference is made to Ivalid being zero or non-zero, it
actually means the CONTENTS of Ivalid must be zero or
non-zero. Correct code to test for zero or non-zero would be:

if (*iscreen[field].Ivalid) /* field have valid data? */































- 24 -









CAUTIONS - HOW TO STAY OUT OF TROUBLE


1. Know the limits (maximum and minium values and sign
extension) and size (number of bytes) of each C data type
(int, char, double, etc.).

2. Test attribute "Ivalid" before using data. Ivalid will be
non-zero when a field has valid data, otherwise it will be
zero.

Attribute Ivalid is a pointer. Consequently, whenever
reference is made the Ivalid being zero or non-zero, it
actually means the CONTENTS of Ivalid must be zero or
non-zero. Correct code to test for zero or non-zero would be:

if (*iscreen[field].Ivalid) /* field contain valid data? */

3. Reset attribute "Ivalid" to zero whenever a field is OFF. One
statement can perform this job. See the example screen
functions.

4. Add one extra byte for character arrays. The byte is used for
the terminating NULL ('\0') character. Use the coding
standard of writing "+ 1" when specifying the size of a
character array. For example, "char name[10+1];".

5. If you turn a field OFF, you must provide for turning it ON.

6. Use the correct version of the linkage editor (LINK).


























- 25 -









EXAMPLE PROGRAM


An example program is included in source and executable form. It
shows how to construct screens and a data entry, or screen,
program. The files are: example.c, example.str, screen0.c,
screen1.c, screen2.c and screen3.c. Include file "scrnlib.h" is
also needed, and is included in this package. The source code
files are ready to be compiled in "small" memory model. See the
chapter on compiler options to select the necessary options.

File "example.c" is the control center for the program. Action
is taken depending upon the return code from each screen, such as
"PgUp" as the command for the previous screen, if there is a
previous screen.

The example program shows one possible implementation of a
context sensitive help key in screen1.c.

Two levels of editing are used in screen two (screen2.c). There
is a pre-input edit and post-input edits. In the pre-input edit,
the value of a field prior to F_MODEL is checked. According to
the value of the prior field, field F_MODEL is either active (ON)
or inactive (OFF). When the field is OFF, the cursor will not
stop at the field. The Ivalid attribute should be reset (set to
zero) when an input field is inactive (OFF).

Each field is identified with a #defined tag, such as field
"F_MODEL". The use of tags to identify fields generally produces
more maintainable code. If fields are added or deleted, a
field's number need be changed in only one location, which
reduced the possibility of error.

The example program can also be compiled in "medium" memory
model, but the library name in EXAMPLE.LNK will have to be
changed from SSCREEN.LIB to MSCREEN.LIB.

Link the compiled functions using the "LINK" command file
"example.lnk": "LINK @example.lnk". The command file assumes all
object modules and libraries are in the current directory, and
uses the "small" memory model (SSCREEN.LIB) version of Screen
Lib.














- 26 -









MISCELLANEOUS FUNCTIONS



DMPRINT() - DIRECT MEMORY PRINT

Function dmprint() writes data directly to the active display
controller's buffer. Therefore, special characters, such as
control-g (bell), carriage return, line feed, etc., are not
recognized as special characters.

SYNOPSIS

void dmprint(row, column, width, attribute, buffer)

char row; /* 1 - 25 */
char column; /* 1 - 80 */
char width; /* 0 - 80 (zero has special meaning) */
char attribute; /* DIM, BRIGHT, etc. */
char *buffer; /* pointer to character string */




Typical usage:

dmprint((char) 24, (char) 1, (char) 80, BRIGHT, "Value required");

-or-

static char *msg[] =
{
"Value required",
"Invalid month",
etc.
};

dmprint((char) 24, (char) 1, (char) 80, BRIGHT, msg[error]);


















- 27 -












BARMENU() - CREATE HORIZONTAL "BAR" MENU

Function barmenu() creates a "bar" menu. The menu options are
listed on one line, while an explanation is displayed on another
line, similar to many popular software packages. For an example,
see the first screen the enclosed example program EXAMPLE.EXE
displays.

The function returns an integer that indicates which option was
selected: option numbering begins with "1". A return value of 0
(zero) indicates the "Esc" (or CANCEL) key was pressed. Using the
example given below, if the cursor is positioned over "Demo" and
the RETURN/ENTER key pressed, barmenu() will return integer 1.

Function barmenu() dynamically creates even spacing between
options. Thus, the spacing of options in the example program
included in this package will change if another option is added.

The "explanation" line is limited to 76 characters.

The source code for barmenu() is included (barmenu.c) as an
example of how Screen Lib functions can be used to create new
functions.

SYNOPSIS

int barmenu(options, count)

char *options[][2]; /* pointer to text */
int count; /* number of options */

Typical usage:

int choice;

static char *options[][2] =
{
"Demo", "Begin Screen Lib demonstration program",
"Help", "Brief introduction to Screen Lib",
"Quit", "Exit to DOS"
};

choice = barmenu(options, 3);

switch (choice)
{
case 0: /* CANCEL/ESC */
case 3: /* Quit */
(some code ...)
break;



- 28 -









case 1: /* Demo program */
(some code ...)
break;

case 2: /* Help */
(some code ...)
break;
}
















































- 29 -












ACCESS()

Access() can be used to determine if a file exists and if it can
be accessed with the specified mode. Access() will detect when a
drive is not ready under program control, avoiding DOS's message:

"abort, retry, ignore"

Access() can be used to test if a disk drive (or network virtual
drive) is ready (door open, no diskette, etc.).

If an error occurs (return of -1), check the external int "errno"
for the specific error (see error list "ERRNO.H"). Errors are
ENOENT and EACCES.

SYNOPSIS

int access(pathname, mode)

char *pathname; /* file pathname */
int mode; /* permission setting */
Modes
0 - check for existance only
2 - check for write permission
4 - check for read permission
6 - check for read and write permission

returns: 0 if file has given mode
-1 indicates file does not exist, or is not
accessable with the given mode

Examples:

if (access(filename, 0))
{
perror();
exit(1);
}

if (access(filename, 0))
switch (errno)
{
case EACCES : /* Drive not ready */
(code...)
break;

case ENOENT : /* file not found */
(code...)
break;
}



- 30 -












BEEP()

Function beep() beeps the computer's bell once.

SYNOPSIS

void beep(void);














































- 31 -









UPDATES AND SUPPORT


Support is available for registered users of Screen Lib.
Registration includes a copy of the source code. One year of
support will then be available (from date registration is
received). Support will be provided through written
correspondence. Telephone support is not available. Registered
users will also be informed of software updates, if any, for one
year. See the order form for price.

A diskette (360KB double sided MS/PC DOS format) with the latest
object module library version of Screen Lib can be purchased.
See the order form for details.










































- 32 -









ORDER FORM


Send To:

DAR Research
C/O
Dean A. Roth
P.O. Box 11095
Milwaukee, WI 53211
U.S.A.


Item Quantity Unit Price Total
------------------ -------- ---------- -------

Copy of latest software and manual ________ $15.00 _______
(360KB PC/MS DOS diskette)


Registration and purchase of ________ $50.00 _______
one copy of the source code
(360KB PC/MS DOS diskette)
plus 1 year of support through
written correspondence.
Total -------


All prices are in U.S. dollars.

Make checks or money orders payable to "Dean A. Roth".

Software will be delivered in approximately 4 weeks.



Name __________________________________________________
Address _______________________________________________
Address _______________________________________________
City _____________________________
State _____________________________
Zip ________________


Your current version of Screen Lib _________











- 33 -








Index



--- A ---

access(), 30
A_COLOR, 23
A_MONO, 23
AT&T 6300, 1
Attributes
Display, 23
Icharset, 12
Icolumn, 10
Idattr, 11
Idecimals, 12
Ifieldtype, 11
Iflags, 13
Input Fields, 10
Ionoff, 10
Irow, 10
Ivalid, 14
Ivarptr, 14
Iwidth, 10
Ocolumn, 15
Odattr, 15
Onoff, 15
Orow, 15
Otextptr, 15
Output Fields, 15
Owidth, 15



--- B ---

Backspace Key, 9
Backtab Key, 9
barmenu(), 28
beep(), 31
BIOS I/O, 2
BIOS Level I/O, 4
BIOS.LNK, 2, 4













- 34 -









--- C ---

Compiler Options, 3
Compiler Version, vi
Compiling, 3
Control Keys
Backspace, 9
Control keys
Backtab, 9
Control Keys
Del, 9
Down Arrow, 8
Escape, 7
F1 - F10, 8
Home, 8
PgDn, 7
PgUp, 7
RETURN/ENTER, 8
space bar, 9
Tab, 9
Up Arrow, 8



--- D ---

Data entry mode, 5
Del Key, 9
disp_help(), 19
dispif(), 17
Display Attributes, 23
Idattr, 11
Odattr, 15
dispof(), 18
disps(), 16
dmprint(), 27
Down Arrow Key, 8



--- E ---

EACCES, 30
efinput(), 5
ENOENT, 30
errno, 30
Error Message Line, 12, 13, 20
Escape Key, 7
example.c, 26
example.lnk, 26
Example Program, 26





- 35 -









--- F ---

F1 - F10, 8
Fast forward mode, 5, 6, 14
FFKEY, 13
Flags
FFKEY, 13
FMFILL, 14
FNONE, 14
FREQ., 13
FRREQ, 13
FUCASE, 13
FMFILL, 14
FNONE, 14
FREQ., 13
FRREQ, 13
FUCASE, 13
Function Keys, 8, 13



--- G ---

getkey(), 22



--- H ---

Home Key, 8



--- I ---

Icharset, 12
Icolumn, 10
Idattr, 11
Idecimals, 12
Ifieldtype, 11
Iflags, 13
Incompatible Computers, 1
Input Field Attributes, 10
Ionoff, 10
Irow, 10
Ivalid, 14
Ivarptr, 14
Iwidth, 10








- 36 -









--- L ---

LINK, 3
LINK version, vi



--- M ---

Medium Memory Model, 3
MS C 5.0, vi
MSCREEN.LIB, 1, 2, 3



--- N ---

Next Field Control Key, 8



--- O ---

Ocolumn, 15
Odattr, 15
Oonoff, 15
Order Form, 33
Orow, 15
Otextptr, 15
Output Field Attributes, 15
Owidth, 15



--- P ---

PgDn Key, 7
PgUp Key, 7
Previous Field Control Key, 8
printem(), 20
printmsg(), 21



--- R ---

RETURN/ENTER Key, 8
Revisions, vi








- 37 -









--- S ---

screen0.c, 26
screen1.c, 26
screen2.c, 26
screen3.c, 26
scrnlib.h, 2
Small Memory Model, 3
Software/Services Order Form, 33
Space Key - numeric fields, 9
SSCREEN.LIB, 1, 2, 3
Support, 32



--- T ---

Tab Key, 9



--- U ---

Up Arrow Key, 8
Updates, vi, 32



--- V ---

Versions, vi

























- 38 -





 December 19, 2017  Add comments

Leave a Reply