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:

Module Dependencies

This module requires the following modules:

Module Definition Files

The following modules are required along with this module:

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