|
 |
 |
|
|
|
||
|
|
|
FmPro Migrator Features and Benefits FmPro Migrator Demo Available for download... File: example_instructions1.txt Used By: Perl CGI Script Developer This output file was created by FmPro Migrator version 1.46 on Mon Jul 14 12:16:11 2003. By .com Solutions Inc. www.dotcomsolutionsinc.net Overview The generated Perl code is designed to be easily updated due to its organized structure and documentation. Commonly changed parameters such as connection strings, table names and error messages are defined near the start of each script. The generated scripts utilize commonly available open source Perl modules including CGI.pm and DBI/DBD in order to make it practical for a developer to make more extensive changes. One minor change which can easily be made to the generated
scripts involves the display of visible borders for HTML tables. By
default, the generated scripts set the table border to "1"
which makes the table borders visible. To make the table borders invisible,
just change the following line of code to set the border to "0": Generated CGI Scripts example_submit1.html
- (Submit
Flowchart) example_submit1
- example_header1.html - example_footer1.html - example_query1.html
- (Query
Flowchart) example_query1
- example_display_record1
- example_update1.html
- (Update
Flowchart) example_update1
- example_update_record1
- example_update_record_validate1
- example_delete1.html
- (Delete
Flowchart) example_delete1
- example_delete_record_display1
- example_delete_one_record1
- example_instructions1.txt
- Usage Instructions 1) Fill in the database related fields within the FmPro
Migrator application and generate migration files for the destination
database. As the migration files are created, a file named layouts.txt
will also be created within the destination directory. This file contains
layout-specific information regarding the names and types of fields
included within each FileMaker layout. Web Server Setup Instructions The CGI.pm Perl module is included as a standard component with current Perl distributions so you should not generally need to install it. If a reinstall of the CGI.pm module is required, it may be downloaded from www.cpan.org. For database access by scripts running on the web server
it is necessary to first install database client software and DBI/DBD
driver software on the web server. Install Oracle database client software on the web server.
The Oracle client software must be installed before the DBI/DBD software
is installed. Configure the Oracle client software to enable connections
to the database thru the tnsnames.ora file. Test the database connection
with the tnsping utility to test the service name entered into the tnsnames.ora
file. As an additional test, use sqlplus to connect to the database
with the service name and database account/password which will be used
by the CGI scripts. Once the database software has been installed, copy the generated scripts to the Apache web server configured /cgi-bin directory. Copy the HTML files into the documents directory. If the URLs within the scripts are different from your webserver structure, you may either make the changes in FmPro Migrator and regenerate the scripts, or update the scripts manually. Make each script executable by the user who owns the web
server software: The Perl scripts will be executed by the web server software whenever they are accessed because they are associated with the Perl executable by virtue of the fact that each script contains the line: #!/usr/bin/perl Notes for MacOS X webservers: General
Folder Tab - Field Descriptions Open... - File Menu item - The Open menu loads migration specific information from the filename.txt file selected by the user. This menu item also loads the filename.cgi file (if it exists) which contains previously saved CGI-specific information. Save As... - File Menu item - The Save As menu saves migration specific information into the filename.txt file (where "filename" is the filename entered by the user). CGI specific information (if it has been entered) is also saved by this menu selection as a file named filename.cgi into the same directory. If no CGI specific information has been entered a filename.cgi file is not created. File Version field (FileMaker tab) - The File Version field is used to add a version number to each generated script and HTML file. Each major revision of the scripts for a website may utilize a different version number. This feature enables webmasters to perform testing of new scripts with differing version numbers while maintaining existing scripts on the website. Once the testing has been completed, the top level HTML filenames may be changed in order to switchover to the new design with minimal impact to web visitors. If problems are encountered with the new scripts, the site can quickly be switched back to the previous HTML and scripts by swapping the top-level HTML files which submit info to the cgi scripts. Refresh Layouts button - This button loads the contents
of the layouts.txt file from the Output Directory if migration scripts
have already been generated. The action of the Refresh Layouts button
replaces any existing information concerning Layouts and Fields which
may have previously been loaded into memory. The Refresh Layouts button
should be pressed anytime there are changes made on the FileMaker, Oracle
or Other tabs. After making changes on those tabs the following procedure
should be followed: Layouts field - Once the CGI specific data has been loaded by clicking the Refresh Layouts button or selecting Open... from the File menu, the fields named Layouts and Fields will be populated with information about the FileMaker database. Clicking on any individual layout name will present the user with the top level Layout screen for that particular layout. Fields field - The Fields field will be populated with the fields associated with an individual layout. Clicking on any individual field will present the user with the screen of info for that particular field. Clicking on either a field or layout name will instantly present the user with the relevant information for the layout or field which has been selected. Generate CGI button - If CGI specific information has been entered, Perl CGI scripts are generated for each layout of the FileMaker database. Even though migration scripts are generated for every open FileMaker database file, CGI scripts are only generated for one FileMaker database file at a time - as specified by the contents of the layouts.txt file. This is necessary because of the need to manually enter layout and field specific information for each database layout. Web Server menu - The two types of supported web servers are UNIX (which includes Linux and MacOS X) and Windows. CGI scripts generated for UNIX web servers are optimized for use with the Apache web server. This means that it is important for the Path to Perl field to be filled out correctly on the FileMaker tab for proper execution of the scripts by the web server software. Also, Perl CGI scripts generated for UNIX servers do not utilize the ".pl" filename extension. This feature deprives a potential web attacker of information regarding whether the scripts are created as Perl, PHP, shell scripts or some type of binary compiled application. If Windows is selected as the web server OS, the ".pl" extension is added to each CGI script so that scripts are executed by the Perl interpreter. A creative Windows webmaster could generate scripts for a UNIX server, manually append the ".cgi" extension to each file and then use Windows to associate the ".cgi" extension with the Perl interpreter. [If an Oracle database is used, this creative solution would also require manually compiling the DBD::Oracle driver for use with Oracle 8 if CLOB/BLOB objects were utilized within the database table.] Display Results menu - Query results lists are limited to the number of results displayed per web page which have been selected in this menu. If additional results are available, the user is able to click on a Next link to display additional information. Max Submit Size field (Bytes) - For security purposes is it necessary to limit the amount of info which is accepted by the script from submit forms. This limitation is implemented in order to prevent a web attacker from accomplishing a denial of service or buffer overflow attack on the web server. Exceeding the specified limit defined in this field causes CGI.pm to zero out the data for all submitted fields. When this occurs, all data validation subroutines which require a minimum number of characters to be entered will fail - even if info has been properly entered into the field. The web developer needs to plan for the maximum amount of data which will be processed by the script in order to prevent unexpected behavior for web users. The default value of 10000 bytes is generally a high enough number for most text forms, but often won't be high enough for insertion of images into the database. Each Perl CGI script generated by FmPro Migrator which processes LONG/BLOB data is also designed to limit the amount of LONG/BLOB data to the value specified for the Max Submit Size on the General tab of FmPro Migrator. The Max Submit Size should be configured to handle the maximum amount of data which will be processed by the script in one submission. A script which needs to handle 10,000 bytes of text plus the uploading of five 100,000 byte images in the same submission should be configured with the Max Submit Size set for 510,000 bytes. Website URL field - The website URL entered into this field is used for creating script submission URLs. The string "http://" may be prefixed to the URL, or it will be added by FmPro Migrator if it is omitted. For testing purposes, an IP address to a test web server may be entered into this field. Once testing has been completed, the correct website URL may be entered here in order to generate scripts for the production web server. Layouts
Folder Tab - Field Descriptions Layout Name field - The names of FileMaker layouts are renamed as necessary by FmPro Migrator in order to remove special characters and convert spaces to underscore characters. This read-only field displays the name of the layout which is currently being viewed. To change the name of a layout, change the name of the layout within FileMaker, then recreate the migration scripts and reload the layouts.txt info by clicking the Refresh Layouts button. HTML Header field - The information contained within this field is used to create an external HTML file which is loaded and displayed dynamically by the CGI scripts. This external HTML file is expected to be located by default from within the cgi-bin directory - however the Perl scripts may be updated manually to change this location. This external HTML file may be edited independently by the webmaster without any knowledge of Perl CGI programming. If no information is entered into this field, default HTML header information located within each Perl script is used for creating each dynamic web page. HTML Header Replace All button - Clicking this button replaces the HTML Header information on all of the other layouts with the contents of the HTML Header field on the layout currently being viewed. HTML Footer field - This information is used to create the external footer HTML file. This is the HTML footer information which is displayed after the dynamically generated information on dynamic web pages. HTML Footer Replace All button - Clicking this button replaces the HTML Footer information on all of the other layouts with the contents of the HTML Footer field on the layout currently being viewed. Security menu - The two options on this menu are None
and Secure. If the Secure option is selected, the URLs created for posting
info to web pages will be created with an "https" prefix instead
of an "http" prefix. Submit Success URL field - If the Submit Success URL is filled in, the user will be redirected to the URL specified in this field upon successful completion of insert, update and delete scripts. Submit Success Text field - If the Submit Success URL field is not filled in, the text listed in the Submit Success Text field will be displayed upon successful completion of insert, update and delete scripts. Fields
Folder Tab - Field Descriptions Display As field - The default value for the Display As field content is the modified name of the FileMaker database field. The modified name of each FileMaker field represents a name which does not contain spaces or special characters which would prevent it from being used as the name of a database column. The modified name may not be suitable for display on a web page therefore this field provides a way to change the displayed name of each field. Auto-Enter menu - The Auto-Enter menu enables auto-enter
values similar to the method implemented by FileMaker. Fields may contain
Auto-Enter Creation Time, Creation Date, Data, Modification Date, Modification
Time, Perl Calculation or Serial Number. The Auto-Enter Creation Date/Time
parameters are only used when new records are created. The Auto-Enter
Modification Date/Time parameters are only used when a record is updated,
not when it is created. The Auto-Enter Data parameter is a static value
consisting of text or numbers which is entered upon record creation
or modification. The static Data value needs to be entered into the
"Result =" field. The Perl Calculation parameter is used during
record creation and updating. The Perl code for the calculation needs
to be entered into the "Result =" field and does not need
to be terminated with a ";". Result = field - This field is used for additional parameter specifications based upon the value selected for the Auto-Enter menu. If using the Auto-Enter Data or Auto-Enter Perl Calculation, the appropriate values or Perl code need to be entered into this field. The Perl calculation may make use of any existing Perl variables which have already been declared in the output script at the time the Auto-Enter directives are processed. Any syntax errors in the entered Perl code will cause the CGI script to stop running (script processing errors can be found in the web server error.log file). Display Value List menu - The two options for this menu are None and From Value List. If the From Value List menu item is selected, the values for the value list should be entered into the Value List Items field. Value List items are used to build Submit, Query and Delete HTML pages. Value List Items field - If the "From Value List" option is selected in the Display Value List menu, the value list items should be entered in this field. Validate Data Entry menu - The options for this menu include None, Not Empty, Characters Only, Numbers Only, Numbers and Characters Only and Email Address. These validation options are checked during Submit and Update form processing. Validate Numeric Range Low field - If validation of a numeric range is required, the lower range should be entered into this field. Validate Numeric Range High field - If validation of a numeric range is required, the higher range should be entered into this field. Number of Characters Min field - If a minimum number of characters must be entered into the field, the minimum number should be entered into this field. Number of Characters Max field - If a maximum number of characters should not be exceeded for the field, this maximum number should be entered into this field. Custom Validation Text field - A standard generic error message is generated for each validation test. However a custom error text message may be specified within this field in order to override the standard message. This message will be displayed for each validation error which occurs for the field. The text entered within this field should be terminated by an HTML <BR> command. All other HTML commands may be included as well. Troubleshooting Most web development troubleshooting may be performed by using information written to the web server error.log file. Additional information may be written to this file by using the Perl warn "" feature to write variable contents to the error.log file. Perl DBI/DBD module related information may also be written to a log file. Each CGI script generated by FmPro Migrator contains a debug variable near the start of the program. Changing this variable from 0 to 1 will enable DBI/DBD debugging the next time the script is executed. On UNIX servers you may find that your web server software user does not have enough privileges to write the dbitrace.log file specified in the CGI script. Directory permissions may be changed to allow this file to be written if desired, however this information gets written to the Apache error.log file anyhow. On Apache web servers running on Windows, this log file will generally be created and can be viewed within the directory containing the CGI script. Example Errors: Form validation fails while uploading images (or no data
is written to the database) - If the combined data submitted to the
database exceeds the value defined for $CGI::POST_MAX, then CGI.pm will
often clear the data for all of the fields prior to passing the info
to the script for processing. This feature is designed to prevent a
web attacker from sending enough data to your script to cause a buffer
overflow in an attempt to gain root access over the web server. syntax error at C:/test/Apache2/cgi-bin/form_-_depreciation_query1.pl
line 283, near "abcdef - This error shows how a syntax error may
show up in the error log. DBD::Oracle::st execute failed: ORA-01847: day of month
must be between 1 and last day of month - This error may occur if an
attempt is made to insert or update incorrectly formatted date information
in an Oracle date column. DBD::Oracle::st execute failed: ORA-00932: inconsistent
datatypes (DBD: oexfet error, e.g., can't select LOB fields using DBD::Oracle
built for Oracle 7) - This error has been observed with DBD-Oracle 1.12
installed by ActiveState PPM on Windows. [Oracle][ODBC][Ora]ORA-01008: not all variables bound
- This error should not normally be observed unless the output code
has been manually modified. DBD::ODBC::st fetchrow_arrayref failed: [Oracle][ODBC]String
data, right truncated. (SQL-01004)(DBD: st_fetch/SQLFetch (long truncated
DBI attribute LongTruncOk not set and/or LongReadLen too small) - This
error is the result of attempting to insert too much data into an Oracle
CLOB or BLOB column. ORA-12154 Error while trying to retrieve text for error
ORA-12514 (DBD ERROR: OCIServerAttach) ORA-01465 DBD::Oracle::st execute failed: ORA-01465: invalid
hex number (DBD ERROR: OCIStmtExecute) ORA-00911 DBD::Oracle::st execute failed: ORA-00911: invalid
character (DBD ERROR: OCIStmtExecute) when using the DBD::Oracle driver
with the Apache web server on Linux/UNIX operating system.
|
|
|
|
|
|
|
||
|
|
|
|
||
