home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 December / simtel1292_SIMTEL_1292_Walnut_Creek.iso / msdos / turbopas / bonus507.arc / TPENV.ARC / TPENV.DOC < prev    next >
Text File  |  1988-11-07  |  11KB  |  226 lines
  1. TPENV - Routines for manipulating the DOS environment
  2. -----------------------------------------------------
  3. Kim Kokkonen
  4. TurboPower Software
  5. 10/88
  6. Version 1.0
  7. Released to the public domain
  8.  
  9.  
  10. Overview
  11. ------------------------------------------------------------------------------
  12. TPENV is a Turbo Pascal unit that allows application programs to manipulate
  13. the DOS environment by reading and setting environment strings in either the
  14. current program's environment or in the system master environment.
  15.  
  16. The environment is an area defined by DOS to pass limited amounts of ASCII
  17. text from one program to another. Standard strings stored in the environment
  18. are those associated with COMSPEC, PATH, and PROMPT. Although the DOS batch
  19. language provides the SET command to manipulate the environment, there are no
  20. standard function calls to access it from a program. The TPENV unit fills this
  21. gap.
  22.  
  23. TPENV provides another important function, useful to any program that provides
  24. a DOS shell. This function allows the specification of a custom DOS prompt
  25. within the shell. This prompt might show the name of the application, or a
  26. reminder to "type EXIT to continue".
  27.  
  28.  
  29. Using TPENV
  30. ------------------------------------------------------------------------------
  31. TPENV is designed to be used with Turbo Professional. If you don't have Turbo
  32. Professional, you can delete the conditional compilation symbol UseTpro found
  33. near the top of TPENV.PAS and TESTENV.PAS. Without Turbo Professional, you'll
  34. be able to use all of TPENV's functions except for the special DOS shell.
  35.  
  36. TESTENV is a small program that demonstrates TPENV. Compile it to an EXE file,
  37. and run it from the DOS command line. If you have Turbo Professional, it will
  38. first conduct you to a DOS shell with a customized prompt. Fiddle around in
  39. the shell, and then enter EXIT to return to the test program. Next, it will
  40. show how you can modify the DOS master environment from within a program. Be
  41. careful: any changes you make to the DOS environment will remain in force when
  42. you quit the program.
  43.  
  44. TPENV interfaces about a dozen routines to manipulate the environment. Almost
  45. all of these complement the routines found in Turbo Pascal 5's DOS unit, and
  46. all of them do something that TP4's DOS unit doesn't. Here's a rundown of the
  47. data types and procedures in TPENV:
  48.  
  49. type
  50.   EnvRec =
  51.     record
  52.       EnvSeg : Word;
  53.       EnvLen : Word;
  54.       EnvPtr : Pointer;
  55.     end;
  56.  
  57. This type is TPENV's way of packaging information about the environment.
  58. You'll pass a parameter of this type to almost all of TPENV's routines. EnvSeg
  59. is the segment address of the environment. At this address starts a list of
  60. null-terminated strings that may extend for up to 32K characters. EnvLen is
  61. the maximum usable length of that environment (not the amount currently in
  62. use). EnvPtr is normally nil. It is used only when you allocate new
  63. environment space from the Turbo Pascal heap, and even then you won't want to
  64. refer to the EnvPtr field directly.
  65.  
  66. If an error occurs in one of TPENV's routines, the EnvSeg field will remain
  67. at zero. You shouldn't continue processing with an environment record if
  68. EnvSeg is zero.
  69.  
  70. const
  71.   ShellUserProc : Pointer = nil;
  72.  
  73. This constant is used only when you call the ShellWithPrompt function. It
  74. contains the address of a user routine passed to the (Turbo Professional)
  75. ExecDos routine (from the TPDOS unit). You'll probably want to leave it nil,
  76. but the constant is available should you wish to take advantage of this
  77. powerful ExecDos feature.
  78.  
  79. procedure MasterEnv(var Env : EnvRec);
  80.  
  81.   Returns a record for the master system environment. Changes to this
  82.   environment are retained after the current program exits. Finding the master
  83.   environment is a little tricky, and if for some reason the method doesn't
  84.   work on your system, the EnvSeg field of the returned environment record
  85.   will be set to zero. The master environment for the system is typically
  86.   larger than that for the current program -- DOS copies only the portion of
  87.   the master environment that is actually in use when it runs each program.
  88.  
  89. procedure CurrentEnv(var Env : EnvRec);
  90.  
  91.   Returns a record for the current program's environment. There isn't much
  92.   space left to add to this environment (see above), and any changes made to
  93.   it are lost when the current program ends. On the plus side, under DOS 3.0
  94.   or later, there is an additional string at the end of this environment which
  95.   specifies the complete pathname of the current program. TPENV offers a
  96.   special routine to return this pathname: see the ProgramStr function.
  97.  
  98. procedure NewEnv(var Env : EnvRec; Size : Word);
  99.  
  100.   Allocates space for a new environment, from the Pascal heap. The most likely
  101.   use for this routine will be in a program that spawns other programs and
  102.   needs to pass a lot of environment information to them. Size specifies the
  103.   number of bytes to reserve for the new environment. NewEnv actually
  104.   allocates 31 bytes more than you request, to assure that paragraph
  105.   alignment is possible and to create a fake DOS memory control block which
  106.   keeps other programs and routines happy. If there isn't sufficient heap
  107.   space to allocate the new environment, NewEnv returns the EnvSeg field of
  108.   Env set to zero.
  109.  
  110.   After a call to this routine, the new environment is totally filled with
  111.   nulls. Use the CopyEnv routine to copy from another environment to
  112.   initialize the new one.
  113.  
  114. procedure DisposeEnv(var Env : EnvRec);
  115.  
  116.   Deallocates heap space for an environment previously allocated with NewEnv.
  117.   Calling DisposeEnv with the master or current environment record as a
  118.   parameter does nothing.
  119.  
  120. procedure SetCurrentEnv(Env : EnvRec);
  121.  
  122.   Sets the environment of the current program to a different one, the one
  123.   specified by the Env parameter. You'll want to do this after calling NewEnv
  124.   and initializing the new environment, but before spawning a child process.
  125.   DOS copies the current environment to the child process. To keep from
  126.   messing up DOS's own memory allocation, you should always restore the
  127.   current environment to the one DOS allocated before quitting a program. See
  128.   the calls to SetCurrentEnv in ShellWithPrompt for an example.
  129.  
  130. procedure CopyEnv(Src, Dest : EnvRec);
  131.  
  132.   Copies one environment to another. If the Dest environment is smaller than
  133.   the Src, CopyEnv copies what it can and truncates the last element wherever
  134.   it must. The copy never includes the pathname information that DOS 3.0+
  135.   tacks at the end of the normal environment. If this information is
  136.   needed, you can usually use the SetProgramStr function to copy it. See
  137.   ShellWithPrompt for an example of how to do this.
  138.  
  139. function EnvFree(Env : EnvRec) : Word;
  140.  
  141.   Returns the number of bytes unused in the specified environment. You may
  142.   want to check this value before adding a new string to the environment,
  143.   although SetEnvStr checks as well.
  144.  
  145. function GetEnvStr(Env : EnvRec; Search : string) : string;
  146.  
  147.   Returns the value of a particular environment string. For example, to check
  148.   the value of the COMSPEC environment setting in the master environment, you
  149.   would code a sequence like the following:
  150.  
  151.     var
  152.       E : EnvRec;
  153.     begin
  154.       MasterEnv(E);
  155.       WriteLn('Master setting for COMSPEC is ', GetEnvStr(E, 'COMSPEC'));
  156.     end.
  157.  
  158.   The search string may end with '=' if desired, but GetEnvStr will append an
  159.   equal sign if needed. Searching is not case sensitive. White space in the
  160.   search string is important and should generally be avoided. If GetEnvStr
  161.   finds no matching environment string, it returns an empty string.
  162.  
  163. function SetEnvStr(Env : EnvRec; Search, Value : string) : Boolean;
  164.  
  165.   Sets the value of an environment string. Note that you can set the value in
  166.   the master or current environment, depending on how the Env parameter was
  167.   initialized. Search specifies the name of the environment string to change,
  168.   for example, 'COMSPEC'. Value specifies its new value. If Value is the empty
  169.   string, the entire item is removed from the environment. New values are
  170.   always added to the end of the environment, after first removing any
  171.   replaced value from the middle. If there is insufficient space for the new
  172.   environment value, SetEnvStr returns False, otherwise true. See TESTENV.PAS
  173.   for an example of using SetEnvStr.
  174.  
  175.   This routine has one side effect. If the environment to be changed is the
  176.   current environment, SetEnvStr wipes out the program path name stored beyond
  177.   the end of the environment under DOS 3.0 and later. If you need to access
  178.   this pathname, be sure to do so (via the ProgramStr function) before calling
  179.   SetEnvStr.
  180.  
  181. procedure DumpEnv(Env : EnvRec);
  182.  
  183.   Parses and writes each element of the environment to the output device. The
  184.   listing is terminated with the number of unused bytes in the environment.
  185.  
  186. function ProgramStr : string;
  187.  
  188.   Returns the complete pathname of the current program, if DOS 3.0 or later is
  189.   installed. Otherwise returns the empty string. Under Turbo Pascal 5, the
  190.   same result may be obtained by using the expression ParamStr(0).
  191.  
  192. function SetProgramStr(Env : EnvRec; Path : string) : Boolean;
  193.  
  194.   Provides a method to set the program path name, normally available under DOS
  195.   3.0 or later. Path is appended to the specified environment just like DOS
  196.   would do it. If insufficient space remains, SetProgramStr does nothing and
  197.   returns False.
  198.  
  199. function ShellWithPrompt(Prompt : string) : Integer;
  200.  
  201.   Starts a DOS shell with the prompt set to the specified value. The user can
  202.   execute DOS commands until EXIT is entered, and then the calling program
  203.   continues. This routine depends on the ExecDos routine from Turbo
  204.   Professional for the mechanics of the shell. If you don't have Turbo
  205.   Professional, you could modify the routine to use Turbo Pascal's Exec
  206.   routine instead.
  207.  
  208.   The Prompt string may specify any valid DOS prompt, including the
  209.   metacommands such as $p$g, and ANSI escape sequences if ANSI is installed.
  210.   The prompt totally replaces the existing prompt until the shell returns.
  211.  
  212.   ShellWithPrompt allocates heap space for a new environment including the
  213.   specified Prompt. Heap space is allocated even if the prompt would fit in
  214.   the existing environment. The new environment is a copy of the current one,
  215.   with the PROMPT entry changed.
  216.  
  217.   ShellWithPrompt returns a status value in the function result. The value
  218.   will be zero for a successful exec. Positive values are interpreted as
  219.   DOS error codes. Negative values are error codes specific to ExecDos and
  220.   ShellWithPrompt. See the Turbo Professional manual for a listing of the
  221.   error codes -1..-4. ShellWithPrompt adds the following codes:
  222.  
  223.     -5 Can't read current environment
  224.     -6 Insufficient heap space for new environment
  225.     -7 Space calculation error (shouldn't happen)
  226.