GENSCRNX 1.7a INTRODUCTION GENSCRNX.PRG extends the control of code generated from FoxPro's screen builder. After Generate... is selected when using the Screen Builder, GENSCRNX first copies the .SCX database and then updates it based on comments in the snippets and setup code. Also, GENSCRNX places the .SPR into a memo field after its created to make possible code changes and/or replacements after GENSCRN. The ability to define each object into a global database called FOXSCX.DBF is performed when a define object directive is placed in an object's comment code. The FOXSCX.DBF contains the same structure as FoxPro's .SCX files except has added fields for object name, field, library, and other objects that it bases from. New screens can be created without snippet code by simply placing a base object directive in the comment snippet with the appropriate name. GENSCRNX updates the .SCX before passing it to GENSCRN. Drivers can be defined in the CONFIG.FP and screen Setup snippet code. Every driver is called once for each record in the .SCX before GENSCRN generates code. The driver may update the .SCX database with no limitations. Objects can be manipulated or replaced by pure FoxPro code using a driver procedure. GENSCRNX handles the code replacements to the .SPR. A driver may use pre-made functions contained in GENSCRNX which handle the .SCX record update for code replacement, template insertion, and other .SCX update functions. A DEFINE WINDOW command can be inserted in the .SPR between the GET/SAY fields in the Screen Layout section.. Multiple drivers may also be selected for functions such as 3D effects or auto insertion of menu push buttons (Next, Previous, Append, Delete, etc.). GENSCRNX is entirely written in FoxPro and fully compatible with FoxPro 2.0 and FoxPro 2.5 (all platforms). The FOXSCX library database can be updated when referenced by FoxPro 2.0 and/or FoxPro 2.5 for MS-DOS without any conversion. FoxPro 2.5 for MS-DOS MS-DOS applications can be built by referencing objects created with FoxPro 2.0 and vice versa. The FOXSCX.DBF database can contain records for FoxPro 2.5 (all platform) while GENSCRNX automatically handles the record relation between platforms. Notes: CONFIG.FP relates to FoxPro 2.0 and FoxPro 2.5 DOS. CONFIG.FPW relates to FoxPro 2.5 Windows. Notes: For futher information about GENSCRNX and related files, refer to VERSION.TXT supplied with GENSCRNX.ZIP. FEATURES - Extended control over FoxPro's Screen Builder without changing GENSCRN. - Option for compiling the output file when generating from the Screen Builder. - Option for displaying the .SPR and .ERR files if an .ERR file is generated after compiling the output file when generating from the Screen Builder. - Ability to store screen objects into a database library. - Ability to retrieve screen objects from a database library with support of multiple inheritance (expressions are separated by .AND. while procedures are appended). - Option to set Read level settings (OpenFiles, CloseFiles, Modal, OutFile, etc.) from with the screens setup that override the Generate dialog checkboxes. This allows settings to be saved with the screen without using a project. - Ability to insert records contained in a separate .SCX file at compile time. All records row and column information is automatically adjusted. This allows subforms to be inserted without copy and paste. If the inserted screen is updated, the screen importing it can be re-generated without change. - Ability to insert FoxPro code in place of any screen object. This allows a line or multiple lines of FoxPro code to be generated between GET commands in the Screen Layout section. - Ability to block a GET command with any IF/ENDIF statement. - Ability to specify any SIZE clause and override the SIZE setting defaulted by the Screen Builder. - Ability to remove the SIZE clause from any GET command. - Ability to create .PRG drivers that update the .SCX database at compile time before GENSCRN is called. This allows external programs to be created that automatically add, update, or remove code of any screen snippet. Drivers can make function calls to many of GENSCRNX's built in function library for parsing or insertion of .SCX information. - Support for any expression to be evaluated at compile time using {{}} in any snippet or field. GENSCRNX will evaluate at compile time and replace {{}} with its result. If was an external function and the command was placed in the Setup snippet, the external function could act like a #INCLUDE function by returning multiple lines of code. Example: If the following command was in the Setup snippet and assuming the current date was 06/01/93: WAIT '{{DATE()}}' WINDOW NOWAIT the following code would be placed in the .SPR: WAIT '06/01/93' WINDOW NOWAIT INSTALLATION After unzipping GENSCRNX.ZIP, copy GENSCRNX.PRG to all existing FoxPro 2.x directories Change all CONFIG.FP and CONFIG.FPW files to: _GENSCRN="GENSCRNX.PRG" MVCOUNT=512 Notes: If MVCOUNT is already set to a number greater than 512, then do not change it. If MVCOUNT is set to a number less than 512, then change the number to 512. If a line containing MVCOUNT does not exist, then create one as above. Notes: For futher information about GENSCRNX and related files, refer to VERSION.TXT supplied with GENSCRNX.ZIP. CONFIG.FP/CONFIG.FPW OPTION SETTINGS _GENSCRNX Specifies program to generate .SPR file from .SCX database. Default: _GENSCRNX="GENSCRN.PRG" in FoxPro start directory Example: _GENSCRNX="C:\MYDIR\MYGENSCN.PRG" Notes: When _GENSCRN="\GENSCRNX.PRG", then _GENSCRNX is used to specify which program is used to generate screen code. If _GENSCRNX is not specified in the CONFIG.FP/CONFIG.FPW, the default setting is GENSCRN.PRG located in FoxPro's start-up directory. _FOXSCX Specifies database used for object library records. Default: _FOXSCX="FOXSCX.DBF" in FoxPro start directory Example: _FOXSCX="C:\MYDIR\FOXSCX.DBF" Notes: It is recommended that all FoxPro 2.x CONFIG.FP/CONFIG.FPW contain the same _FOXSCX setting. _SCXDRV1 Specifies global driver program. Default: _SCXDRV1="" _SCXDRV1 to _SCXDRV8 Specifies global driver program. The numbers 1-8 represent various driver hooks throughout GENSCRNX while the .SCX databases is being generated. Example: _SCXDRV2="C:\3DFOX\3D" _SPRDRV1 Specifies global driver program. Default: _SPRDRV1="" _SPRDRV1 to _SPRDRV6 Specifies global driver program. The numbers 1-6 represent various driver hooks throughout GENSCRNX while the .SPR file is being updated. Example: _SPRDRV1="C:\MYDIR\SPRUPD1" GENSCRNX Specifies GENSCRNX functions enabled (ON) or disabled (OFF). Default: GENSCRNX=ON COMPSPR Specifies auto-compilation of .SPR file. A public variable called _COMPSPR to override the COMPSPR setting. Default: COMPSPR=OFF Important: This setting is ignored during screen building from projects. DISPSPR Specifies auto-display of .SPR and .ERR files if an .ERR file is exists. A public variable called _DISPSPR to override the DISPSPR setting. Default: DISPSPR=OFF Important: DISPSPR=ON may cause a file sharing error when SHARE.EXE is installed. SETUP SNIPPET DIRECTIVE REFERENCE #:SECTION 3 Used in Setup snippet (like #SECTION 1 | 2) to insert code after GETs and before READ in the Screen Layout. *:AUTORUN Automatically releases screen after generation and executes generated file. *:AUTORUN is automatically disabled if either a compiled file is not properly generated or a compile error was detected via the COMPSPR=ON. *:COMPSPR Overrides COMPSPR=OFF in CONFIG.FP/CONFIG.FPW. New: *:DISPSPR Overrides DISPSPR=OFF in CONFIG.FP/CONFIG.FPW. *:SET OPENFILES ON | OFF Open files. Example: *:SET OPENFILES ON *:SET CLOSEFILES ON | OFF Close files. *:SET DEFWINDS ON | OFF Define windows. *:SET RELWINDS ON | OFF Release windows. *:SET READCYCLE ON | OFF Read cycle *:SET MULTREADS ON | OFF Multiple READs. *:SET NOLOCK ON | OFF READ nolock. *:SET MODAL ON | OFF Modal. *:SET PLATONLY ON | OFF Current platform objects only. If this setting is ON, GENSCRN will not generate code for other platform code but GENSCRNX will still process all platform records. Setting PLATONLY='ON' in the CONFIG.FP/CONFIG.FPW files will cause GENSCRNX to not pre or post process other platform records. See ADDITIONAL INFORMATION section below for controlling this setting using a public variable. *:SET BORDERGETS ON | OFF Border for GETs. *:SET ASSOCWINDS TO Assoc. windows list. The is appended to Assoc. windows list from screen or project. Example: *:SET ASSOCWINDS TO Calculator,Calendar *:OUTFILE Output file name. *:OUTFILE is disabled when building screen from a project. Example: *:OUTFILE TEST.PRG *:PRG A Setup snippet directive called *:PRG that is used to automatically change the .SPR extension to a .PRG extension and also add the #NOREAD PLAIN directive to the Setup snippet. The *:PRG directive used in conjunction with screen objects with the *:INSTXT directive will allow a .PRG file to be created that has no GETs, SAYs, or READ, while the screen builder Object Order controls the order of the FoxPro source code generated in the .PRG file. When building a screen from a project, the *:PRG directive does not change the file name to a .PRG extension due the fact that the project expects the file name specified in the project for a proper build. *:PJXSET Place in the Setup snippet before the *:PRG directive or any *:SET directive to force the project information to have priority settings when building the screen from a project. Example: If the following was in the Setup snippet of a screen: *:SET MODAL ON *:PJXSET *:SET READCYCLE OFF Then if the screen was generated from the Screen Builder, the READ would contain the clauses MODAL and CYCLE no matter what the check box settings were set to before selecting . If the screen was generated from a project, the READ would contain MODAL no matter what the settings were set to in the project but the CYCLE setting would be set to whatever the project setting was set to. *:DEFLIB Defines library name. *:DEFLIB can be used with stand alone screens only and cannot be used with screens in a screen set. *:INCLIB Includes library in base object search path. *:BASLIB Base library objects for field name match. *:SAVESIZE Used with *:DEFOBJ in a library object to force the SIZE information to be retrieved fromt he library when the object is based in a screen. *:SAVEPICT Used with *:DEFOBJs to force the PICTURE information to be retrieved from the library when the object is based in a screen. *:BASBEFORE Used with *:DEFOBJ in a library object to force any inherited expressions or procedures to be inserted before rather than appended after to any screen surface code. *:SCXDRV1 Specifies screen driver program. *:SCXDRV1 to *:SCXDRV8 Specifies screen driver program. The numbers 1-8 represent various driver hooks throughout GENSCRNX while the .SCX databases is being generated. *:SPRDRV1 Specifies screen driver program. *:SPRDRV1 to *:SPRDRV6 Specifies screen driver program. The numbers 1-6 represent various driver hooks throughout GENSCRNX while the .SPR file is being updated. *:MEMVAR Replaces all aliases in GET name from alias.variable to m.variable. All alias.variable names referenced in the WHEN, VALID, ERROR, MESSAGE, RANGE LO, and RANGE HIGH snippets will be replaced with m.variable. *:NAME The following example demonstrates how *:NAME affects FoxPro 2.5's #NAME directive. #NAME v_show is changed to #NAME v_showd && _DOS=.T. #NAME v_showw && _WINDOWS=.T #NAME v_showm && _MAC=.T. #NAME v_showu &&_UNIX=.T. The above changes will occur before GENSCRN is called. Then, a function is appended to the Cleanup snippet as follows: FUNCTION V_SHOW DO CASE CASE _DOS RETURN V_SHOWD() CASE _WINDOWS RETURN V_SHOWW() CASE _MAC RETURN V_SHOWM() CASE _UNIX RETURN V_SHOWU() ENDCASE RETURN .F. FUNCTION V_SHOWM RETURN .F. FUNCTION V_SHOWU RETURN .F. This will result in the exact same code execution as if a CASE _DOS, CASE _WINDOWS, etc. was generated in the snippet. The only rule is that *:NAME uses only the first 9 characters of the snippet name specified. The 10th character is used for the platform character. Also, any PARAMETER statement that follows the #NAME in the snippet will be properly handled in the cross-platform function that is generated. The only rule here is that the PARAMETER statements must be identical for all platforms having the same #NAME definition. *:NOGEN Prevents GENSCRN from being called so that no .SPR file is generated. *:NOGEN should be used with templates since templates do not need code to be generated. *:NOXGEN Prevents GENSCRNX from updating .SCX database and .SPR file. *:GENSCRNX Used to specify which program is used to generate screen code. *:GENSCRNX overrides any _GENSCRNX in the CONFIG.FP and CONFIG.FPW files. If both *:GENSCRNX and _GENSCRNX are notspecified, the default setting is GENSCRN.PRG located in FoxPro's start-up directory. *:GENSCRNX can be used to specify a modified GENSCRN needed for a particular screen rather than changing _GENSCRN before generating a screen. *:NOCOMPSPR Overrides COMPSPR=ON in CONFIG.FP/CONFIG.FPW. *:NODISPSPR Overrides DISPSPR=ON in CONFIG.FP/CONFIG.FPW. *:NOWCLAUSES Removes a list of clauses from the DEFINE WINDOW command of a screen. Any list of clauses can be removed (except COLOR) by listing the name of each clause separated by a space delimiter. Example: Add following line in the Setup snippet to remove all FROM, TO, AT, SIZE, FONT, and STYLE clauses will be removed from the DEFINE WINDOW command: *:NOWCLAUSES FROM TO AT SIZE FONT STYLE To directly add any of the removed clauses, use GENSCRN's #WCLAUSES directive. Example: Add following lines in the Setup snippet to add a custom AT SIZE : *:NOWCLAUSES AT SIZE #WCLAUSES AT 1,1 SIZE 10,30 or *:NOWCLAUSES AT SIZE #WCLAUSES AT {{VPOS}},{{HPOS}} SIZE {{HEIGHT}},{{WIDTH}} Note: The {{}} evaluates any expression and replace its result as source code. In the above example, the field names are referencing the .SCX header record which contains the screen layout window data. Example: Add following lines in the Setup snippet to add a custom FONT STYLE : *:NOWCLAUSES FONT STYLE #WCLAUSES FONT m.myfontface STYLE m.myfontstyl *:DRVOFF Specified in the Setup snippet to disable any driver setting that is specified in the CONFIG.FP/CONFIG.FPW. The number of *:DRVOFF directives specified in the Setup snippet is unlimited and the files included are retained for all screens in a screen set. If *:DRVOFF is specifed in the Setup snippet in a screen set, then all screens following in that screen set will inherit the *:DRVOFF for the specified driver. Example: If the 3D.PRG is specified in the CONFIG.FPW as _SCXDRV5="3D.PRG", for the 3D driver to be executed globally for every screen, then specifying *:DRVOFF 3D in the Setup snippet would disable the 3D driver for that screen. GENSCRNX creates comments in the Setup snippet as that include the the following information at compile time. Example: * This program was preprocessed by GENSCRNX. *--GENSCRNX 1.7 *--Screen C:\SAMPLE\CUST2.SCX *--Project C:\SAMPLE\SAMPLE.PJX *--FOXSCX C:\FOXPRO25\FOXSCX.DBF *--Platform DOS *--Time 08/25/93 20:29:46 COMMENT SNIPPET DIRECTIVE REFERENCE *:DEFOBJ Defines object name. *:BASOBJ [ Specify base object. *:INSOBJ [ Insert object from FOXSCX.DBF in place of screen object. *:INSSCX Insert screen from template in place of screen object. Using *:INSSCX with FoxPro 2.0 and FoxPro 2.5 for DOS screens work are fully compatible for both directions. *:INSTXT Insert all preceding text in place of screen object. *:ENDTXT Place at end of code that follows *:INSTXT to mark ending of text. *:ENDTXT is not required and is only used as a separator if non- *:INSTXT text follows the code to be inserted. *:TRNTXT || [|| ] [|| ]] Transform text of *all* memo fields. The search is *not* case-sensitive. The character expression that's searched for. The search character expression is replaced by the character expression . If is omitted, is replaced with the null string. The optional numeric expression specifies which occurrence of is the first to be replaced. For example, if is 4, replacement begins with the fourth occurrence, counting from the left, and the first three occurrences remain unchanged. The occurrence where replacement begins defaults to 1 if is omitted. specifies the number of occurrences of to replace. If is omitted, all occurrences of , starting with the occurrence specified in , are replaced. Note: *:TRNTXT is mainly used with the *:BASOBJ command for data translation of code being referenced from a library object. *:IF Blocks object with IF ... ENDIF statements. *:SIZE Replaces object SIZE clause with . can be any character expression, including variable names or FoxPro functions. *:NOSIZE Removes SIZE clause from object. *:NOSIZE is ignored for EDIT objects. *:DEFAULT Replaces object DEFAULT clause with . can be any character expression, including variable names or FoxPro functions. Push buttons, Radio buttons, and Check boxes use the value of . Lists, invisible buttons, and spinners cannot use the *:DEFAULT directive. All other objects use with a direct replacement. If a character default is desired, be sure to include the quotes in the expression. If the current object's color is set to default, then a COLOR SCHEME or COLOR may be included in . *:DELETE Delete screen object at compile time. Use *:DELETE for objects that need to appear while using the Screen Builder but not in the .SPR file at run-time. *:DELOBJ Delete screen object at compile time after pre-processing is complete. Use *:DELOBJ for objects that need to reside in the .SCX database during pre-processing but not in the .SPR file at run-time. PROCEDURE SNIPPET DIRECTIVE REFERENCE #:INSERT Screen generator directive inserts the contents of into generated screen code. Not only does GENSCRNX support the #INSERT directive for FoxPro 2.0, but the #:INSERT directive performs the same operation as FoxPro 2.5's #INSERT except it is much faster when inserting large files. FILE GENSCRN GENSCRNX SIZE #INSERT #:INSERT ----------------------------------------------------------- 2K 3.215 2.938 135K 178.717 3.475 330K 970.478 6.630 ---------------------------------------------------------- Time is in seconds using 486-50DX When using GENSCRNX, use #:INSERT instead of #INSERT for better performance. #:INSERTTOP Inserts file at top of .SPR code before DO CASE of cross-platform block. If #:INSERTTOP appears more than once due to cross-platform snippets containing the same code, the will only be inserted into the .SPR once. This allows header files containing #DEFINE directives to be inserted once per .SPR file instead of one per platform inside the DO CASE block. PROCEDURE SNIPPET COMMAND REFERENCE {{}} Text surrounded by double braces performs the EVALUATION of at compile time and returns the value in string form. {{}} is replaced with the string of EVALUATE(). can be any type (character, numeric, date, logical, etc.) and {{}} will always return the result in character form. Example: If the following command was in the Setup snippet and assuming the current date was 06/01/93: WAIT '{{DATE()}}' WINDOW NOWAIT the following code would be placed in the .SPR: WAIT '06/01/93' WINDOW NOWAIT If the following command was in the Valid snippet: DEFINE POPUP pop_test FROM {{VPOS+HEIGHT}},{{HPOS-1}}; TO {{VPOS+HEIGHT+7}},{{HPOS+WIDTH}}; PROMPT FIELD items.item and VPOS=5, HPOS=10, WIDTH=8, HEIGHT=1 in the .SCX database, then the following code would result in the Valid snippet of that object in the .SPR: DEFINE POPUP pop_test FROM 6,9; TO 13,18; PROMPT FIELD items.item {{&.}} Text surrounded by double braces with a &. immediately after the open braces performs the macro substitution of at compile time and returns a null value in string form. {{}} is replaced with a null string. can be any FoxPro command that can be executed within a macro substitution string. Example: If the following command was in the Setup snippet and assuming the current date was 06/01/93: {{& WAIT '{{DATE()}}' WINDOW NOWAIT}} the following WAIT window would appear at compile time of the screen: 06/01/93 If the following command was in the Setup snippet: {{&.DO MYPROG}} then a program called MYPROG would be executed as a subroutine at compile time of the screen. If the program was to return a character string for code insertion, then {{MYPROG()}} would have been used. DRIVER INFORMATION Driver programs are specified either in the CONFIG.FP/CONFIG.FPW files by defining: _SCXDRV2="\[]". Driver programs can also be specified a screen Setup snippet by defining: *:SCXDRV2 \[]. *:SCXDRV1 is used before any GENSCRNX compilation. It can be used as a #INCLUDE to add any GENSCRN or GENSCRNX directives. Another method of obtaining a #INCLUDE type function is the use the braces ({{}}) when contains an external function. The character string returned from the function will replace the {{}} directly. For example, if the Setup snippet contained the following line: {{inc_test()}} and the external function inc_test() return a character string of #NOREAD, then the {{inc_test()}} line would be directly replaced by the #NOREAD command. Also, the returned character string may contain a carriage return and line feeds (CHR(13)+CHR(10)) to separate lines when multiple lines are needed for insertion. Refer to the {{}} definition supplied with GENSCRNX for further information. Notes: If the parameter of a driver directive does not include a file extension, the following extensions are checked in this order: .EXE, .APP, .PRG, .FXP The n in SCXDRVn represents the hook number from GENSCRNX. GENSCRNX has 8 different places during the compiling loop that can call out to drivers. The most common one to use is #2. You can have infinite drivers for #2: Example: *:SCXDRV2 *:SCXDRV2 The order they are listed is the order they are called. Hook #1 is before compilation (like #INCLUDE), hook #2 is the first in each compile loop, and #8 is after compiling is complete. Important: Only one driver can be specified in the CONFIG.FP/CONFIG.FPW files. If more than one driver is specified in the Setup snippet, the drivers are called in the order they are listed. Drivers specified in the CONFIG.FP/CONFIG.FPW are called before the drivers specified in the Setup snippet. ADDITIONAL INFORMATION All *: directives used for GENSCRNX must be specified starting in column one of the snippet. Do not indent the *: directives with spaces or tabs. When using the Standard version of FoxPro for MS-DOS, the .SPR file size must be less than 64K. If a public variable called _GENSCRNX is set to OFF, GENSCRNX with pass the .SCX directly to GENSCRN and all GENSCRNX directives and commands will be ignored. GENSCRNX can also be specified in the CONFIG.FP/CONFIG.FPW files and changed without re-entering FoxPro. If a public variable called _PLATONLY is set to ON, GENSCRNX and GENSCRN will only generate code for the current running platform. PLATONLY can also be specified in the CONFIG.FP/CONFIG.FPW files and changed without re-entering FoxPro. _PLATONLY='ON' is useful during development when cross-platform code generation is not required for screens until development is complete. COPYRIGHT NOTICE Compressed file: GENSCRNX.ZIP System: GenScrnX Author: Ken R. Levy Company: Jet Propulsion Laboratory Copyright: None (Public Domain) All source code and documentation contained in GENSCRNX.ZIP was developed at the Jet Propulsion Laboratory in Pasadena, Calif. and has been placed into the public domain. You may use, modify, copy, distribute, and demonstrate any source code, example programs, or documentation contained in GENSCRNX.ZIP freely without copyright protection. All files contained in GENSCRNX.ZIP are provided 'as is' without warranty of any kind. In no event shall its authors, contributors, or distributors be liable for any damages. COMMENTS/SUGGESTIONS/PROBLEMS/QUESTIONS Please use CompuServe's FoxForum (section 3rd Party Products) directed to: Ken Levy 76350,2610 -----------------------------------------------------------