home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 9 / 09.iso / l / l010 / 5.ddi / C5.ARC / BBX_C.DOC < prev    next >
Encoding:
Text File  |  1989-12-20  |  5.5 KB  |  152 lines
  1. C is the only language besides assembly language that can be used for writing
  2. memory-based BlackBoxes.  Disk-Based BlackBoxes are also easy to do in C.
  3.  
  4.  
  5. ; ----------------------- MEMORY-BASED BLACKBOXES -----------------------
  6.  
  7.  
  8. When writing a Memory-Based BlackBox, you will need to generate two versions
  9. of your source code.  The first version will be for the .OBJ to link into
  10. your source code, and the second will be for creating the .BBX.
  11.  
  12.  
  13. The steps for writing a Memory-Based BlackBox in C are as follows:
  14.  
  15.  
  16. 1.  Write the C procedure as you normally would for an external procedure
  17.     to be called from another C routine.  Remember that BlackBoxes are
  18.     always treated as procedures, not functions.
  19.  
  20.     For BlackBoxes, it is a good idea to keep to the following rules:
  21.  
  22.     1. Any temporary space that's allocated should be released by the
  23.        procedure before exiting.
  24.  
  25.     2. Do NOT access the enviroment strings!  As a C BlackBox, you do not
  26.        have access to the enviroment strings of the program, since you do
  27.        not know whether you are being run by FLOWCHRT.EXE or the created
  28.        program.
  29.  
  30.     3. Try to make the BlackBoxes as self-contained as possible.
  31.  
  32.  
  33. 2.  For the parameters of the C procedure, the first is ALWAYS going to
  34.     be an integer passed by value.  This will be the LANGUAGE TYPE of the
  35.     calling procedure.    Most BlackBoxes will not use this, but it must
  36.     still be declared as the first parameter in the BlackBox.  The rest
  37.     of the parameters follow in the reverse order that you intend to
  38.     request.
  39.  
  40.     For example, if you want the BlackBox to request the following:
  41.  
  42.      1.   An Integer Value to be passed
  43.      2.   A Resulting Integer Variable (int *)
  44.      3.   A Resulting CheckBox Variable (char *
  45.  
  46.     The declaration of the procedure would look like this:
  47.  
  48.      void YOUR_BLACKBOX (lang_type, CheckBox_Result, Int_Result, Int_Value)
  49.  
  50.      int lang_type, Int_Value, *Int_Result;
  51.      char *CheckBox_Result;
  52.  
  53. 3.  The C file should be ready for creating the .OBJ to link into the compiled
  54.     C program.    Compile, but do not link, this file, and copy the .OBJ created
  55.     to a different name.  The naming convention used by MATRIX is to add a
  56.     c on to the file name, so that name.OBJ becomes nameC.obj.
  57.  
  58.  
  59. 4.  In the source code, change the name of the BlackBox procedures to "main".
  60.     This will create a .C suitable to make the .BBX.  Compile this file and
  61.     link it with the libraries CBBX_LIB+LLIBCE, along with the /NOE and /NOD
  62.     flags.  The order of the libraries is very important!  You MUST link
  63.     CBBX_LIB first, because it contains a modified version of the C Startup
  64.     Code to accomodate the BlackBox structure.    Rename this file to a .BBX.
  65.  
  66.     The Link command would might look like this:
  67.  
  68.     LINK /NOD /NOE your_bbx, your_bbx.bbx ,,CBBX_LIB+LLIBCE;
  69.  
  70.  
  71.  
  72.  
  73. ; ------------------------ DISK-BASED BLACKBOXES ------------------------
  74.  
  75. A Disk-Based BlackBox written in C is basically a normal, self-contained,
  76. executable program which follows a few simple rules.
  77.  
  78. 1.  Any memory which is allocated by the disk-based blackbox MUST be
  79.     deallocated before exiting the program.
  80.  
  81. 2.  Any File Handles which are opened must be closed before exiting the
  82.     program.
  83.  
  84. 3.  The Disk-Based BlackBox CANNOT leave the screen in text mode before
  85.     exiting, and it should preserve the top two lines of the screen in
  86.     case a menu is present from the calling procedure.
  87.  
  88. 4.  The Interrupt vectors 0F3H and 0F4H cannot be replaced.
  89.  
  90. 5.  The program must exit normally, it cannot terminate and stay resident.
  91.  
  92.  
  93. The procedure for calling a disk-based blackbox is as follows:
  94.  
  95. 1.  The parameters are pushed on the stack as if calling a memory-based
  96.     blackbox.  Note that the last parameter pushed will always be the
  97.     LANGUAGE_TYPE integer value.
  98.  
  99. 2.  The value of the stack pointer and stack segment is stored in the
  100.     graphics device driver using int 0F3H
  101.  
  102. 3.  An EXEC call (DOS CALL 21H, subfunction 4BH) is made to load and
  103.     execute the disk-based blackbox.
  104.  
  105. 4.  Your Disk-Based BlackBox makes a call to int 0F3H to obtain the
  106.     stored pointer to the passed data.
  107.  
  108. 5.  Whatever action required is performed.
  109.  
  110. 6.  Return whatever status values using the pointers passed.
  111.  
  112. 6.  Your Disk-Based BlackBox exits normally, after having deallocated any
  113.     allocated memory and closing any file handles.
  114.  
  115. 7.  The calling program continues execution.
  116.  
  117.  
  118. The call for obtaining the pointer to the passed data is:
  119.  
  120.     parameter_block = GET_BLACKBOX_PARAM_PTR ();
  121.  
  122.     This returns a far pointer to a parameter block, whose structure is
  123.     determined by the parameters requested by the BlackBox.
  124.  
  125.     The first field in the parameter block structure is always an integer
  126.     value, LANGUAGE_TYPE, which indicates the language of the calling
  127.     procedure.    Then those parameters in the header file follow in reverse
  128.     order.
  129.  
  130.     Example:  A Disk-Based BlackBox which asks for
  131.  
  132.      1. A File Name (pointer to array of characters)
  133.      2. An Integer Value (passed by value)
  134.      3. An Integer Variable (passed by reference)
  135.      4. A CheckBox Variable (passed by reference)
  136.  
  137.     The Structure for the parameter block would be:
  138.  
  139.     struct BlackBox_Parameter_Block {
  140.  
  141.      unsigned language_type;
  142.      char *CheckBox_Variable;      /* CheckBoxes are of type char */
  143.      int *Integer_Variable;
  144.      int Integer_Value;
  145.      char *File_Name;
  146.  
  147.     };
  148.  
  149. In order to access the GET_BLACKBOX_PARAMETER_PTR call, you must link in
  150. the object module BBXPTR_C.OBJ on this disk.
  151.  
  152.