Black Box 4/BlackBox.cdr/database/datamage.arj/HELPFILS.ZIP/AM_CTR_T.HLP

Text File | 1991-07-02 | 16.1 KB | 316 lines

APPLICATIONS MAKER - HELP FOR CONTROL TYPES

The  CONTROL  ITEMS relate to the program flow, or control,  of  your
application.   They may be of nine types:  LABEL, GOTO,  GOBACK,  IF,
DO, DO PRINT, BREAK, END and LOCATE.

LABEL ITEMS:  With the LABEL ITEMS a position on the screen to  which
you may go (or BRANCH) is established.  The labels can be duplicated.

GOTO ITEMS:  With the GOTO ITEMS the application will branch  FORWARD
to a label.  BREAK items will also be found by forward gotos.

GOBACK  ITEMS:   With the GOBACK ITEMS the  application  will  branch
BACKWARD  to a label.  These items, when used in conjunction with  or
as an argument of an IF ITEM, will allow you to create loops.

In the jargon of programming a LOOP is a series of instructions  that
are   repeated  while/until  a  test  evaluates   true/false.    Each
individual repetition of a LOOP is called an ITERATION.

LOOPS can be very useful.  They can also create LOCKUP if their  test
never  evaluates  as planned.  If this happens to you just  hit  your
escape key to halt the application.

IF ITEMS:

The  IF  ITEMS  provide the ability to do a set of  operations  IF  a
certain requirement is met.  The targeted data is TESTED to determine
whether  or not the requirement is met.  If it is the IF is  said  to
EVALUATE  as true and the operations are executed; if not the  IF  is
said  to  EVALUATE  as false and the set of operations  will  not  be
executed.  This is known as CONDITIONAL processing.

STRUCTURE:

The structure of the IF ITEMS is identical to the same structures  in
any  other program.  In the jargon of the programmer,  ARGUMENTS  are
parameters  supplied to a function.  The ARGUMENTS for the  IF  ITEMS
consist of a CONDITIONAL argument which defines the test to be  done,
and up to ten EXECUTION ARGUMENTS which are to be carried out if  the
test evaluates as true.

DEFINING THE CONDITION TO BE MET:

The  IF  ITEMS  can  compare any of the three  basic  data  types  in
DATAMAGE files.  You may compare numbers to numbers (dollar-formatted
fields are numbers), dates to dates or numbers or strings to strings.
All  three  data types may also be compared to CONSTANTS,  which  are
values  that  you  include in the IF ITEM.   You  may  NOT,  however,
compare dates or numbers to strings, or vice-versa.

SYNTAX OF THE CONDITIONALS:

Yes,  this is one of two places within the DATAMAGE system where  you
will  be  required  to enter SYNTAX, or commands that  conform  to  a
specified  format.   But the claim that a DATAMAGE  user  need  NEVER
learn  SYNTAX  is not false; the SYNTAX is supplied to  you  on  your
screen  during the entry of the IF ITEMS and FORMULAS.  Your  entries
are  SYNTAX-CHECKED  during both entry and execution of the  IFs  and
FORMULAS,  and  appropriate error messages are displayed  should  you
make a mistake or, for example, attempt the division of zero.

COMPARING NUMERIC DATA:

Numeric  data may be stored in a field within a file, an  element  of
the  USER-ARRAY, or included in the IF ITEM.  You may compare any  of
the above to any of the above targeting on equal, less than,  greater
than, or not equal.

COMPARING DATE DATA:

When  we begin comparing dates we have a slight problem.  You may  be
prone  to  enter  dates  in  the  formats:  MM/DD/YYyy  (normal)   or
DD/MM/YYyy (military).  When entering dates into DATAMAGE fields  the
format  is  displayed for you, and detectable errors are met  with  a
beep, and the return to the entry of the date.  When creating your IF
ITEMS this is, of course, not available.

This situation will NOT DO!

When  dates  are  compared within the DATAMAGE  system  the  software
converts  them  into  numbers.  You may have noticed  that  the  BASE
program  can sort a datafile on a date field in a hurry; this is  how
it's done.  This date format is commonly called a METRIC date.

Let's consider the date: 01/02/91.  If it was stored in a field whose
format was MM/DD/YY, this date would represent Jan. 1, 1989.  On  the
other  hand, if this date were recorded in a field whose  format  was
DD/MM/YY, this date would represent Feb. 1, 1991.

Note  that omitting the first two digits of the year will  cause  the
software to assume that you mean 1,900 and whatever is present.   For
this reason the DATAMAGE system is no good for recording dates before
the year 100 a.d.  (Sorry, history buffs.)

In  order to convert this date to an ABSOLUTE value we first  process
the year.  The 91 is stripped from the end and, since it is less than
100,  1,900  is added to it.  the result of this is 1991.   Now,  the
software  selects  the month, be it in position 1 and 2 or 4  and  5.
Assuming the more common MM/DD/YY format, the O1 is added to the  end
of the 1991, giving 199101.  Now, we do the same for the day,  giving
19910102.  Finally, this string is converted to a number.

When  you enter date CONSTANTS within your IF ITEMS you MUST use  the
METRIC date format.  This may be a small inconvenience for the  short
period that it takes to get used to it, but it will save many errors.
It  should  be  noted that this is necessary only  when  CREATING  an
application,  and  is  not  supported when  entering  data  into  the
program.

You may also compare date fields to values in the USER-ARRAY.   These
values  must  also be in the METRIC format.  You can  use  a  numeric
field with the auto-fill option to get the date into the  USER-ARRAY,
where  it  becomes available for use as a target of date  or  numeric
comparisons.  This process may be the ARGUMENT of an IF ITEM,  giving
you the ability to use different comparison dates as needed.

COMPARING STRINGS:

Strings  may be compared in all the normal manners:   equal,  greater
than,  less than and not equal, plus one more that is unique  to  the
string comparisons: contains.  If the contains operator ( is used  it
always  looks  for the second string (on the right of  the  operator)
within the first string.

If the greater than or less than options are used the result will  be
according to alphabetic order.  No, you can't use APPLICATIONS  MAKER
to  sort  your datafiles - the BASE program  performs  that  function
rather  handily  upon up to eight targets of the same or  mixed  data
types.   You may then create a MARKER FILE that makes the product  of
the sort available to APPLICATIONS MAKER.

CONSTANTS may also be incorporated into your string IF ITEMS, but the
space provided for them is significantly less than the maximum length
of  a  DATAMAGE string field, which is 250 characters.  In  the  rare
case  of  needing to use a string CONSTANT that is  longer  than  the
space provided you're out of luck.

When  comparing  strings APPLICATIONS MAKER always  removes  all  the
spaces  from both targets and converts all the upper case letters  to
lower  case.   Thereby using the CONTENT of the string  and  ignoring
it's case and spacing.

EXECUTED ARGUMENTS:

Legal  arguments  for IFs are EXECUTE FORMULA, DO,  DO  PRINT,  GOTO,
GOBACK,  ABORT  and KILL RELATIONAL WRITES.  The GOTOs,  GOBACKs  and
ABORTs must be the LAST argument of the IF item as they terminate the
IF.  Any arguments following these items will NOT be executed.

Care should be taken in using the ABORT option of the IF items.  This
will abort the application!  If you have used the REL WRITES item  to
store  interfile  updates  they  will  NOT  be  executed.   If   your
application  keeps running totals etc. they will not be listed.   The
application will stop dead.

If  you  desire only to abort the current iteration of  a  repetitive
application  (such  as  one that enters records)  you  should  simply
branch to a label past your write record and REL WRITES.  This should
offer  the user the option to perform another iteration (by  entering
1),  or  to quit (enter 2).  The result of this numeric  screen  item
should  be  placed  in an element of the user  numeric  array  via  a
formula, then tested with an IF item.

The KILL relational writes argument is provided for this eventuality.
If  your  application  has made use of the REL WRITE  item  to  store
interfile updates to be executed at a later time (when the record  is
completed)  you will need to delete these relational writes when  you
branch to the next iteration of your repetitive application in  order
to  prevent  their  execution  the next time  a  REL  WRITE  item  is
encountered.

The KILL argument will also obviate any/all DO statements in  effect.
If  the  KILL is encountered within a DO statement the  program  will
need to negate the effect of that DO so that the next BREAK item will
not send control of your application back to the item proceeding  the
DO.  This will work no matter how many levels of DO are currently  in
effect, including recursive DOs.  (DO ITEMS are coming later.)

There may be times when you wish to get at the ABORT and KILL options
without  a  test.   These items are almost always  the  result  of  a
condition  in  your application, but, due to the  structure  of  your
logic, they may occasionally be needed as stand-alone functions.   To
do this you must initiate an IF, as these items are available only as
arguments to IFs.  Just type as the test of the IF: U1=U1.  The first
element  of  the  user numeric array will  (hopefully)  always  equal
itself, so the arguments will always be executed.

If  there is any possibility of branching to the next iteration of  a
repetitive application you should also take care concerning  whatever
running totals you are keeping.  This can be accomplished by  placing
the  data  for the running totals into another element  of  the  user
numeric  array, then adding it into the running total after the  last
possibility of aborting the iteration has been executed.

Compound IFs, block IFs and IFs with ELSE arguments all evaluate to a
series  of simple IF/GOTO operations, as do SWITCH (C),  SELECT  CASE
(BASIC)  and  CASE OF (PASCAL).  If you do not understand what  I  am
talking about, here, don't worry about it.  If you do then you should
already know how to do these constructs with IF/GOTO.

Simply put, there are many times when you want to execute  operations
only if a multiple test evaluates true.  For example, you might  wish
to  update  a  file if the record being entered is  a  sale  AND  the
purchase is being charged.  To do this you might reverse your  tests.
The first IF might test for the record NOT being a sale, then  branch
around  the file update.  The second IF might test that the  purchase
is NOT a charge, then branch around the file update.

There are also many times you want to execute an operation if one  of
several tests evaluate true.  You might wish to abort a record if  it
is  a charge and the customer has no credit OR is at/over his  credit
limit.   This is easily done by testing for no credit,  branching  to
the abort.  Use a second IF to test for over credit limit,  branching
to the abort.  Or reverse your tests and branch around the operation.

I  am not writing a textbook on programming here, nor ever will I  do
so.   APPLICATIONS  MAKER is written for those who  need  to  produce
simple  applications in order to do their work and are  possessed  of
little  or no programming ability.  By providing and  explaining  the
more intricate features of real programming languages I would totally
confuse such a person.

If  you are a programmer you should look in the \MAGE\DOCS  directory
and  find  sample source code, in BASIC and C,  to  process  DATAMAGE
files.   Due to it's six byte reals PASCAL is not equipped to  handle
these files.

DO ITEMS:  With the DO ITEMS the application will start execution  at
the  first  occurrence of the target label, and to continue  until  a
BREAK ITEM is encountered.

The  DO  and DO PRINT items will start looking for the label  at  the
beginning of their respective screens.  When you define a DO item  on
the  input screen you are, in effect, defining a FUNCTION  that  your
"program"  may call from anywhere within the input screen,  including
from  within the function itself.

A  function  that calls itself, in the jargon of the  programmer,  is
called a RECURSIVE function.  Many real programming languages do  not
allow recursion.

If  you  are  going to use DO items to  create  and  call  functions,
especially  recursive ones, a programming method called TOP  DOWN  is
highly recommended.  To do this you define all functions before  they
are  called.  Just place a GOTO item as your first screen  item,  and
use  as  it's target label the place in your screen  where  you  wish
execution of your application to start.  And place that label at  the
start of your control routine.

Between  the initial GOTO item and it's target label place  all  your
functions.  When you use a DO item to call a function you will go  to
the FIRST occurrence of that label.  If it's atop the screen you  may
re-use that label later without worrying about losing control.

Each  time a DO item is encountered the program uses a little  memory
to  record  DO's location so you can return when the  BREAK  item  is
executed.   If  your computer has less than the  full  compliment  of
640K, or your applications are extremely large you should watch using
recursive DO functions, as they may cause you to run out of memory.

If this happens the program will recover by displaying the  (DREADED)
out of memory error, and terminating your application.  This has  yet
to  happen,  but it could easily occur on a computer with  448K,  and
might happen up to 576K.

DO  PRINT ITEMS:  With the DO PRINT ITEMS the application will  start
report  execution at the first occurrence of the target label on  the
report  screen and continue until a BREAK ITEM is encountered in  the
report, or until the report ends.

BREAK ITEMS:  With the BREAK ITEMS the application will return to the
item  after  the DO which caused their execution.  If the DO  was  an
argument  to an IF the remainder of the arguments to the if  will  be
executed.   If  no DO is in effect when a BREAK item is  executed  it
will  be ignored.  BREAK items are also the target of forward  gotos.
BREAK items appear on both the input and report screens.

END ITEMS: With the END ITEMS the execution of the application halts.

LOCATE  ITEMS:  With the LOCATE ITEMS you may control  your  screens.
APPLICATIONS  MAKER  screens may be up to 100  SUB-SCREENS  wide  and
tall.  Each SUB-SCREEN is 78 columns wide and 19 lines tall.  You may
choose to use implement an application that uses ten SUB-SCREENS.

Each  of  your  ten horizontal screens might be a  task  within  your
application.   You will need to be able to control the  execution  of
your application so that it goes to the start of the desired  screen,
and  then  works it's way down while staying within  that  horizontal
boundary.  This is the purpose of the LOCATE ITEMS.

The  first  option  of the LOCATE items is to BEGIN  or  RELEASE  the
enforcement of the horizontal boundaries.

If  you use a DO to execute a function in your application  and  that
function  is  located  outside  the  horizontal  boundary  you   have
specified  you  will  need to release the LOCATE  ITEM  currently  in
effect.   When you complete the task associated with  the  horizontal
section  of  the  application you may wish to go back  to  the  first
screen  and display a menu item so that the user may  select  another
task,  or exit.  Again, you will need to release the current  LOCATE.
If you do not the application will end with a LABEL NOT FOUND error.

When you initialize a locate item you are prompted for the SUB-SCREEN
then  the vertical line within your application at which you wish  to
locate the screen.

The  LOCATE  ITEM also causes the program to ignore  any  LABELS  not
within the horizontal limits you specify.  If you use GOTO, GOBACK or
DO  items they will not find LABELS whose horizontal position in  the
application is not within the boundaries specified.

Your   screen  WILL  find  items  whose  vertical  position  in   the
application is not on the same visible screen as your starting point.
So,  you  may scroll the screen vertically to any position  you  wish
within the horizontal limits you set.