                            Miscellaneous Routines

                                      "You yourself are much condemned
                                      to have an itching palm; to sell
                                      and mart your offices for Gold."

                                        Shakespeare, Julius Caesar IV.3

Introduction

          The GoldMISC unit contains a grab-bag of miscellaneous
     procedures and functions that really do not call for an entire unit
     of their own. They may, one day, grow up and have their own units.
     Some of these routines were developed to support other units, and
     may be of little value to you on a regular basis. Nonetheless, they
     are here if you need them. The routines are organized into three
     categories: File, Printer and Misc.

File Routines

     FSize(Filename:string): longint;

          Returns a longint indicating the size of the file in bytes. If
          the FileName passed is not found, a -1 value is returned.

     FileDrive(Full:string): string;

          Extracts and returns the drive letter (without the colon) from
          a filename. If the passed string parameter does not include a
          drive, a null is returned, i.e. ''.

     FileExt(Full:string): string;

          Extracts the file extension (excluding the period) from a
          filename. If the passed string parameter does not include an
          extension, a null is returned, i.e. ''.

     FileDirectory(Full:string): string;

          Extracts the directory path (without the drive letter) from a
          filename. If the passed string parameter does not include an
          extension, a null is returned, i.e. ''. The trailing backslash
          is always removed.

     FileName(Full:string): string;

          Extracts the file name (excluding the extension) from a
          filename. If the passed string parameter does not include an
          extension, a null is returned, i.e. ''.

     SlashedDirectory(Dir:string):string;

          This function is useful for building fully-qualified
          filenames. The passed directory name is returned, with a
          backslash added if the string did not already terminate with a
          backslash or colon.

     ParentDirectory(Dir:string): string;

          Returns the name of the parent to the directory string passed.
          If only the root directory is passed then the root is
          returned. A null string is returned if the string passed does
          not contain a parent.

     SmartMakeDir(DirectStr: PathStr): integer;

          Parses the passed string and creates each subdirectory as it
          progresses. The final product is a newly created (or nested)
          subdirectory. The passed string must follow the DOS naming
          conventions. Failures are recorded in  LastMiscError.

     Exist(Filename:string):boolean;

          Returns true if the filename can be found. The passed string
          must follow all the DOS naming conventions.

     DeleteFile(Filename:string): shortint;

          Designed to delete the filename passed, this function returns
          a shortint value indicating the results of the routine, as
          follows:

               -1 - File not found
                0 - File deleted {success}
                1 - Error - file not deleted.

     RenameFile(Oldname,NewName:string):shortint;

          Attempts to rename the old filename to the new filename.
          Returns a shortint value indicating the results, as follows:

               0 - File renamed {success}
               1 - File not found
               2 - Rename failed

     CopyFile(SourceFile, TargetFile:string): shortint;

          Copies a file like the DOS copy command. If a file with the
          same name as the Target already exists, it will be
          overwritten. The function returns one of the following byte
          values:

               0 - Successful
               1 - Source and Target are the same
               2 - Cannot open source
               3 - Unable to create target
               4 - Error during copy

Printer Routines

     The GoldMISC unit includes the following printer related routines:

     PrinterStatus:byte;

          This function is designed to indicate whether or not a
          parallel printer is attached and on-line. The global variable
          MiscVARS.LPTport indicates which port to test. Set
          MiscVARS.LPTport to 0 for LPT1 (default), 1 for LPT2, etc. The
          function returns one of the following byte values to indicate
          the status of the printer:

               0 - Printer ready
               1 - No paper
               2 - Off line
               3 - Busy
               4 - Undetermined error

     AlternatePrinterStatus:byte;

          This function is very similar in operation to PrinterStatus
          but uses a slightly different technique. If you have problems
          using PrinterStatus with some weirdo printer, try this
          function instead.

     PrinterReady :boolean;

          This function returns true if a printer is detected as being
          on-line and ready.

     PrintScreen;

          This procedure emulates the user pressing the PrtScr key, and
          dumps the visible display to the printer port.

     ResetPrinter;

          This procedure should reset any printer back to its default
          (boot-up) settings.

Memory Info

          It is not a good idea to use every scrap of available memory
     on the heap, as your program will tend to be unstable. Also, with
     no memory left, it is difficult to display information to the user
     advising him/her of the low memory.

          The GoldMISC unit includes a longint variable,
     MiscVARS.GoldMemBuffer, with a default value of 10,000 bytes. This
     represents the amount of memory which will be left free when Gold
     routines try to allocate memory on the heap. You may change the
     value as necessary.

          The following functions should be used in preference to
     MemAvail and MaxAvail:

     GoldMaxAvail:longint;

          After deducting the amount of memory reserved by
          MiscVars.GoldMemBuffer, this routine returns the size of the
          largest contiguous amount of free memory.

     GoldMemAvail:longint;

          After deducting the amount of memory reserved by
          MiscVars.GoldMemBuffer, this routine returns the total amount
          of free memory.

Sounds

     The GoldMISC unit includes the following sound routines:

     Beep;

          You guessed! This function emits a brief, but nonetheless
          irritating, beep from the PC speaker.

     Ding;

          Teensy Weensy little noise.

     Thunk;

          Somewhat negative sounding, like wrong key press.

     Trill;

          Great feedback. It indicates success.

Executing Other Programs

          The three routines listed below can be used to execute another
     program or application from within the active application.

          IMPORTANT NOTE: You must use the $M compiler directive to
     instruct Borland Pascal to leave some memory for the spawned or
     child program, e.g.{$M $8192,$8192,$8192}. The precise values
     depend on the size of your program, so experiment to determine the
     optimum settings. If the child process runs OK, try smaller values.
     If the child process doesn't run, try larger values.

     RunEXECOM(Progname, Params: string):integer;

          Executes an EXE or COM file as a child process. Pass two
          parameters, the name of the program and the optional
          parameters. Returns an integer value indicating the returned
          DosError value; a zero indicates success.

     RunDOS(Msg:string):integer;

          Starts a secondary copy of COMMAND.COM. One parameter is
          passed which is the message provided to the user. Returns an
          integer value indicating the returned DosError value; a zero
          indicates success.

     RunAnything(Command: string):integer;

          Spawns a child process from your application. Use this to run
          non-executables such as batch files. Returns an integer value
          indicating the returned DosError value; a zero indicates
          success.

Development Tools

          If you look at any of the demo programs, you will find the
     HeapRecord and HeapCheck routines used in each one. These routines
     are designed to identify memory leaks in an application. If the
     application finishes with less memory than when it started, an
     error message is displayed. These routines were used extensively
     during Gold's development!

          Memory leaks can occur, for example, when you forget to call
     the function DisposeFields having created and used a form. When you
     are developing applications, make it a habit to use these routines
     to make sure that you have disposed of all memory you used.

     HeapRecord;

          Records the amount of available memory when the routine is
          called. Call this procedure as the first statement in an
          application.

     HeapCheck;

          Records the amount of available memory when the routine is
          called and  compares it to the amount recorded by HeapRecord.
          Differences are displayed on screen. Calling this routine
          without first calling HeapRecord has no effect.

          Clearly you don't want these routines to be left in the
     production code. If you have a memory leak in your application, you
     certainly don't want your customer to see it! You should consider
     placing these calls inside conditional defines. The following code
     fragment illustrates this technique.

          begin
          {$IFOPT D+}
              HeapRecord;
          {$ENDIF}
              InitVars;
              SetScreen;
              SetFields;
              MouseShow(true);
              AssignHindHook(MyHindHook);
              ProcessInput(1);
              DisposeFields;
              DisposeForms;
              MouseShow(false);
              clrscr;
          {$IFOPT D+}
              HeapCheck;
          {$ENDIF}
          end.

Miscellaneous

          Here are the routines that don't fit into any specific
     category:

     GetBitStatus(B:byte;BitPos:byte): boolean;

          Returns the status of a single bit contained within a byte.
          You store and retrieve up to 8 boolean values in a single
          byte; these are numbered 0 through 7.

     SetBitStatus(var Val:byte; BitPos:byte; On:boolean);

          Used to change the value of a single bit within a byte.

     Swap(var A,B:longint);

          Switches the values of A and B.

     WithinRange(Min,Max,Test: longint): boolean;

          Determines whether or not the value contained in Test falls
          between the upper and lower limits set in Min and Max and
          returns an appropriate true or false value.

     GetMin(Value1,Value2:longint): longint;

          Returns the smallest of the two passed values.

     GetMax(Value1,Value2:longint): longint;

          Returns the largest of the two values passed.

     ParamLine: string;

          Returns the entire parameter line as a space-delimited string,
          i.e. all the parameters specified by the user on the command
          line when the application was executed.

     ParamVal(Marker:string): string;

          Searches for Marker in the command line and returns all
          characters following the string up to the next occurrence of
          the marker.

     Frequency(Match:string;Source:string): byte;

          Returns the number of times that Match occurs in Source.

     BadCharPos(Str:string): integer;

          This function is used for checking for invalid filename
          characters in a string. The function returns the character
          position of the first illegal character, or 0 if no illegal
          characters were encountered.

     ValidFileName(FN:string): shortint;

          Verifies whether a filename is valid. Refer to the Reference
          for a list of the possible return codes.

     LastMiscError: integer;

          Dealing with memory and DOS shells certainly leaves an
          application open to failure. LastMiscError should be checked
          regularly to determine whether the last call to a GoldMISC
          function was successful.


     El blanko pageo on purpuso


