#import - Multi Line Records

This type of #Import has clearly defined fields which you label. You would frequently wish to display these in a table (say in a HTML page) however nothing says that you need to do so.

Field Information Parameters

On these types of imports "FieldInfo" follows the "DefineName" parameter on the #import command line.

For each field you have defined in your database you must specify field information. The field information is of the format:

{*,FieldName[,FieldOptions]}TitleText

In place of the '*' you could specify the column number you wish to place the field but its usually easier to simply reorder the fields.

The "field name" specifies the name you use in your database. It can contain virtually any characters but must of course not contain the delimiter character ('=' by default). Like all PPWIZARD names the name can contain international characters.

You can optionally specify some field options which vary the way individual fields are processed. Each field option is separated by a comma, valid options are:

• REQUIRED
  This field is required. You can supply a blank value. This validation occurs whether or not the field is dropped.

• NONBLANK
  This field if supplied must be non blank. If not supplied its value will become blank unless "REQUIRED" option was also specified. This validation occurs whether or not the field is dropped.

• NOASIS
  By default all files go through AsIs() replacements, this option allows you to prevent this occuring on particular fields if required.

The "title text" specifies the value for the field in the header record. Since all fields must be defined we use a blank "title" to indicate that we don't require a field and it should be dropped.

DEFINITIONS/OPTIONS

If you can't understand how these options work then I suggest you try using /debug or #debug to watch what variables the import uses etc.

• DefineName_#DATA
  Normally PPWIZARD generates the information as per your specification (you preconfigure this or allow it to default). You can also set this macro to have the data read into memory as per the #data command, it is then up to you to generate each database row (possibly after field manipulation).

  To save the data to memory you need to supply the name of the #data structure, you refer to this when generating the output with the <?Data> symbol. If used a lot of the other definitions are not used, if unsure have a look at the debug output.

• DefineName_BLANK_FIELD
  Normally a blank field will be displayed as blank. You may wish to display '-' instead. Another possiblity is to display a 1 by 1 transparent gif so as to have table borders around blank fields look better.

  For even more control (probably rare requirement):

  • DefineName_BLANK_COLUMN_?
    This allows you to specify different blank replacement values for each column.

• DefineName_STRIP_SPACES
  How do you want leading and trailing spaces on column data handled? Supply "L" to strip leading, "T" to drop trailing, "B" for both or nothing to not touch the value. The default for fixed field imports is "T", all others are to do nothing.

  You can set this on a field by field level if required:

  • DefineName_STRIP_SPACES_?
    Set the required value for a specific column.

• DefineName_TAB_CHAR
  Normally tabs are ignored by the import process. This variable allows you to replace them with something else.

• DefineName_ASIS_TAGGING
  The default value for this option is "IMPORT_HTML_BASIC" which takes care of converting the "&", "<" and ">" characters into their html codes so they they will display correctly in a browser.

  If your database contains preformatted HTML code (or references PPWIZARD macros) then this default handling would prevent this from working so you would probably want to turn this off, on the other hand you may wish to extend this to other characters (possibly international characters such as umlauts).

  This definition lists zero, one or more names as used on previous "#AsIs SETUP" commands (separated by whitespace). Each is added in turn.

  To prevent all character conversions you should assign an empty value to this parameter.

• DefineName_BEFORE
  You would probably only use this define if you didn't want to generate a table at all. You may specify the string "{$Columns}" which will get replaced with the number of fields to be displayed. If this define is not used then you can use the following:

  • DefineName_TABLE_ATTRIBS
    This value allows you to specify all HTML attributes of the table apart from the number of columns.

  • DefineName_TABLE_CAPTION_TEXT
    The Text of a table caption.

  • DefineName_TABLE_CAPTION_ATTRIBS
    Any attributes for the HTML "caption" tag. This is ignored unless text is also supplied.

• DefineName_HEADER
  This is used to control the "code" which handles the "heading" record, this does not have to be a html table. You can specify the string {$Column?} to represent a fields value (? = number of field where 1 is the first).

  If this define is not used then you can use the following:

  • DefineName_HEADING_COLUMNS
    This value allows you to specify the column (HTML "<TH>" tags) information to change alignment or colours of columns. This value becomes the default for all columns.

  • DefineName_HEADING_COLUMN_?
    This value allows you to specify the column (HTML "<TH>" tags) information to change alignment or colours of specific columns. Another use for this would be to specify the width of a column. This value is only used for column number '?'.

  • DefineName_HEADING_BEFORE_DATA
    This value allows you to specify some text to be placed in front of the fields data, for example if you wish to change the font size for each column you might used the value "<FONT SIZE=-1>". This value becomes the default for all columns.

  • DefineName_HEADING_BEFORE_DATA_?
    This value allows you to specify leading data on a column by column basis.

  • DefineName_HEADING_AFTER_DATA
    This value allows you to specify some text to be placed after the fields data, for example if you wish to change the font size for each column you might used the value "</FONT>" to close the previous font tag. This value becomes the default for all columns.

  • DefineName_HEADING_AFTER_DATA_?
    This value allows you to specify trailing data on a column by column basis.

• DefineName_RECORD
  This is used to control the "code" for each record, this does not have to be a html table. You would definately define this option if you didn't want a html table, you might wish to create a series of #defines (default configuration won't allow this) or maybe you are not generating html at all and need to generate an IPF table. You can specify the string {$Column?} to represent a fields value (? = number of field where 1 is the first).

  If this define is not used then you can use the following:

  • DefineName_RECORD_COLUMNS
    This value allows you to specify the column (HTML "<TD>" tags) information to change alignment or colours of columns. This value becomes the default for all columns.

  • DefineName_RECORD_COLUMN_?
    This value allows you to specify the column (HTML "<TD>" tags) information to change alignment or colours of specific columns. Another use for this would be to specify the width of a column. This value is only used for column number '?'.

  • DefineName_RECORD_BEFORE_DATA
    This value allows you to specify some text to be placed in front of the fields data, for example if you wish to change the font size for each column you might used the value "<FONT SIZE=-1>". This value becomes the default for all columns.

  • DefineName_RECORD_BEFORE_DATA_?
    This value allows you to specify leading data on a column by column basis.

  • DefineName_RECORD_AFTER_DATA
    This value allows you to specify some text to be placed after the fields data, for example if you wish to change the font size for each column you might used the value "</FONT>" to close the previous font tag. This value becomes the default for all columns.

  • DefineName_RECORD_AFTER_DATA_?
    This value allows you to specify trailing data on a column by column basis.

• DefineName_AFTER
  Unless you are not creating a table you are unlikely to want to change the codes that end the table.

• DefineName_LINE_FILTER
  The contents of this variable should be one or more rexx expressions.

  If an expression is supplied for this option then the filter code will be called immediately following the line having been read from the imported file. This could help you to perform slight reformatting of information etc.

  The following rexx variables are relevant:

  • FileLine
    This is the current line exactly as read from the file being imported. You may modify the contents if you need to.

  • LineFilter
    If you don't need to do any more filtering then you can clear this variable. This will improve performance.

  Note that any macros or other symbols are replaced once at the start of the import and not for each field.

• DefineName_RECORD_FILTER
  The contents of this variable should be one or more rexx expressions.

  Normally all records are displayed. A filter can examine all column variables and modify them or tell PPWIZARD to ignore the record. The filter is not called for the heading record.

  The following rexx variables and functions are relevant:

  • Remove
    If this variable is set to any non blank value then the record will be dropped, the variables value is shown when debugging so it is recommended that the value be the reason for dropping the record.

    If the contents starts with 'EOF:' then the current record and ALL following are dropped.

  • Column.?
    The "Column" array holds the data for each field (that you are interested in) of the current record in the order you provided. For example "Column.2" holds the 2nd column's data. Note that "Column.0" holds the number of fields in the array.

  • Dropped.?
    The "Dropped" array holds the data for each field (that you dropped) of the current record in the order that they were dropped. For example "Dropped.1" holds the first dropped field. Note that "Dropped.0" holds the number of fields in the array.

  • ThisRecordsCodes
    This variable gets initialized for each record with the value that you defined (or allowed to default) for the "DefineName_RECORD" option. You can add to or modify this record in any way. The value of "{$Column1}" gets replaced with the contents of the rexx variable "Column.1" etc.

    If all your records are processed the same way then you should not need to modify this variable. It is useful where you might want the output (row of table) to look different depending on the records data. In some cases this can be better done by updating the rexx "Column.?" array.

    If you need multiple lines you can of course use "<?NewLine>" where required.

  • WriteLineToTmpImportFile()
    The passed data is written to the output file, any line feed characters will indicate the end of a line.

  • GetMlField()
    This routine can be called to obtain the value of a field (the name of which is passed). You can access the fields data in a more efficient manner using the "Column" and "Dropped" arrays however this routine allows you to access a variable knowing its name.

  • RecordFilter
    If you don't need to do any more filtering then you can clear this variable. This will improve performance.

  Note that any macros or other symbols are replaced once at the start of the import and not for each field.

• DefineName_DELIMITER
  This is the character(s) that separate the name of a field from its value.

• DefineName_STRIP_LEADING
  This indicates whether or not leading whitespace on a fields value should be removed. The default is 'Y', if 'N' one only space is removed if it exists (to allow for a space after the delimiter).

• DefineName_SEPARATOR
  If you continue a field over onto a following line (the continued line has no field name) then what are the two components "stitched" together with? The default is a space.

• DefineName_LINE_COMMENT_CHAR
  This is the character that can be used to start a line for commenting your file. It defaults to the current PPWIZARD line comment character.

• DefineName_MULTILINE_FILTER
  The contents of this variable should be one or more rexx expressions.

  If an expression is supplied for this option then the filter code will be called for each non comment line found. This allows you to build extra smarts into the processing of records if you wish (for example breaking a table into sections).

  The following rexx variables are relevant:

  • MultiLine
    This is the current line without leading and trailing whitespace. You may modify the contents if you need to.

  • Remove
    If this variable is set to any non blank value then the line will be dropped, the variables value is shown when debugging so it is recommended that the value be the reason for dropping the line.

    If the contents starts with 'EOF:' then the current line and ALL following are dropped.

  • MultiLineFilter
    If you don't need to do any more filtering then you can clear this variable. This will improve performance.

  Note that any macros or other symbols are replaced once at the start of the import and not for each field.

• DefineName_KEEP_TMP_FILE
  Normally PPWIZARD keeps the temporary file it creates while importing when debug is on. This option allows you to specify whether you do or don't want the file kept (whether debug is on or off).

• DefineName_DO_PASS_2
  You would rarely wish to modify this value. It controls whether or not the generated file is #included (pass 2), its value defaults to 'Y'. You might wish to disable the processing if all your processing can be done in pass one (for example you have imported a database into memory.

• DefineName_PROTECT_START
  By default will be set to the value <?ProtectFromPpwStart>. If you have filter code that wants to generate PPWIZARD commands (or macro references) or your data contains these then you will need to override (clear) this value. Have a look at the multiple HTML pages example.

• DefineName_PROTECT_END
  By default will be set to the value <?ProtectFromPpwEnd>.

You should also check out an example of importing a file into multiple HTML pages based on the contents of one of the fields.

Example - Multi Line Import

Lets assume you have created a database (called "WEBLINKS.ML") similar to:

;--- First record ------------------------
   Name     :  Dennis
            :  Bareis
   Email    :  dennis@dennisbareis.id.au
   Web Page :  http://dennisbareis.id.au/index.htm
   Comment  :  Really good site!

;--- Second record -----------------------
    Name:  Fredric Bald
 Comment:  This comment contains LT=< & GT=> characters
Web Page:  www.somewhere.com
   Email:  fred@bnz.com

Note that in the above sample data the first "name" field spans two lines to demonstrate line continuation.

Then you can import the data and convert the email and web addresses into hypertext links with:

<HTML><BODY>
#DefineRexx ML_RECORD_FILTER
            Column.2 = "<A HREF='mailto:" || Column.2 || "'>" || Column.2 || "</A>"
            Column.3 = "<A HREF='http://" || Column.3 || "'>" || Column.3 || "</A>"
#DefineRexx
#define ML_DELIMITER      :
#import WEBLINKS.ML ML  "" "{*,Name}Name" "{*,EMail}Email<BR>Address" "{*,Web Page}http://" "{*,Comment}Comment"
</BODY></HTML>

The following code imports the same database but demonstrates field reordering (unusual requirement), field dropping (email address is not required) and requiring all fields to be specified and non-blank:

<HTML><BODY>
#define THIS1_RECORD_FILTER                                                         \
        Column.2 = "<A HREF='http://" || Column.2 || "'>" || Column.2 || "</A>"
#define THIS1_DELIMITER      :
#import WEBLINKS.ML ML  "THIS1"  "{2,Web Page,required,nonblank}http://"  \
                                 "{3,Comment,required,nonblank}Comment"   \
                                 "{1,Name,required,nonblank}Name"         \
                                 "{*,email}"
</BODY></HTML>

email me  any feedback, additional information or corrections.
See this page online (look for updates)

PPWIZARD Manual

Sunday November 05 2017 at 10:00am