Contents -------- Section 1 Program Description Section 2 Screen File Section 3 INI File Parameters Section 4 Errors / Return Codes Section 5 Special Notes / Considerations Section 6 Examples ENVFORM is a C program I wrote to accomplish a specific need. Upon completion, I decided to distribute it under the shareware concept. You may use the software to determine if it meets your needs. If you then decide to continue using the software you pay a license fee to the author. The license fee for this package is $10.00. This fee entitles you to use the software royalty free. If you choose to license ENVFORM, please send the $10.00 license fee to: Steve Lundeen Software Integration Group, Inc. P.O. Box 723847 Atlanta, GA 31139 Whatever you decide to do, please distribute this software to any bulletin boards you wish. I may be contacted at CIS[71051,1243]. ENVFORM uses The Window Boss screen I/O routines provided by Philip A. Mongelluzzo, Star Guidance Consulting, Inc. DISCLAIMER ---------- THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED. We cannot be held liable for any loss of profit or any other commercial damage, including but not limited to, special; incidental; consequential; or other damages. Section 1 - Program Description ------------------------------- ENVFORM is a parameter driven program which allows you to perform full screen input of DOS enviroment variables. The fields can be set to the values of DOS environment variables pior to the calling of the program, allowing you to establish desired defaults. ENVFORM is also capable of displaying error messages to instruct the user to re-enter invalid information. ENVFORM requires the use of two files, an .INI file which contains control information and a text file which is displayed on the screen upon program entry. When invoked, ENVFORM parses the passed INI file for required information. If any required parameters are not specified, the program will set the appropriate return code and terminate. After successfully interrogating the INI file, the program will then display the screen contained in the text file specified. Next, the program will solicite input from the user to fill the defined fields. If the user presses escape to exit the screen, a return code will be set to denote this action. Once the user accepts the entries, the DOS environment variables are set and, if specified, a batch file is created in the designated directory. Optionally, ENVFORM can invoke another program upon entry of all the fields. Section 2 - Screen File ----------------------- The screen file is typically a 24 row by 80 column text file. This file is written to the screen, starting at the top left corner. Row 25 is reserved for program use. Included with this download are four sample screen form files, FORM1.TXT through FORM4.TXT. These are just text files which can be used for initial form design or as copy and paste objects. Section 3 - INI File Parameters ------------------------------- The INI file consists of the following sections and keys: [ENVFORM] SCREEN=text file name RUN=program file to invoke BATCH=batch file name for SET statements ERRORLOCATION=row,column PUTFORECOLOR=color PUTBACKCOLOR=color GETFORECOLOR=color GETBACKCOLOR=color [ENVVARS] var1=row,column,length var2= row,column,length varn= row,column,length [ENVTEXT] var1=row,column,foreground color,background color var2=row,column,foreground color,background color . . varn=row,column,foreground color,background color [ENVFORM] section SCREEN=text file name Specify the name of the text file to be displayed upon program entry. This file can contain any displayable ASCII characters. This file should not be more than 24 rows by 80 columns. RUN=program file to invoke Specify the name of the program to run after the user accepts the input. This can be a .BAT, .COM, or .EXE file. This program will receive a copy of the environment which contains the specified DOS environment variables. BATCH=batch file name for SET statements If specified, this batch file will be created and contain DOS SET statements which can be execute to set the environment variables specified. This is useful for integrating ENVFORM with batch files. ENVLOCATION=row,column Specify the row and column to display a blinking error message to the user. Error messages can be passed to ENVFORM in the DOS ENVERROR environment variable. If upon program entry the variable ENVERROR exists, its contents will be displayed at the row and column specified by ENVLOCATION. If the column is set to zero, the text will be centered. PUTFORECOLOR=color PUTBACKCOLOR=color GETFORECOLOR=color GETBACKCOLOR=color Specify the color values for the foreground and background colors for the text display (PUT) and field variables (GET). The color values are as follows: 0 = Black 4 = Red 1 = Blue 5 = Magenta 2 = Green 6 = Yellow 3 = Cyan 7 = White [ENVVARS] section varx=row,column,length These values specify the variables to be accepted during data entry. Each variable entered here will correspond to a screen field as well as a DOS environment variable. The name preceding the equal sign will be the name of the environment variable. If the variable exists in the current environment, its contents will be used as a default during data entry. The screen position for this field is specified by the row and colmun values. The of the field length used during data entry is specified by the length value. The top left corner of the screen is row one, column one. This method was chosen due to the fact that most text editors display the row and column when editing files. [ENVTEXT] section varx=row,column,color These values specify DOS environment variables to be displayed within the data entry form. The top left corner of the screen is row one, column one. If column is set to zero, the text is centered. The color values are the same as in the [ENVFORM] section. Section 4 - Errors / Return Codes --------------------------------- When ENVFORM terminates, the following return codes (ERRORLEVEL) are set: 0 = Normal completion 1 = Screen error, possible row/column error 2 = INI file not found 3 = Screen file not found 4 = Run file not found 5 = Run file could not be invoked 6 = Batch file could not be created 7 = Reserved, not used 8 = User pressed ESCape Section 5 - Special Notes / Considerations ------------------------------------------ If you receive an 'Out of environment space' message, the amount of memory allocated for the DOS environment may need to be increased. Adding the following line to your CONFIG.SYS file may correct the problem: SHELL=C:\COMMAND.COM /E:512 /P Reference the 'COMMAND' command in your DOS manual for more information. Section 6 - Examples -------------------- Several examples should have been included in this download. Remarks within each sample should provide you with ample information to design your own ENVFORM applications. Example 1 EX1.BAT - Simple form to run DOS EDIT. Example 2 EX2.BAT - Simple form to run DOS EDIT, with error checking. Example 3 EX3.BAT - Form to accept and validate data. Sample application.