Tcl Database Import Library

The Tcl database import library module has the file name iexlib.tcl. This module allows ASCII data in either fixed field length or variable field delimited to be imported into a Bbuuzzb table.

This module is only sourceed with applications that require the import facility. At the moment, this module provides for import only. At some future date, this module will be enhanced to also provide for data export from Bbuuzzb tables into ASCII files.

This module manages the iex_spec array. This array contains a series of import specifications loaded from an import template.

Here is a list of functions in this module:

- iexlib_import
- iexlib_start
- iexlib_stop
- iexlib_active
- iexlib_dump
- iexlib_import_do_line
- iexlib_config_set_sd
- iexlib_config_set_conv
- iexlib_config_get_sd
- iexlib_import_get_ascii_field
- iexlib_import_match
- iexlib_import_do_wind_dir
- iexlib_import_do_time
- iexlib_import_do_fxp
- iexlib_import_do_int
- iexlib_import_do_pint
- iexlib_import_do_month
- iexlib_import_conv_wind_dir
- iexlib_import_conv_time
- iexlib_import_conv_int
- iexlib_import_conv_pint
- iexlib_import_conv_fxp
- iexlib_import_conv_month
- iexlib_import_put_fxp
- iexlib_import_put_data
- iexlib_import_conv_get_token

# Module Dependencies

This module requires the following modules:

- either the complete single user database suite or the complete client/server database suite
- fixed-point number API
- database fixed-point number API
- weather library

# Module Definition Files

The following modules are required along with this module:

- stdhead.tcl
- dbmess.tcl

# The Import Profile/Template

ASCII data import is accomplished using an import profile or template (hereafter referred to as the profile). The profile is a Bbuuzzb record in the iex.config table. The profile field layout is as follows:

Element | Description
--- | ---
1 | profile name: usually containing name of user program (any length)
2 | comment: any length
3 | operation code: i for import, x for export (no export currently)
4 | input ASCII format: f for fixed field or field delimiter otherwise
5 | array of specs: each complete spec is a subfield containing the following subsubfields:
5,*,1 | source field: field number for delimited or start,chars for fixed, note that start byte is zero based
5,*,2 | conversion: one of:

- fxp[,n] - fxp number optionally with n scale (zero if no scale)
- time - convert hh:mm[a|p] to 24hrs. with no colon
- int[,n] - integer optionally padded on the left with zeros to n length
- pint,n - integer plus the parameter which is mandatory
- winddir - convert a wind direction alpha (N,NW,S,SSE etc) to degrees (result is fxp with scale of one)
- month - convert a three char alpha month name to an integer (base one) zero padded on the left to two digits
- an empty value here denotes no conversion

5,*,3 | destination field: must be a bbuuzzb field, subfield or subsubfield in the form f[,sf][,ssf], zero may be used in any part to indicate an append (append not recommended)
6 | auto record locate/create switch: see below
7 | bbuuzzb field to match (optional): if present, an attempt will be made to locate an existing matching record
8 | ascii null field signature (optional): if present, these chars will denote an empty input ascii field

There must be at least six fields present in the iex profile record. Notice that field five is a two-dimensional array of import specifications. Each import spec consists of the source field (from the ASCII file) spec, a conversion spec and a destination field (bbuuzzb field, subfield or subsubfield) spec.

This module may be used in a couple of different ways. To import an entire file at once without any special processing, call the iexlib_import procedure (or use the iex application). You also may import one ascii line at a time with any processing you like by first using the procedure iexlib_start to load the profile followed by the procedure iexlib_import_do_line for each ascii input line and iexlib_stop when all lines are completed.

The procedure iexlib_import is a good example of manually controlling the import.

The auto record locate/create switch is used in conjunction with the match field. If the auto record switch is off(0), the caller is assumed to have already set the bbuuzzb file position and no automatic record location or creation will take place. If the auto switch is on(1) and there is a match field present, an attempt will be made to find the matching bbuuzzb record before the import of that ascii line takes place. If the find of the bbuuzzb record fails, a new output record will be created. If the auto switch is on and there is no match field present, a new bbuuzzb output record will be created for each ascii input line. As a guideline, set the auto switch high when you will be using the procedure iexlib_import to import the entire ascii file at once. Set the auto switch low when you will be manually controlling the import. When the auto record switch is low, any value in the match field will be ignored.

# Module Procedures

## iexlib_import

    Declaration  : proc iexlib_import {profile_name in_file_name out_table_name}
    Parameters   :
          Name   : profile_name
          Type   : string
    Description  : name of profile/template (stored in field one of the iex.config record)

          Name   : in_file_name
          Type   : string
    Description  : path and name of input ASCII file

          Name   : out_table_name
          Type   : string
    Description  : name of output bbuuzzb table

    Returns      : dbeng code

This procedure will perform a regular (no special processing) import of the input ASCII file into the output bbuuzzb table. All input records will be processed. A new output record or a re-write of an existing bbuuzzb record will take place for each input record depending on the status of the profile auto record locate/create switch.

## iexlib_start

    Declaration  : proc iexlib_start {profile_name}
    Parameters   :
          Name   : profile_name
          Type   : string
    Description  : name of profile/template (stored in field one of the iex.config record)

    Returns      : dbeng code

This procedure will obtain the iex profile record from the profile_name and load all module globals and the iex_spec array. This procedure should be used when manual control over the import process is desired.

## iexlib_stop

    Declaration  : proc iexlib_stop {}

This procedure will delete the iex_spec array and set the module globals to zero/null. This procedure should only be called at the end of the import process when using manual control (import started with iexlib_start).

## iexlib_active

    Declaration  : proc iexlib_active {}

    Returns      : TRUE if active profile loaded, FALSE otherwise

This procedure will determine whether there is a current iex profile loaded into the iex_spec array.

## iexlib_dump

    Declaration  : proc iexlib_dump {}

This procedure will output the contents of the global data and the iex_spec array to the logging manger. Note that logging manager must already be turned on.

## iexlib_import_do_line

    Declaration  : proc iexlib_import_do_line {out_tid line}
    Parameters   :
          Name   : out_tid
          Type   : positive integer
    Description  : output table tid

          Name   : line
          Type   : string
    Description  : input ASCII line

    Returns      : dbeng code

This procedure will import the input ASCII line from the input ascii file into the bbuuzzb output table. This procedure should be called once per ASCII input line if the import is under manual control.

## iexlib_config_set_sd

    Declaration  : proc iexlib_config_set_sd {is_source tid rsf}
    Parameters   :
          Name   : is_source
          Type   : boolean flag
    Description  : source field flag

          Name   : tid
          Type   : positive integer
    Description  : iex profile input table tid

          Name   : rsf
          Type   : positive integer
    Description  : input subfield

    Returns      : dbeng code

This procedure will load the source or destination field specification from the iex profile record into the iex_spec array.

## iexlib_config_set_conv

    Declaration  : proc iexlib_config_set_conv {tid rsf}
    Parameters   :
          Name   : tid
          Type   : positive integer
    Description  : iex profile input table tid

          Name   : rsf
          Type   : positive integer
    Description  : input subfield

    Returns    : dbeng code

This procedure will load the conversion spec from the iex profile record into the iex_spec array.

## iexlib_config_get_sd

    Declaration  : proc iexlib_config_get_sd {fdat f sf ssf}
    Parameters   :
          Name   : fdat
          Type   : string
    Description  : source or destination field spec from iex profile data

          Name   : f
          Type   : positive integer
    Description  : returned field number

          Name   : sf
          Type   : positive integer
    Description  : returned subfield number

          Name   : ssf
          Type   : positive integer
    Description  : returned subsubfield number

    Returns      : dbeng code

This procedure will parse a source or destination field spec into its component parts.

## iexlib_import_get_ascii_field

    Declaration  : proc iexlib_import_get_ascii_field {line outfield spec}
    Parameters   :
          Name   : line
          Type   : string
    Description  : input ASCII line

          Name   : outfield
          Type   : string
    Description  : output raw, trimed data

          Name   : spec
          Type   : positive integer
    Description  : iex_spec array element number

    Returns      : dbeng code

This procedure will obtain a field within the ascii import line. The field data is retrieved based on whether the input format is fixed or delimited (contained in the globals). The iex_spec array element number must point to a valid iex_spec element and the field will be obtained from this spec and placed into output raw, trimed data.

## iexlib_import_match

    Declaration  : proc iexlib_import_match {tid line}
    Parameters   :
          Name   : tid
          Type   : positive integer
    Description  : output table tid

          Name   : line
          Type   : string
    Description  : input ASCII line

    Returns      : dbeng code

This procedure will attempt to match the input ascii field with bbuuzzb data by applying the specified conversion to the input ascii field and attempting to locate a bbuuzzb record with the matching data.

## iexlib_import_do_wind_dir

    Declaration  : proc iexlib_import_do_wind_dir {tid ifield spec}
    Parameters   :
          Name   : tid
          Type   : positive integer
    Description  : output table tid

          Name   : ifield
          Type   : string
    Description  : input ASCII wind direction (W,NE,SSW etc)

          Name   : spec
          Type   : positive integer
    Description  : iex_spec array element number

    Returns      : dbeng code

This procedure will convert the input wind direction from alpha to degrees (fxp number with a scale of one) and place the data into the bbuuzzb record according to the iex_spec array element number specification.

## iexlib_import_do_time

    Declaration  : proc iexlib_import_do_time {tid ifield spec}
    Parameters   :
          Name   : tid
          Type   : positive integer
    Description  : output table tid

          Name   : ifield
          Type   : string
    Description  : input ASCII time (hh:mm[a|p])

          Name   : spec
          Type   : positive integer
    Description  : iex_spec array element number

    Returns      : dbeng code

This procedure will convert the input ASCII time to 24 hour notation (with no colon) and place the data into a bbuuzzb record according to the iex_spec array element number specification.

## iexlib_import_do_fxp

    Declaration  : proc iexlib_import_do_fxp {tid ifield spec}
    Parameters   :
          Name   : tid
          Type   : positive integer
    Description  : output table tid

          Name   : ifield
          Type   : string
    Description  : input ASCII floating-point number

          Name   : spec
          Type   : positive integer
    Description  : iex_spec array element number

    Returns      : dbeng code

This procedure will convert the input ASCII floating-point number and place the data into the bbuuzzb record according to the iex_spec array element number specification. The result data is in fxp format.

## iexlib_import_do_int

    Declaration  : proc iexlib_import_do_int {tid ifield spec}
    Parameters   :
          Name   : tid
          Type   : positive integer
    Description  : output table tid

          Name   : ifield
          Type   : string
    Description  : input ASCII integer

          Name   : spec
          Type   : positive integer
    Description  : iex_spec array element number

    Returns      : dbeng code

This procedure will convert the input ASCII integer and place the data into the bbuuzzb record according to the iex_spec array element number specification.

## iexlib_import_do_pint

    Declaration  : proc iexlib_import_do_pint {tid ifield spec}
    Parameters   :
          Name   : tid
          Type   : positive integer
    Description  : output table tid

          Name   : ifield
          Type   : string
    Description  : input ASCII integer

          Name   : spec
          Type   : positive integer
    Description  : iex_spec array element number

    Returns      : dbeng code

This procedure will convert the input ASCII integer plus a constant and place the data into the bbuuzzb record according to the iex_spec array element number specification.

## iexlib_import_do_month

    Declaration  : proc iexlib_import_do_month {tid ifield spec}
    Parameters   :
          Name   : tid
          Type   : positive integer
    Description  : output table tid

          Name   : ifield
          Type   : string
    Description  : input ASCII month name (3 char. abbr.)

          Name   : spec
          Type   : positive integer
    Description  : iex_spec array element number

    Returns      : dbeng code

This procedure will convert the input ASCII month name to a month number (base 1) and place the data into a bbuuzzb record according to the iex_spec array element number specification.

## iexlib_import_conv_wind_dir

    Declaration  : proc iexlib_import_conv_wind_dir {ifield spec ofield}
    Parameters   :
          Name   : ifield
          Type   : string
    Description  : input ASCII wind direction (W,SE,NNW etc)

          Name   : spec
          Type   : positive integer
    Description  : iex_spec array element number

          Name   : ofield
          Type   : fxp
    Description  : output ASCII wind direction in degrees (fxp, scale 1)

    Returns      : TRUE upon success, FALSE otherwise

This procedure will convert the input ASCII wind direction according to the iex_spec array element number specification. This procedure will load the result into the output ASCII wind direction upon success. This procedure is used only to match records from iexlib_import_match.

## iexlib_import_conv_time

    Declaration  : proc iexlib_import_conv_time {ifield ofield}
    Parameters   :
          Name   : ifield
          Type   : string
    Description  : input ASCII time (hh:mm[a|p])

          Name   : ofield
          Type   : string
    Description  : output ASCII time (hhmm, no colon)

    Returns      : TRUE upon success, FALSE otherwise

This procedure will convert the input ASCII time. Upon success, the output ASCII time will be loaded with the result.

## iexlib_import_conv_int

    Declaration  : proc iexlib_import_conv_int {ifield spec ofield}
    Parameters   :
          Name   : ifield
          Type   : string
    Description  : input ASCII integer

          Name   : spec
          Type   : positive integer
    Description  : iex_spec array element number

          Name   : ofield
          Type   : string
    Description  : output ASCII integer

    Returns      : TRUE upon success, FALSE otherwise

This procedure will convert the input ASCII integer according to the iex_spec array element number specification. This procedure will load the result into the output ASCII integer upon success.

## iexlib_import_conv_pint

    Declaration  : proc iexlib_import_conv_pint (ifield spec ofield}
    Parameters   :
          Name   : ifield
          Type   : string
    Description  : input ASCII integer

          Name   : spec
          Type   : positive integer
    Description  : iex_spec array element number

          Name   : ofield
          Type   : string
    Description  : output ASCII integer

    Returns      : TRUE upon success, FALSE otherwise

This procedure will convert a plus integer, which is an integer plus a constant according to the iex_spec array element number specification. This procedure will load the result into the output ASCII integer upon success.

## iexlib_import_conv_fxp

    Declaration  : proc iexlib_import_conv_fxp {ifield spec ofield}
    Parameters   :
          Name   : ifield
          Type   : string
    Description  : input ASCII floating-point number

          Name   : spec
          Type   : positive integer
    Description  : iex_spec array element number

          Name   : ofield
          Type   : string
    Description  : output ASCII fxp number

    Returns      : TRUE upon success, FALSE otherwise

This procedure will convert the input ASCII floating-point number according to the iex_spec array element number specification. This procedure will load the result into the output ASCII fxp number upon success. Note that the result is in bbuuzzb fxp format (no decimal and padded on the right with zeros to the desired precision or scale). This procedure is used only to match records with iexlib_import_match.

## iexlib_import_conv_month

    Declaration  : proc iexlib_import_conv_month {ifield ofield}
    Parameters   :
          Name   : ifield
          Type   : string
    Description  : input ASCII month name (3 chars.)

          Name   : ofield
          Type   : string
    Description  : output ASCII month number

    Returns      : TRUE upon success, FALSE otherwise

This procedure will convert the input ASCII month name to a month number zero padded to two digits (base one). This function will load the result into the output ASCII month number upon success.

## iexlib_import_put_fxp

    Declaration  : proc iexlib_import_put_fxp {out_tid dat spec}
    Parameters   :
          Name   : out_tid
          Type   : positive integer
    Description  : output table tid

          Name   : dat
          Type   : fxp number
    Description  : input fxp number

          Name   : spec
          Type   : positive integer
    Description  : iex_spec array element number

    Returns      : dbeng code

This procedure will place the input fxp number into a bbuuzzb record according to the iex_spec array element number specification.

## iexlib_import_put_data

    Declaration  : proc iexlib_import_put_data {out_tid dat spec}
    Parameters   :
          Name   : out_tid
          Type   : positive integer
    Description  : output table tid

          Name   : dat
          Type   : string
    Description  : input data

          Name   : spec
          Type   : positive integer
    Description  : iex_spec array element number

    Returns      : dbeng code

This procedure will place the input data into a bbuuzzb record according to the iex_spec array element number specification.

## iexlib_import_conv_get_token

    Declaration  : proc iexlib_import_conv_get_token {keywrd}
    Parameters   :
          Name   : keywrd
          Type   : string
    Description  : input conversion keyword

    Returns      : keyword token ID

This procedure will translate the input conversion keyword to a keyword token ID.

Goto Top | Tcl Database Engine and API's | Tcl Applications | Tcl Software Overview | Tcl Library Overview
| Future Lab Home | Contact Webmaster | Feedback

Copyright © 2006 Future Lab, Last Updated Jul 01, 2006