home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / database / msg.zip / MSG.DOC < prev    next >
Text File  |  1988-10-24  |  9KB  |  234 lines
  1.  
  2.                                     MSG()
  3.                        For Clipper, version Summer '87
  4.                              by Steve Badaracco
  5.                                   10/24/88
  6.  
  7.      MSG() is a function written in Clipper which makes use of the new low
  8.      level file I/O functions.  The purpose is to allow your application to
  9.      read text strings from an external message file at runtime.
  10.  
  11.      Why?  Because Clipper stores character strings from your source code
  12.      into the output (EXE) file.  As a result, each byte of text is one less
  13.      byte of RAM available to your application!  If you want a user-friendly
  14.      application with lots of messages, you generally get a MEMORY-HOG.
  15.  
  16.      With MSG(), you can store text strings externally, for use in ...
  17.         @...Say <text>
  18.         ?/?? <text>
  19.         @...Prompt <text> Message <text>
  20.         [MemVar] = <text>
  21.         @...Get [MemVar/Field] Picture <text> Valid &<text>.
  22.         Accept/Input <text> to [MemVar]
  23.         KeyBoard <text>
  24.         Replace [Field] With <text>
  25.         Run/! &<text>.
  26.         Set Filter To &<text>.
  27.         Set Path To (<text>)
  28.         Wait <text>
  29.      and many, many more commands and functions.  Just use MSG() wherever
  30.      a long character string ("<expC>") would otherwise be used.
  31.  
  32.      Using macro expansion you can even store complex VALIDs or FILTER
  33.      expressions in the external file (of course, you may have to use
  34.      EXTERNAL commands to ensure that the necessary functions are linked
  35.      into your application).
  36.      For example ...
  37.         OLD code:
  38.          USE CONTACTS
  39.          Set Filter To (.Not.Deleted()).And.(LenNum(CONTACTS->CONNUM)#0);
  40.            .And.(CONTACTS->ACCTEXEC='Smith').And.(CONTACTS->EFFDATE=Date())
  41.         NEW code:
  42.          USE CONTACTS
  43.          Filt = Msg(22)
  44.          Set Filter To &Filt.
  45.  
  46.      MSG() v1.00 is being introduced into the public domain.  That is, you
  47.      can copy the program all you want, and give it to whomever you want.
  48.      I have omitted the source code only because I hope to include it in
  49.      a library which I am working on.  I ask for no money, but I certainly
  50.      would not refuse any if it came!
  51.      << Disclaimer >>
  52.      | Please note that MSG() has not been fully tested under all runtime
  53.      | conditions...it works on my IBM PS/2, running my own applications.
  54.      | MSG() is being released "as is" with no warranty, expressed or
  55.      | implied, as to usability, "safety", or fitness for a particular use.
  56.      | In no event will I be liable for any direct, indirect, or
  57.      | consequential damages, real or imagined.
  58.  
  59.      Please report any bugs to me at the following address:
  60.                              Steve Badaracco
  61.                              48 Park Street
  62.                              Willimantic, CT  06226
  63.      or leave me a message on THE BOSS BBS Clipper conference.
  64.      Incidentally, THE BOSS has the best Clipper conference going,
  65.      hands down!   The number is (201) 568-7293.
  66.  
  67.                                     -2-
  68.  
  69.  
  70.      SYNTAX:
  71.  
  72.        MSG([<expN>[,<expL>]])
  73.  
  74.  
  75.      ARGUMENTS:
  76.  
  77.        Calling MSG() with no arguments will attempt to close the .MSG
  78.        file, should it be open.
  79.        It is advisable to do this before QUITting your application.
  80.  
  81.        <expN> is the line number in the .MSG file to be returned as
  82.               a character expression.  If this argument is not numeric,
  83.               MSG() will return "<record not found>".
  84.  
  85.        <expL> is result class, should an error occur.
  86.               The argument is optional, and defaults to .T.
  87.               .T.  will result in a fatal error, reported through the
  88.                    error system function MISC_ERROR().
  89.               .F.  will result in a non-fatal error, and return a "*".
  90.  
  91.  
  92.      RETURNS:
  93.  
  94.        MSG():
  95.        If the .MSG file had been open, and was properly closed, ".T." .
  96.        If the .MSG file was not open, or was open but could not be
  97.          closed, ".F." .
  98.        Note that the returns are of type CHARACTER, to maintain
  99.          compatibility with other return values.
  100.  
  101.        MSG(<expN>[,.T.]) : FATAL error class
  102.        If the specified line number exists in the proper format in the
  103.          .MSG file, the char string contained in that line is returned.
  104.        If an error occurred, MISC_ERROR() is called, with the following
  105.          arguments:
  106.          NAME:  "<filename>.MSG, record <line # from expN>"
  107.          LINE:  913
  108.          INFO:  "<applicable error message: see below>"
  109.  
  110.        MSG(<expN>,.F.) : NON-FATAL error class
  111.        If the specified line number exists in the proper format in the
  112.          .MSG file, the char string contained in that line is returned.
  113.        If an error occurred, the value "*" is returned so that processing
  114.          can continue.
  115.  
  116.                                     -3-
  117.  
  118.        ERROR MESSAGES passed to MISC_ERROR():
  119.  
  120.        "<file is not accessible>": Could not open the file SYSTEM.MSG.
  121.          If you have specified an alternate filename, then could not
  122.          open the file &sysn..MSG.  See ENVIRONMENT.
  123.  
  124.        "<record not found>": Could not find the line # specified in <expN>.
  125.          This could mean (1)that <expN> was not numeric, (2)that the line
  126.          does not, in fact, exist, or (3)that a previous line is not 85
  127.          positions long, including the CR/LF pair.  See FILE FORMAT.
  128.  
  129.        "<EOR/delimiter error>": The line does not contain a character
  130.          expression.  This could mean (1)that the EOR (end-of-record) byte
  131.          is misplaced, (2)that a previous line is not 85 positions long,
  132.          including the CR/LF pair, or (3)that the line is not in the proper
  133.          format.  See FILE FORMAT.
  134.  
  135.        "<undetermined error>": Any other miscellaneous condition.
  136.  
  137.  
  138.      ENVIRONMENT:
  139.  
  140.        There are two variables used which are external to MSG().
  141.        All others are declared PRIVATE.  The two externals are:
  142.  
  143.        MSGHANDLE (public):
  144.        This one is created on the first call to MSG() with argument(s).
  145.        Contains the value .F. if the .MSG file is closed.
  146.        Contains a numeric value representing the DOS file handle if the
  147.        .MSG file is open.
  148.  
  149.        SYSN (public):
  150.        This is not created by MSG().
  151.        If you wish to use a .MSG filename other than the default,
  152.        which is "SYSTEM", then declare a PUBLIC variable SYSN, and
  153.        assign to it a valid DOS filename (1..8 characters, no extension).
  154.        In this case, &sysn..MSG will be searched by MSG().
  155.        Note that if you use more than one file, you MUST close one before
  156.        searching another.  Use MSG() without arguments to do this.
  157.  
  158.  
  159.      FILE FORMAT:
  160.  
  161.        See the sample file SYSTEM.MSG, supplied with this ARC file.
  162.        The .MSG. file is a pseudo-database; each line is an 85-byte
  163.        record, in the following format:
  164.           1..82: Is a valid Clipper character expression. Don't
  165.                  forget to use quotes ( '',  "",  or  [] ) !
  166.              83: Is any character used to mark the end of the record (EOR).
  167.                  The purpose is to make it possible to edit the .MSG file
  168.                  using an editor which does not allow positioning of the
  169.                  end-of-line marker (i.e. SideKick).
  170.          84..85: Is the CR/LF sequence inserted in the file by your editor
  171.                  when the Return key is pressed.
  172.  
  173.                                     -4-
  174.  
  175.      LINKING MSGFUNC.OBJ WITH YOUR APPLICATION:
  176.        You need to have Clipper, version Summer '87.
  177.        The MSG() function is contained in the file MSGFUNC.OBJ and must
  178.        be linked with your application.  Here is the syntax for linking
  179.        with PLINK-86 Plus, Microsoft Link, or Turbo Link:
  180.  
  181.        PLINK86 FI <yourprgs>,MSGFUNC LIB CLIPPER,EXTEND
  182.  
  183.        LINK <yourprgs>+MSGFUNC,,,CLIPPER+EXTEND
  184.  
  185.        TLINK <yourprgs>+MSGFUNC,,,CLIPPER+EXTEND
  186.  
  187.  
  188.      TO COMPILE AND LINK THE DEMO:
  189.  
  190.        You need to have Clipper, version Summer '87.
  191.        First compile the demo program:
  192.  
  193.        CLIPPER DEMO
  194.  
  195.        Then link:
  196.  
  197.        PLINK86 FI DEMO,MSGFUNC LIB CLIPPER,EXTEND
  198.  
  199.        LINK DEMO+MSGFUNC,,,CLIPPER+EXTEND
  200.  
  201.        TLINK DEMO+MSGFUNC,,,CLIPPER+EXTEND
  202.  
  203.        Now run it:
  204.  
  205.        DEMO
  206.  
  207.  
  208.      CRITICAL ERROR HANDLING:
  209.  
  210.        Since we have the capability in Summer '87 of handling Clipper
  211.        critical errors, many folks have undertaken to write their own
  212.        error functions to replace MISC_ERROR(), etc.
  213.  
  214.        I highly recommend DMSERROR.PRG, marketed by
  215.          Data Management Systems
  216.          PO Box 3104
  217.          Fallbrook, California 92028
  218.          (619) 728-0984.
  219.  
  220.        This system is an excellent vehicle for handling all critical
  221.        errors in a uniform way.
  222.        It is shareware, and can be found on most BBS's which have a
  223.        Clipper conference (try THE BOSS first!).
  224.        <End of free advertisement.>
  225.  
  226.  
  227.      LEGAL STUFF:
  228.  
  229.        NANTUCKET is a registered trademark of Nantucket Corporation.
  230.        CLIPPER is a trademark of Nantucket Corporation.
  231.        PLINK86-Plus is a trademark of Phoenix Technologies, Ltd.
  232.        MICROSOFT LINK is a registered trademark of Microsoft Corp.
  233.        TURBO LINK is a trademark of Borland International, Inc.
  234.