home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Power-Programmierung
/
CD1.mdf
/
xbase
/
library
/
clipper
/
window
/
clipwin
/
clipwind.doc
< prev
next >
Wrap
Text File
|
1988-08-09
|
89KB
|
2,021 lines
Windows For Clipper
-------------------
Copyright (C) 1986-1988 By Jim Holley
All Rights Reserved
1346 Woodington Cir.
Lawrenceville Ga. 30245
(404)564-3647
Windows For Clipper
Trademarks and Concessions
--------------------------
Clipper is a Trademark of Nantucket Corp.
Lattice is a Trademark of Lattice, Inc.
Microsoft is a Trademark of Microsoft Corp.
Desmet 'C'is a Trademark of C Ware Corp.
Plink86 is a Trademark of Pheonix Software
Associates LTD.
IBM is a Trademark of International Business
Machines.
Windows For Clipper
SHAREWARE / NOT FREE SOFTWARE
-----------------------------
The Windows For Clipper Library is now being distributed under the
Shareware Concept. IT IS NOT FREE SOFTWARE. A lot of hard work and
long hours have been put into developing this library of window
routines. If you find this library of some practical use in developing
your applications, please REGISTER your copy. If you don't find it of
use, First, I'd like to know why. Second, please do not use it in any
applications that you develop. I will trust in your conscience as a
fellow programmer and developer. In trying to stay with the true concept
of shareware (try it before you buy it), a decision was made to release
the Windows For Clipper Library. I hope this decision will prove to be
a wise one. This is a full working version. Not a demo. The
documentation included on disk is also the complete reference to the
library. There are no gimmicks or tricks. The contents of this
distribution, is the same as the ordered version. If you use these
routines and don't register them, you deminish the concept of shareware,
and the programmer/developer community as whole. Shame on you!
A Registration Form May Be Found In The REGISTER.DOC File.
To All Bulletin Board Sysops and Users Groups:
You may freely copy or make available for distribution, the Windows For
Clipper Library package for evaluation purposes. However, no one may
modify any of the files that are part of the orignal package. You may
not sell, or otherwise profit from this package. That is the exclusive
right of the author. You may however, charge a copy fee not to exceed
$7.00 to cover costs, such as diskettes etc. This is the only fee that
is allowable. If you paid more than this allowable fee, please contact
the author. This provision applies ony to the Bulletin Board and Users
Group Community. All others organizations and distribution methods are
excluded and prohibited.
Windows For Clipper
Copyright Notice.
-----------------
Copyright (C) 1986, 1987, 1988, By Jim Holley
All rights reserved.
Limited License Agreement
-------------------------
Non registered users are granted a limited use license
for evaluation purposes on a private Non commercial basis,
to determine if Windows For Clipper is suitable for your
use. If you regulary use Windows For Clipper, you must
register your copy.
This license does not apply to commercial businesses,
institutions, or government agencies. If the Windows For
Clipper Library is used in this way, registration is required.
Remember, if you use the functions in the Windows For Clipper
Library, you must register your copy.
Disclaimer
----------
The author(s) of this set of routines believe that they will
perform their stated purpose. No warranty of any kind, expressed
or implied, including without limitation, any warranties of
merchantabillity and/or fitness for a particular purpose is made.
The author shall not be held liable for any damages to data,
property, lost profits, lost savings, or other incidental or
consequential damages, whether direct, indirect, or special, arising
out of your use or inability to use these routines.
Windows For Clipper
This version of Windows For Clipper is for the Summer '87 version of the
Clipper Compiler.
All code with the exception of the WN_DBF(), WNSAVE(), and WNRESTORE()
functions are written in MicroSoft 'C' Ver. 5.0 and Microsoft's Macro
Assembler Ver 5.0. They are all a combination of Clipper, 'C', and
assembler code.
Windows For Clipper
Table Of Contents
-----------------
Page
1. Introduction ____________________________ 1
2. Limitations _____________________________ 2
3. Installing the Library __________________ 3
4. Link Phase ______________________________ 4
5. Technical Information ___________________ 5
6. Reserved Words ___________________________6
7. Library Reference _______________________ 7
Control & Initialization
_SINIT_WN()............................ 8
_SST_WNCL()............................ 11
_SST_WNBC()............................ 12
_SST_PTSL()............................ 13
_SST_PTCL()............................ 14
_SST_UBIOS()........................... 15
_SWNCHG().............................. 13
_SMOVE_WN()............................ 14
_SREM_WN()............................. 15
_SWN_ROW()............................. 16
_SWN_COL()............................. 17
Input & Output
_SWNPUTCH()............................ 21
_SWNGETCH()............................ 22
_SDRW_ROW()............................ 23
_SDRW_WN()............................. 24
_SWTE_TXT()............................ 25
_SWTE_RECS()........................... 26
_SWTE_PTR()............................ 28
_SCLS_WN()............................. 30
_SCRL_VERT()........................... 31
_SCRL_HORZ()........................... 32
_SWNERASE()............................ 33
_WNSAVE().............................. 34
_WNRESTORE()........................... 35
_WNGETBUF()............................ 36
_WNPUTBUF()............................ 37
_WN_DBF().............................. 38
Other Functions
_BIGSTR().............................. 43
_NEWCOLOR()............................ 45
Windows For Clipper Page 1
Introduction
------------
Welcome to Windows for Clipper, a comprehensive set of window
routines written especially for the Clipper programmer and Clipper
Compiler. These routines provide all the basics for creating and
manipulating windows in the Clipper programming environment. Also
included are other video functions you may find useful.
Windows For Clipper has been in use for over a year now by such
companies or organizations as
The Library Of Congress
University Of Utah
Scientific Atlanta
Southern Methodist University
Dr. Jay Sprenger
Micro Business Services
dConsultant Systems
and many more. It is a proven, solid library. A Remote Bulletin Board
service has been set up so that Windows For Clipper users can get
support for the library, leave examples of code that others may find
useful, and to discuss the Clipper compiler in general. The bulletin
board is a restricted access board. You will be provided the number
to call when you register your copy of the library.
The demo that comes with this package shows how easy it is
to access the window functions. No special tricks or requirements
are needed. You write code as you normally would for any of the
Clipper internal functions or your own User Defined Functions.
No memory resident program needs to be loaded so that your program
functions properly. It is all built into the program during the
link phase. The only thing you need to learn are the function
names and what they do.
Windows For Clipper Page 2
Limitations
-----------
The window functions have the following limitations:
1. Minimum ram required.................................1.5k (or 1048
bytes) This requirement is set even if a window is never created.
2. Maximum ram required.................................?????
This is totally dependent on the number and dimensions of the
windows that are being created in a program. Due to this, it
it can not be stated exactly.
3. Maximum number of windows allowed....................256
Naturally, depending on the dimensions of the window and
the amount of ram installed on the computer, the maximum
number may be less.
4. Maximum window size..................................Full Screen
5. Minimum window size.................................3 col. by 3 rows
Minimum size is due to the requirement of a border for all windows.
Note, a 3 by 3 window will leave no room for text to be written.
Windows For Clipper Page 3
Installation
------------
The first step you should take is MAKE A BACKUP COPY. Place
the backup in a safe place in case you need it again.
Installation of the library is simple and straight forward.
Depending on the system configuration, do one of the following:
If you have a floppy based system:
----------------------------------
Locate the diskette that contains the CLIPPER.LIB file. Copy
the CLIPWIND.LIB file to this diskette. If there is not enough
room on the disk for all of your libraries, you may put the
Windows For Clipper Library on a separate disk. Refer to your
linker manual to determine how to do this.
If you have a hard disk system:
-------------------------------
Determine which directory contains the CLIPPER.LIB file. Copy
the CLIPWIND.LIB file to the same directory.
Windows For Clipper Page 4
Link Phase
----------
The link phase is that portion of development where you invoke
a linker to create the executable version of your program. Before
you start to worry, the Windows For Clipper system requires nothing
special other than specifying the library on the link line. For
example:
Plink86 Example
PLINK86 FILE WDEMO, CURSOR LIBRARY CLIPPER, CLIPWIND
^-----------------^ ^-----------------------^
| |
Indicate the object files to link |
|
Indicate the libraries to be used during the link phase.
Link.exe Example
LINK WDEMO CURSOR,, CLIPPER CLIPWIND
The link structure may be as simple or complex as required.
The only thing required is the CLIPWIND library in the link
command used to invoke your linker.
Included with the CLIPPER compiler are 2 batch files. These
batch files, CL.BAT and CLD.BAT, are used to help compile and
link your applications. Also included with Windows For Clipper
are 2 batch files, CLWIND.BAT and CLDWIND.BAT. These were created
to replace the batch files included with the compiler. If you
currently use the aforementioned batch files, you may want to
use those included with Windows For Clipper instead.
There is also a batch file named PL2.BAT. This example file
illustrates how to create batch files for linking using the PLINK86
linkage editor. It is fully functional and can be used if you do
not wish to compile and link under control of a single batch file.
Windows For Clipper Page 5
Technical Information
---------------------
The Windows For Clipper routines support PC/MS - DOS for the
IBM PC/XT/AT and 100% compatible computers. Some clones may or
may not function properly, depending on the compatibility of the
clone. The Windows For Clipper functions use DMA, or the standard
BIOS interrupt call 10 hex. Any machine that does not support the
IBM video addressing scheme or interrupt 10 hex will not work
properly. It stands to reason, any machine that will execute a
Clipper application will also execute the Windows For Clipper
routines without problems.
Compatibility Notes
The Windows For Clipper functions will run on any IBM PC/XT/AT
or 100 % compatibles. Since the new IBM PS/2 was not available to me,
I can not state that it is 100 % compatible with this machine.
Compatibility with this machine should not be a problem. As soon as
this information becomes available, it will be documented.
Windows For Clipper has been tested on, and found compatible
with the following:
Novell Advanced Netware Ver. 2.0A
Various LIM Standard extended memory cards including the Intel
AboveBoard, and Talltree Systems Jram3 and Jram AT3.
Various Expanded Memory cards including the Quadram Quadboard.
Thanks are in order for Mr. Paul Leo and his staff at the
University of Utah, for there exhaustive testing of the Windows
For Clipper System.
Windows For Clipper Page 6
Reserved Words
--------------
The following is a list of reserved words in the Windows For
Clipper package. Please refrain from using any of these names.
If you encounter a type conflict error during a program run,
check your field and variable names to be sure you are not using
one of these reserved words.
_SINIT_WN _SST_WNCL _SST_WNBC _SWNCHG
_SST_PTCL _SST_PTSL _SST_UBIOS _BIGSTR
_SMOVE_WN _SREM_WN _SWNPUTCH _SWNGETCH
_SDRW_ROW _SDRW_WN _SWTE_TXT _SWTE_RECS
_SCLS_WN _SCRL_VERT _SCRL_HORZ _SWNERASE
_WN_DBF _VIDSUP _SWN_ROW _SWN_COL
_WNSAVE _WNRESTORE _WNGETBUF _WNPUTBUF
_NEWCOLOR WNZ WN_ZFLD1 WN_ZFLD2
WN_ZFLD3 WN_ZFLD4 WN_ZFLD5 WN_ZFLD6
WN_ZFLD7 WN_ZFLD8 WN_ZFLD9 WN_ZFLD10
WN_ZUP WN_ZDOWN WN_ZLEFT WN_ZRIGHT
WN_ZESC WN_ZCR WN_ZNUMROW WN_ZKEY
WN_ZOFFSET WN_ZSCRL WN_ZTREC WN_ZCNT
WN_ZTRSH WN_ZLINDEX WN_ZREC WN_ZF1
WN_ZF2 WN_ZF3 WN_ZF4 WN_ZF5
WN_ZF6 WN_ZF7 WN_ZF8 WN_ZF9
WN_ZF10 WN_ZFLEN WN_ZHOME WN_ZEND
WN_ZCHOME WN_ZCEND WN_ZPGUP WN_ZPGDN
ZZNROWS ZZNCOLS ZZSAVBUF ZZSAVEWN
ZZMEMNAM
Windows For Clipper Page 7
Library Reference
-----------------
List of function calling syntax,
synopsis, and return values for
the Clipper window routines.
--------------------------------
==============================================================================
Notational Conventions
NOTE: Conventions used in this reference are as follows:
TRUE - Logical True (.T.)
FALSE - Logical False (.F.)
[] - Anything enclosed in brackets is optional.
... - Ellipses following an item indicate that more
items having the form may appear.
^ - Is used to indicate points of interest in example code.
Also may indicate the use of the control (CTRL) key.
==============================================================================
Windows For Clipper Page 8
Initialization and Control Functions
-----------------------------------------------------------------------------
_SINIT_WN(starting column, starting row, number of columns, number of rows)
Synopsis This is the core of the window functions. It is responsible
for setting up the requirements of the window system as well
setting up and maintaining the request for window creation
from the programmer. What follows is a technical description
of what this function does, as well as descriptions of the
windows created and functions provided, with the window system.
If you are not technically oriented, inclined or just plain
uninterested in the technical aspect, you should still skim
over the information below. It provides some very important
information about this window system.
On the first, and only the first, call to this module, 3
arrays are initialized. An array of pointers, an array of
of color values, and an array of color codes. The memory
required to establish the arrays is allocated whether you
call a window function or not. All of the arrays are accessible
to any of the window functions that require the data stored in
them.
The array of pointers consists of 256 elements, effectively
giving the programmer 256 windows to work with and manipulate.
All elements in the array are initialized to 0. As stated, this
is an array of pointers. I am stressing this point because the
initialization that takes place points every element in the
array to the interrupt vector table in the computer. This is
an area that only the brave should play around with. Any
element that is set to 0 should be avoided. In a Clipper
application, the calls to the window functions should only use
the number returned by this function. If you use a number that
was not provided by this function, you take the chance of
writing information into the interupt vector table. This will
reek havoc in your application, causing all kinds of strange
things to happen.
This brings up a couple of questions. First, why is an array
necessary? And second, why set the value to 0 if it may cause
trouble? The answer lies in dynamic memory allocation and
a pointer variables value. The window routines were designed
from the beginning to allow multiple windows, and to use as
little RAM as possible. It would be a very simple task to
eliminate the array if one could pass pointer values back and
forth from the window functions to the Clipper application. As
far as I know, it can't be done. This brought on the need for
the array. The array is now used to store the pointer value.
The value returned to the Clipper application is the offset
value into the array that stores the pointer value.
Windows For Clipper Page 9
Second question. All memory required for any given window is
allocated dynamically. Any arbitrary number could have been
selected to initialize the array, but chances are, the number
selected could have been the same as the number returned by
the memory allocation routines. Obviously, this would not be
acceptable. The memory allocation routines return a 0 if the
requested memory could not be allocated. So if an element in
the array has a value of 0, it is not a valid pointer to a
window control block structure and should not be accessed. On
the other hand, if the allocation was successful, the pointer
value is placed in the array and the value returned to the
Clipper application corresponds to it's position in the array.
As stated, memory is allocated dynamically when needed. When
the memory is no longer needed, it is released back into the
free memory pool. Therefore, if a window does not exist, it
does not require any RAM. Once a window is initialized, it
does require RAM, and will keep the RAM allocated to it as
long as the window exists. The RAM requirements for each
window created are as follows:
1024 Bytes approximate for the array of pointers.
24 Bytes used store the color and color code tables.
38 Bytes for the window control block structure.
buffer = (number of columns * number of rows) * 2.
The first item above is overhead. The array is manditory, and is
constant. Memory for the array is allocated whether the window
routines are used or not. The 30 bytes and buffer space are
allocated each time a window is created. The memory allocated
is constant as long as the window exists. If a window is
removed the 30 bytes, and the bytes allocated for the buffer
space, are released back to the free memory pool and can be used
again.
The buffer space is needed to store the information currently
on the screen in the area the window will occupy.
Windows For Clipper Page 10
If the window move function is called, memory is allocated for
another buffer of the same buffer size required by the window
itself.
The above memory requirements are provided for those programmers
who insist on writing mammoth applications and must keep a
careful watch on the applications memory usage.
Arguments
starting column - Column offset the upper left corner of the window
should start at. Values range from 0 to 79.
starting row - Row offset the upper left corner of the window
should start at. Values range from 0 to 24.
number of columns - The number of columns the window will occupy. Values
range from 0 to 79.
number of rows - The number of rows the window will occupy. Values
range from 0 to 24.
Returns Value > 0 - If memory allocation and window initialization
were successful. This value corresponds to the
window control blocks structure position in the
array.
0 - If memory could not be allocated, or invalid
parameters were passed to the function.
Windows For Clipper Page 11
_SST_WNCL(window, color code string, where)
Synopsis This function allows the setting of color in a window.
A color value can be established for the window border
or window contents. The default color value is a black
background and white foreground.
Arguments
window - Window number returned by the _SINIT_WN() function.
Color code string - Character variable containing a string representing
the color code. The color code string takes the
following form.
<background/foreground/intensity/blinking>
You may use any character to separate the
color code string, but a slash is recommended.
The following are the codes used for color selection.
A == BLACK
B == BLUE
G == GREEN
C == CYAN
R == RED
M == MAGENTA
O == BROWN
W == WHITE
L == BLINKING
H == HIGH INTENSITY
You may use upper case or lower case or any
combination of the 2.
EXAMPLE 1 "b/o/h/l"
| | | |
Blue Background ---------| | | |-------- Blinking
Brown Foreground ----------| |---------High Intensity
EXAMPLE 2 "b/r//"
| | High Intensity not
Blue Background ---------| | specified.
Red Foreground ------------| No Blinking specified
where - Character indicating where to change the color.
Two (2) areas are available. The border, and the
contents. "Where" must be a single character that is
equal to a (b) for border or (c) for contents and
can be either upper and/or lower case.
Returns TRUE - If the color was changed successfully.
FALSE - If the color could not be set. If this occurs, it
is usually because the function received invalid
arguments.
Windows For Clipper Page 12
_SST_WNBC(window, border character)
Synopsis This function allows the setting of a border character for a
window. This character can be any of the printable characters
in the PC's character set. Four (4) characters are special to
the window borders. They are the upper left corner single,
upper left corner double, upper left corner single top/double
side, and the upper left corner double top/single side line
graphics characters. These can be visually display by entering
the following command at the dot prompt:
? CHR(218) == ┌ or in basic ? CHR$(218)
? CHR(201) == ╔ ? CHR$(201)
? CHR(213) == ╒ ? CHR$(213)
? CHR(214) == ╓ ? CHR$(214)
If one of these characters is detected, a single, double
single side/double top, or double top/single sided graphic box
will border the window. At the current time any other
character is taken literally, and will be used for the corners,
top, bottom, and sides of the window.
This function will obey the video access method selected.
Arguments
window - Window number returned by the _SINIT_WN() function.
border character - The ascii value of the character that is to be used
as the border character. The CHR() function should
not be used as in the example above. Simply provide
the ascii number for the border character. The
reason this method of character selection was chosen
was because not all editors allow entry of all the
characters in the PC's character set, even some of
the very expensive, feature rich editors on the
market. And (here's the important one), it is easier
to deal with characters and associated attributes
as numbers, and not characters. Cheating on my part.
Please forgive!
Example 1. _SST_WNBC(window,218)
This will create a single line graphics
border around the window.
Example 2. _SST_WNBC(window,201)
This will create a double line graphics
border around the window.
Returns TRUE - If function was successfully.
FALSE - If the function was unsuccessful. If this occurs,
it is because the function received invalid
arguments.
Windows For Clipper Page 13
_SST_PTSL(window, pointer type)
Synopsis This function will select the pointer type to be written
by the _SWTE_PTR() and _WN_DBF() functions. Two pointer types
are available, type 1 and type 2.
Type 1 is an arrow that points to the right and is placed in
first 2 columns of a window. Please refer to the _SWTE_PTR()
reference for more information.
Type 2 is a bounce bar type pointer and is the default. This
pointer spans the entire length of the window.
The pointer colors can be selected using the _SST_PTCL()
function. If a type 2 pointer is used, you should select a
contrasting color to that which you have specified in the
window.
Arguments
window - Window number returned by the _SINIT_WN() function.
pointer type - 1 or 2. This indicates the pointer type to use.
This value will be used by the _SWTE_PTR() function.
Returns TRUE - If pointer type selection is successful.
FALSE - If pointer type selection is not successful. This
will occur if an invalid argument is received by the
function.
Windows For Clipper Page 14
_SST_PTCL(window, color code string)
Synopsis This function allows the setting of the pointer color written
by the _SWTE_PTR() function. This color should contrast the
color which is set in the window.
Arguments
window - Window number returned by the _SINIT_WN() function.
color code string - Character variable containing a string representing
the color code. The color code string takes the
following form.
<background/foreground/intensity/blinking>
You may use any character to separate the
color code string, but a slash is recommended.
The following are the codes used for color selection.
A == BLACK
B == BLUE
G == GREEN
C == CYAN
R == RED
M == MAGENTA
O == BROWN
W == WHITE
L == BLINKING
H == HIGH INTENSITY
Please refer to the _SST_WNCL() function for an example of
specifying the color code string.
Returns TRUE - If pointer color selection is successful.
FALSE - If pointer color selection is not successful. This
will occur if an invalid argument is received by the
function.
Windows For Clipper Page 15
_SST_UBIOS(window, logical true or false)
Synopsis This function sets the video access method used for all
read/write operations performed in a window. Each window
is treated as a separate entity. This provides more control
to the programmer as to the video access method used in
each window. The video access methods available are BIOS
and Direct Memory Access.
Some computers may not function correctly if Direct Memory
Access (DMA) is used. For this reason, the window read/write
functions can use an alternate method. If the computer is
not 100% IBM compatible, even the alternate method will fail.
Please test these functions on the machine that runs the
application to be sure they work correctly.
Arguments
window - Window number returned by the _SINIT_WN() function.
logical value - TRUE, will select the BIOS method.
FALSE, will select Direct Memory Access. This is the
default method used.
Return TRUE - If the video access method was selected successfully.
FALSE - If the video access method was selected was
unsuccessful. This usually occurs due to invalid
arguments being passed to the function.
Windows For Clipper Page 16
_SWNCHG(window, new width, new height)
Synopsis This function changes the width and height of a window.
If you specify a window of 30 columns, and 10 rows, you
can change these dimensions with this function to 40 columns
and 15 rows. The window that is being changed can not be on
the screen. You must use the swnerase function to erase
the window from the screen. The new dimensions will appear
when the window is drawn on the screen. Please note that
this does not change the starting column and row coordinates.
Care must be taken to prevent specifying a window that will
exceed the column and row coordinates of the screen because
the new coordinates are not checked.
Arguments
window - Window number returned by the _SINIT_WN() function.
new width - New number of columns occupied by the window.
new height - New number of rows occupied by the window.
Returns TRUE - If the window change was successful.
FALSE - If the window change was unsuccessful. If this
occurs, it is because the function received invalid
arguments.
Windows For Clipper Page 17
_SMOVE_WN(window, new column, new row)
Synopsis This function will restore the text that was originally on
the screen and move the window to the new coordinates. To
do this, the function attempts to create a buffer by
allocating memory. The buffer will store the contents of
the target window. If memory is not available for this
buffer, the window will not be moved.
This function will obey the video access method selected.
Arguments
window - Window number returned by the _SINIT_WN() function.
new column - New column offset for the upper left corner
of the window.
new row - New row offset for the upper left corner of the
window.
Returns TRUE - If the window was moved successfully.
FALSE - If the window move was unsuccessful. This
occurs because the function received invalid
arguments.
Windows For Clipper Page 18
_SREM_WN(window)
Synopsis This function removes a window from the screen, restores the
text that was on the screen prior to placing the window on
the screen, and releases memory allocated, back to the free
memory pool. On return from this function, the window no
longer exists. If stacked (tiled) windows are on the screen,
the last window drawn must be the first window removed. All
subsequent removes must be done in the same manner.
This function will obey the video access method selected
Arguments
window - Window number returned by the _SINIT_WN() function.
Returns TRUE - If succesful in releasing memory, and restoring
orginal screen contents.
FALSE - If window was not successfully removed. This
occurs because the function received
invalid arguments.
Windows For Clipper Page 19
_SWN_ROW(window)
Synopsis This function determines the number of rows available for
writing in the specified window.
Arguments
window - Window number returned by the _SINIT_WN() function.
Returns - The number of rows available for writing.
Or 0, if an invalid argument is received.
Windows For Clipper Page 20
_SWN_COL(window)
Synopsis This function determines the number of columns available for
writing in the specified window.
Arguments
window - Window number returned by the _SINIT_WN() function.
Returns - The number of columns available for writing.
Or 0, if an invalid argument is received.
Windows For Clipper Page 21
Input & Output Functions
------------------------
_SWNPUTCH(window, column, row, character)
Synopsis This function provides the means to directly write any
character to a window. If color has been set in the
window, the character will be written using the same
color attribute.
This function will obey the video access methdo selected.
Arguments
window - Window number returned by the _SINIT_WN() function.
column - The column location a character is to
be written to. The columns are relative to
the window dimensions. Column 0 represents
the first available column for writing within
a window.
row - The row location a character is to be
written to. The rows are relative to the
window dimensions. Row 0 represents the first
available row for writing within a window.
character - The character to be written in the specified
column row coordinates.
Returns TRUE - If the function was successful in writing
the character.
FALSE - If the function was unsuccessful in writing
the character.
Windows For Clipper Page 22
_SWNGETCH(window, column, row)
Synopsis This functions provides the means to directly read any
character in a window. If a variable is to receive the
character read, it must be initialized to a single space
prior to calling this function. This function cannot create
variables that are to be used by a Clipper application. Failure
to initialize the target variable will make the function appear
to have failed. This function should not be confused with the
READ command in Clipper. This function does not get input from
a user. The function will read an existing character in the
window only.
This function will obey the video access method selected.
Arguments
window - Window number returned by the _SINIT_WN() function.
column - The column location a character is to
be read from. The columns are relative to
the window dimensions. That is, column 0
represents the first writable column in a
window.
row - The row location a character is to be
written to. The rows are relative to the
window dimensions. That is, row 0 represents
the first writable row in a window.
Return - This function returns the character read at the
specified coordinates.
Windows For Clipper Page 23
_SDRW_ROW(column, row, number of times, character [, video access method])
Synopsis This function provides a quick and easy way to write a
specified character a specified number of times to the
screen. It is not restricted to a window. You may use
this function to write to any location on the screen.
It can be used to subdivide a window quickly and with
little coding. It is functionally equivalent to the
dBASE/Clipper command:
@ row,col SAY REPLICATE(character, number of times)
This function allows a video access method to be selected
as one of the arguments. The VDM is not mandatory.
Arguments
column - The starting column where the character is to be
written.
row - The starting row where the character is to be
written.
number of times - The number of times the character is to be written.
character - The character to write.
Video Access Method - A character indicating the VDM to use. A "D" will
result in Direct Memory Access (DMA), any other
character will result in a BIOS call. If not
specified, the result will be a BIOS call.
Returns TRUE - If the functions was successful.
FALSE - If the function was unsuccessful. If this occurs,
it is because the function received invalid
arguments.
Windows For Clipper Page 24
_SDRW_WN(window)
Synopsis This function actually draws the window on the screen. You
may create any number of windows in your application, but
they do not appear on the screen until this function is
called. The window drawn occupies the following area:
starting column, starting row
number of columns + 2, number of rows + 2
When a call is placed to the _SINIT_WN() function with the
following parameters:
_SINIT_WN(10,5,30,10)
a window is drawn with the upper left corner starting at
column 10, row 5, and the lower right corner ending at
column 42, row 17.
As can be seen, the actual window occupies an area slightly
larger than what was specified. The inside portion of the
window area is available for writing. This area has the number
of columns and rows which were specified. You cannot write text
on the border area of the window when using the window output
functions. The area available for writing is cleared.
This function will obey the video access method selected.
Arguments
window - Window number returned by the _SINIT_WN() function.
Returns TRUE - If window was drawn successfully.
FALSE - If the window could not be drawn. If this occurs,
it is because the function received invalid
arguments.
Windows For Clipper Page 25
_SWTE_TXT(window, string)
Synopsis This function writes a string of text to a window. If the
length of the string exceeds the the width of the window,
it will be truncated. Each window keeps track of the last
row written to. Each time a string is written to a window,
the row offset inside the window is advanced to the next
line. This is true regardless of the string's length. When
the text is written to the last row in a window, all subsequent
lines will scroll the window up one row, then write the text.
This function will obey the video access method selected.
Arguments
window - Window number returned by the _SINIT_WN() function.
string - The string to be written. The string can be in a
variable, or literal.
Returns TRUE - If the write was successful.
FALSE - If the write was unsuccessful. If this occurs,
it is because the function received invalid
arguments.
Windows For Clipper Page 26
_SWTE_RECS(window, arg1, [arg2, arg3,.....])
Synopsis This function is a specialized form of the write text
function. This function takes database field names as it's
arguments. All fields specified must be of character type or
converted to character type using one of the functions provided
by Clipper i.e. STR(), DTOC() etc. At least one field must be
specified. After that, 9 others maybe specified. The fields
are written in the order specified in the call. If the contents
of a field exceeds the window boundaries, the text will be
truncated, and all subsequent fields will not be written.
This does not mean the field is truncated in the database
itself, just as output into the window. As in the _SWTE_TXT()
function each window keeps track of the last row written to.
Each time a set of fields is written to a window, the row
offset is advanced to the next line.
This function is not limited to just fields. You may specify
string constants, or character type memory variables if needed.
You may also specify any function as an argument, so long as
the function returns a character type result.
Example : _SWTE_REC(wn, Company, IF(paid , "Yes", "No"))
Window # ^ ^ Field ^ Function returning char.
This will display the contents of the field company
and Yes, or No, depending on the value of paid.
This assumes that company is a character field or
memory variable, and paid is a logical field or memory
variable.
NOTE:
The function is limited to combined length of 512 characters.
This means that the length of each argument added together
can not exceed 512 characters. All fields and memory variables
will be displayed until a length of 512 characters is reached.
If the combined length exceeds this limitation, the function
will fail.
This function will obey the video access method selected.
Windows For Clipper Page 27
Arguments
window - Window number returned by the _SINIT_WN() function.
arg1 - A database field name, memory variable, character
constant, or function returning a character result.
If a field is specified, the database in which the
fields are accessed must be open. If the database
is not in the current selected area, an ALIAS
prefix must be used.
Example: CUSTINFO->COMP_NAME
^Alias prefix.
[arg2, arg3,....] - Optional arguments. The above applies here also.
Returns TRUE - If write was successful.
FALSE - If the write was unsuccessful. If this occurs,
it is because the function received invalid
arguments.
Windows For Clipper Page 28
_SWTE_PTR(window, target row, direction)
Synopsis This function will write a pointer in the window specified.
Two pointer types are available, please refer to the _SST_PTSL()
function reference to determine what the pointer types are.
The pointer color can also be set. This function will determine
the current color and use it. Please refer to the _SST_PTCL()
function reference to determine how to set the pointer colors.
A pointer in a window can be used for several different
reasons. Highlight text as it is being read is one example.
The _WN_DBF() function use the pointer to indicate which
record the user is currently resting on.
If order to use this function here are a few things you must
know.
If pointer type 1 is selected, you must prefix all text
written to the window with 2 spaces. Pointer type 1 is an
arrow that points to the right. It occupies the first 2
character positions in a window. You will need to prefix all
text written to the window with 2 spaces. This will provide
the space required to accommodate the pointer.
If pointer type 2 is selected, no extra space is needed. This
pointer is a bounce bar and starts at the first column in the
window and fills the entire length of the window. It will not
disturb the text that occupies the window.
When calling this function, you must indicate the direction
in which the pointer is being moved. If this is the first call
to the function and no direction has yet been established, you
indicate "N" for none. If you have a pointer at the last row
in a window, and wish to move to the pointer to the previous
row, you indicate "U" as the direction. And of course, if you
wish to move the pointer down in a window, you indicate "D".
The direction of movement and the target row are used to
determine what the function must do to erase the previous
pointer written in a window. You should never move the pointer
more than one row up or down at a time. If this occurs the
function will not be able to remove the previous pointer.
You should never select a different pointer type after calling
this function for the first time. This will result in a very
peculiar looking window. If a window is erased, or has no
pointer in it, you can safely change the pointer type to suit
your needs.
If pointer type 2 is selected, the function will use DMA
as the video access method. This is not selectable. If
pointer type one is selected, the function will obey the
video access method selected.
Windows For Clipper Page 29
Arguments
window - Window number returned by the _SINIT_WN() function.
target row - the row the pointer will be written in. The row
is relative to the window dimensions. That is, row
0 represents the first writable row in a window.
direction - the direction in which the pointer will be moved.
valid responses are: "U", "D", and "N".
Returns TRUE - If pointer written succesfully.
FALSE - If pointer not written successfully. If this occurs
it is usually because the function received an
invalid argument.
Windows For Clipper Page 30
_SCLS_WN(window)
Synopsis This function will clear the contents of a window. When
the window is cleared, the row offset is reset to row 1.
If a vertical scroll value has previously been set, it
will not be changed. The vertical scroll value must be
explicitly changed by making a call to the _SCRL_VERT()
function. Please refer to the _SCRL_VERT() functions
synopsis for an explanation of this function.
If you changed the color by calling the _SST_WNCL() function
prior to calling this function, the windows content color
will be changed to that specified when this function is
called. This will not affect the border color of the window.
This function will obey the video access method selected.
Arguments
window - Window number returned by the _SINIT_WN() function.
Returns TRUE - If the window was cleared successfully.
FALSE - If the window clear was unsuccessful. If this
occurs, it is because the function received invalid
arguments.
Windows For Clipper Page 31
_SCRL_VERT(window, number of characters)
Synopsis This function will cause any text written to a window to
scroll left or right. The scroll vertical function will
not affect any text written in the window, prior to calling
the function. All text written to a window after this function
is called will scroll in the appropriate direction. To
reset vertical scrolling to "No Scroll", a value of 0 should
be passed to the function.
Arguments
window - Window number returned by the _SINIT_WN() function.
number of characters - The number of characters to scroll. If left scroll
is desired, a negative value is supplied. If
right scroll is desired a positive value is
supplied. To reset for "No Scroll", a 0 is
supplied.
Example - _SCRL_VERT(window, -5)
This will scroll text left 5 characters.
Example - _SCRL_VERT(window, 5)
This will scroll text right 5 characters.
Returns TRUE - If the scroll was successful.
FALSE - If the scroll was unsuccessful. If this occurs,
it is because the function received invalid
arguments.
Windows For Clipper Page 32
_SCRL_HORZ(window, number of lines)
Synopsis This function will cause any text written to a window to
scroll up or down. If a scroll up request is made, the
top line in the window will be lost and all lines below it
will move up. Likewise, if a scroll down request is made, the
bottom row in the window will be lost and all lines above it
will be moved down.
When scrolling up, the cursor offset in the window is reset
to the first row of the window. When scrolling down, the
cursor offset in the window is reset to the last row of the
window.
Arguments
window - Window number returned by the _SINIT_WN() function.
number of lines - The number of lines to scroll. If an up scroll
is desired, a positive value is supplied. If a
down scroll is desired a negative value is
suppplied.
Example - _SCRL_HORZ(window, 5)
This will scroll text up 5 lines.
Example - _SCRL_HORZ(window, -5)
This will scroll text down 5 lines.
Returns TRUE - If the scroll was successful.
FALSE - If the scroll was unsuccessful. If this occurs,
it is because the function received invalid
arguments.
Windows For Clipper Page 33
_SWNERASE(window)
Synopsis This function erases a window from the screen. If stacked
(tiled) windows are on the screen, the topmost window must
be erased first. All subsequent erasures must be done in
the same manner.
This function will obey the video access method selected.
Arguments
window - Window number returned by the _SINIT_WN() function.
Returns TRUE - If the erasure was successful.
FALSE - If the erasure was unsuccessful. If this occurs,
it is because the function received invalid
arguments.
Windows For Clipper Page 34
_WNSAVE(window, filename)
Synopsis This is a special purpose function that allows the text stored
in a window to be saved in a Clipper MEM file. The complete
contents of a window are saved including the color of the
window contents.
If the MEM filename specified exists, the contents of the MEM
file will be lost and the new information stored in it.
This function will obey the video access method selected.
Arguments
window - Window number returned by the _SINIT_WN() function.
filename - A valid DOS filename. If an extension is not specified,
WFC will be used as the default. The filename argument
must be delimited with quote marks.
Example : _WNSAVE(wn, "TEST")
Returns TRUE - If the function was successful in reading and saving
the windows contents.
FALSE - If the function was not successful in reading and
saving the windows contents. This return usually
occurs if the the target window is not on the screen.
Windows For Clipper Page 35
_WNRESTORE(window, filename)
Synopsis This is a special purpose function that restores the contents
of a window that was previously saved by the _WNSAVE()
function.
The target window must be on the screen and the same size
as the original window the _WNSAVE() function used to save
the information. If the window size differs, unpredictable
results may occur.
Arguments
window - Window number returned by the _SINIT_WN() function.
filename - A valid DOS filename. If an extension is not specified,
WFC will be used as the default. The filename argument
must be delimited with quote marks.
Example : _WNRESTORE(wn, "TEST")
Returns TRUE - If the function was successful in writing the saved
contents back to the window.
FALSE - If the function was not successful in writing the
contents back to the window. This usually occurs if
the target window is not on the screen, or the
indicated file can not be found.
Windows For Clipper Page 36
_WNGETBUF(window, buffer)
Synopsis This is a special purpose function that reads the contents
of a window and stores it into a buffer. This is the low
level function used by the _WNSAVE function.
The buffer must be initialize to a size that will hold the
contents of the window. The buffer format is as follows:
1st byte .... character in the first column and first row in
the window.
2nd byte .... color attribute of the specified window.
All subsequent bytes follow this same pattern. The size of
window buffer required can be calculated as follows:
buffer size = (number of rows * number of columns) * 2
Example of buffer initialization:
buffer = SPACE((numrow * numcols) * 2)
or
buffer = SPACE((_SWN_ROW(window) * _SWN_COL(window)) * 2)
If the buffer space is not large enough, unpredictable results
will occur.
This function will obey the video access method selected.
Arguments
window - Window number returned by the _SINIT_WN() function.
buffer - A Clipper initialized memory variable that will be
used to store the contents of the window.
Returns TRUE - If the function was successful in storing the window
contents in the buffer.
FALSE - If the function was unsuccessful in store the window
contents in the buffer. This will usually occur if
the target window is not on the screen, or invalid
arguments were received by the function.
Windows For Clipper Page 37
_WNPUTBUF(window, buffer)
Synopsis This is a special purpose function that writes the contents
of a buffer created by the _WNGETBUF() function, to a window.
The target window should be the same size as the target window
that was used to create the buffer.
A standard string can not be written to a window with this
function. The function expects the buffer to have the same
format as that created by the _WNGETBUF() function. Please
refer to the _WNGETBUF() fucntion for further information
on the buffer format.
This function will obey the video access method selected.
Arguments
window - Window number returned by the _SINIT_WN() function.
buffer - A Clipper initialized memory variable whose contents
was placed there by the _WNGETBUF() function.
Returns TRUE - If the function was successful in writing the contents
of the buffer to a window.
FALSE - If the function was unsuccessful in writing the buffer
contents in the window. This will usually occur if
the target window is not on the screen, or invalid
arguments were received by the function.
Windows For Clipper Page 38
_WN_DBF(window, "field" [,"field","field".....])
Synopsis This is a special purpose function that allows a database
to be viewed through a window. The function takes control
of the keyboard and provides maneuverability through the
database. Record selection can be accomplished using this
function. All an operator has to do is point to the record
desired and press return.
The function requires the following:
1. A valid window number that has been initialized and drawn
by the _SINIT_WN(), and _SDRW_WN() functions respectively.
2. The database being windowed must be the selected database
in use. Suppose you have two databases open and you wish to
display field information from area 1. This section of code
would be required for the function to operate properly:
*** open files
SELECT 1
USE DATA1
SELECT 2
USE DATA2
*** window view of DATA1
SELECT 1
_WN_DBF(window, "customer", "address", "city", "state", "zip")
This will display fields from the current area with the above
field names. In the above example, all field names specified
are character type fields. The quotes around the field names
are required. There are exceptions to this, which are
documented below.
The type of pointer used by this function is selectable. Two
pointer types are available. Please refer to the _SST_PTSL()
function for more information.
Character and logical fields are directly supported by the
function. Logical fields do not display as .T. or .F., instead
they are displayed as 'Y' for true (.T.) and, 'N' for
false (.F.). To indicate one of these fields simply enclose
the field name in quotes.
Expressions are allowed, as long as the result is a character
or character string. Numeric and date fields can be accessed
by this function only if a method/function of converting the
field to a character or character string is provided. The
technique to accomplish this is usually another function call.
The _WN_DBF() function will implement the method/function
specified through macro expansion.
Windows For Clipper Page 39
Clarification as to a method/function.
--------------------------------------
A method is an action that is not strictly categorized as
a function but still results in a character or character
string result. This can best be describe in the following
line of code:
IF field1 and field2 are character type fields:
"field1 + field2" <--- This is called concatenation.
As can be seen, this will still result in a character or
character string. There may be other methods, but this
should serve as a good example.
Functions should not need clarification. For those that do
not fully understand what a function is or does, most
programming reference works that deal with the 'C' language
can give you a complete description. It is beyond the scope
of this reference to do so.
The handling of data conversion from numeric to character
and date to character is implemented in a fashion to
allow more flexibility to the programmer. Clipper provides
a good set of conversion routines but they are not the only
routines available. The design of this function allows the
programmer to specify the method/function to use. These
methods/functions can be Clipper internal routines, routines
of your own design, or routines acquired by you. Due to this
flexibility, certain precautions must be taken.
Precautions to be aware of:
1. If the method/function is not a Clipper internal routine,
it is suggested that an 'EXTERNAL method/function name'
declaration line be placed somewhere within your
application to insure it is included during the link phase.
EXAMPLE: EXTERNAL LOGTOCHR
2. The programmer should fully understand what the return
result should be from any method/function used for data
conversion. The method/function MUST return a character or
character string value.
3. The method/function can not be a procedure. Procedures
are not supported.
Windows For Clipper Page 40
4. You must follow the section describing the syntactical
requirements found below.
The above describes the data conversion methods using numeric
and date fields as a reference. Be aware that data conversion
is not strickly limited to those field types. Although the
above discussion does apply to the numeric and date field
types, you may also provide a method/function for conversion
of logical fields or special formating of character fields.
For instance, if you require a more verbose display of
logical fields than what is supplied by this function, you
may create your own function for this purpose and specify it
as the data conversion method/function to use. The bottom
line is this; Any method/function that returns a character
or character string result should work.
Syntactical requirements for data conversion.
---------------------------------------------
Two methods are available if data conversion is to be used.
Please keep in mind that character and logical type fields
are directly supported by this function.
In the following descriptions, 'wn' refers to a valid
window number returned by the '_SINIT_WN()' function,
'name' refers to a character field and 'number' refers to
a numeric field.
Method 1.
---------
This is called the 'DIRECT' method. It is preferrable
if you require readable code at the expense of
flexibility.
Example:
rec = _WN_DBF(wn, "name", "STR(number)")
^^^^^^^^^^^^^
In this example, the STR() function will be used for
data conversion. Note the quotes surrounding the
parameter; these quotes are required. If the quotes
are not present, the application will experience a
type conflict error. This is the same method used
for direct support of the character and logical field
types. The difference being, a function is part of the
quoted parameter.
Windows For Clipper Page 41
Method 2
--------
This is called the 'INDIRECT' method. It is preferable
if you require flexibility at the expense of
readability.
Example:
memvar = "STR(number)"
rec = _WN_DBF(wn, "name", memvar)
In this example, the STR() function will be used for
data conversion. Note that quotes do not surround the
parameter containing the method/function string. If
quotes are placed around the memory variable 'memvar',
no error will occur, the function will simply display
the contents of the memory variable in the window.
Parameter checking is at a minimum in this function. The
programmer must bear most of the responsibility to insure
the proper parameter values are passed. The function does
check the parameters passed to it, and these parameters must
be passed in sequence. The following construct would be
invalid:
recs = _WN_DBF(wn1, "customer", ,"address", "city")
(missing ^ parameter)
If parameters were passed as above, unpredictable results may
occur. This function will try to recover and provide function
integrity. This is not guaranteed.
As of this writing, you cannot specify a scope with this
function. Meaning that this construct would be invalid:
_WN_DBF(window, "field1", "field2") for city = "ATLANTA"
You can set a filter, and the function will respect said
filter, until such time as it is removed. If a filter is set,
a delay may be detected when moving from one record to another.
This delay is not caused by the _WN_DBF() function, but the
filter command itself, as it moves through the database
trying to decide if the record qualifies. It is quite possible
that no records pass the filter, therefore no field information
will be displayed in the window.
It is not necessary that the window be the same width or wider
than the field information that will be written. If the field
information is wider than the window, it will be truncated to
fit the window. The information in the database is not
effected. The field information is truncated for writing to
the screen only. The total combined length of all fields
specified can not exceed 512 characters. This restriction is
the same as the _SWTE_RECS() function.
Windows For Clipper Page 42
Maneuvering through the database is accomplished through the
use of the special keys on the numeric key pad. The "Up", and
"Down" arrow keys allow moving from record to record. If the
"Up" arrow key is pressed, the database record pointer will
be moved to the previous record. If the "Down" arrow key is
pressed, the database record pointer will be moved to the
next record. Depending on the pointer position in the window,
the field information may be scrolled up or down, whichever
is appropriate. The "Left" and "Right" arrow keys allow panning
left or right through the field information specified. If
the "Left" arrow key is pressed, the field on the left side
of the window will be scrolled off the screen and all other
field information will be shifted to the left. Any field
information on the right that was not visible, can now be
seen. Pressing the "Right" arrow key has the opposite effect.
The "Home" and "End" keys move the record pointer to the first
and last record displayed in a window. The "^Home" and "^End"
(^ = Control) keys will move the record pointer to the top or
bottom of the database respectively. The "PgUp" and "PgDn"
down keys allowing paging through the database. The page
size is dependant on the size of the window. If you have
a window consisting of 10 rows, then the page size will
be 10. If a window consists of 5 rows, then the page size
will be 5 etc. If a vertical scroll has occurred, it remains
in effect. The movement through the database, regardless
of the key pressed, will maintain the current scroll setting.
Record selection can be accomplished by pressing the enter key
after pointing to the desired record or, if no record is desired
pressing the ESCape key will cause the function to return a
0. It is up to the calling process to take appropriate action
depending on the return value of this function.
Arguments
window - Window number returned by the _SINIT_WN() function.
"field" - Field or data conversion method/function name to
display. Please refer to the above text for an
explaination of data conversion techniques.
[,"field","field"...] - Up to 9 more fields or data conversion
methods/functions may be specified for a total
of 10, whose combined length does not exceed 512
characters.
Return Record number - The function will return the record number of the
or 0 record currently being pointed to if the return
key is pressed, or 0 if the escape key is pressed.
Windows For Clipper Page 43
Other Functions
---------------
_BIGSTR(String, col, row [, color code string, VAM])
Synopsis This function will write BIG strings to the screen. The size
of each character is 8 columns wide and 8 rows long. This
function can be used to create attractive startup screens
etc.
Maximum safe string size is 10 characters. This is due to the
size of each character that is printed. The color control
string and VAM are optional. If not specified, the default
will be white characters as the color and, DMA as the video
access.
Arguments
string - The string to be printed.
col - starting column coordinates. Adjust the starting
column coordinates or the string size to insure
the character will not exceed the screen boundaries.
row - starting row coordinates. You should not specify a
row coordinate higher than 16. If you do, the
characters will exceed the screen boundaries.
color code string - Character variable containing a string representing
the color code. The color code string takes the
following form.
<foreground/intensity/blinking>
You may use any character to separate the
color code string, but a slash is recommended.
NOTE: Only the foreground color is specified as a parameter
to this function. If you wish to set the background
color to something other than White on Black, use
the Clipper SET COLOR TO statement.
The following are the codes used for color selection.
A == BLACK
B == BLUE
G == GREEN
C == CYAN
R == RED
M == MAGENTA
O == BROWN
W == WHITE
L == BLINKING
H == HIGH INTENSITY
Refer to the _WN_DBF() function for examples of
specifying a color code string.
VAM - Video access method to use. Valid arguments are:
1. For direct memory access.
0. For BIOS access.
Windows For Clipper Page 44
Returns TRUE - If the function was successful in writing the string.
FALSE - If the function was unsuccessful in writing the string.
This will occur if the function receives invalid
arguments.
Windows For Clipper Page 45
_NEWCOLOR(start col, start row, end col, end row, color code string)
Synopsis This function will change the color in the specified area
of the screen. It will not disturb any text that may occupy
the target area of the screen.
This function uses only DMA as the access method.
Arguments
start col - The column in which to start the color change.
start row - The row in which to start the color change.
end col - The column in which the color change will end.
end row - The row in which the color change will end.
color code string - Character variable containing a string representing
the color code. The color code string takes the
following form:
<background/foreground/intensity/blinking>
You may use any character to separate the
color code string, but a slash is recommended.
The following are the codes used for color selection.
A == BLACK
B == BLUE
G == GREEN
C == CYAN
R == RED
M == MAGENTA
O == BROWN
W == WHITE
L == BLINKING
H == HIGH INTENSITY
Refer to the _WN_DBF() function for examples of
specifying a color code string.
Returns TRUE - If the function changed the area as specified.
FALSE - If the function could not change the area as specified.
This usually occurs if the function received invalid
arguments.
