The database import library module has the file name iexlib.c. This module allows ASCII data in either fixed field length or variable field delimited to be imported into a Bbuuzzb table. Any mention of QNX in this document refers to the QNX 4.x OS. This API is available for all platforms.
This module is only linked 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 link list. This link list contains a series of import specifications loaded from an import template.
Here is a list of functions in this module:
This module requires the following modules:
In the Linux/Unix/QNX platforms, this module is compiled along with the other database modules as part of the script cdbeng.
This module depends on the following header files:
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:
|
| 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 function (or use the iex application). You also may import one ascii line at a time with any processing you like by first using the function iexlib_start to load the profile followed by the function iexlib_import_do_line for each ascii input line and iexlib_stop when all lines are completed.
The function 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 function iexlib_import (high level) 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.
Prototype : int iexlib_import(char *profile_name, char *in_file_name,
char *out_table_name)
Parameters :
Name : profile_name
Description: name of profile/template (stored in field one of the iex.config record)
Name : in_file_name
Description: path and name of input ASCII file
Name : out_table_name
Description: name of output bbuuzzb table
Returns : dbeng code
This function 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.
Prototype : int iexlib_start(char *profile_name)
Parameters :
Name : profile_name
Description: name of profile/template (stored in field one of the iex.config record)
Returns : dbeng code
This function will obtain the iex profile record from the profile_name and load all module globals and the iex_spec link list. This function should be used when manual control over the import process is desired.
Prototype : void iexlib_stop(void)
This function will delete the iex_spec link list and set module globals to zero/null. This function should only be called at the end of the import process when using manual control (import started with iexlib_start).
Prototype : int iexlib_active(void) Returns : TRUE if active profile loaded, FALSE otherwise
This function will determine whether there is a current iex profile loaded into the iex_spec link list.
Prototype : void iexlib_dump(void)
This function will output the contents of the global data and the iex_spec link list to the logging manger. Note that logging manager must already be turned on.
Prototype : int iexlib_import_do_line(int out_tid, char *line)
Parameters :
Name : out_tid
Description: output table tid
Name : line
Description: input ASCII line
Returns : dbeng code
This function will import the input ASCII line from the input ascii file into the bbuuzzb output table. This function should be called once per ASCII input line if the import is under manual control.
Prototype : static int iexlib_config_set_sd(int is_source, int tid, int rsf,
struct iex_spec *ot)
Parameters :
Name : is_source
Description: source field flag
Name : tid
Description: iex profile input table tid
Name : rsf
Description: input subfield
Name : ot
Description: link list member
Returns : dbeng code
This private function will load the source or destination field specification from the iex profile record into the link list node.
Prototype : static int iexlib_config_set_conv(int tid, int rsf,
struct iex_spec *ot)
Parameters :
Name : tid
Description: iex profile input table tid
Name : rsf
Description: input subfield
Name : ot
Description: link list member
Returns : dbeng code
This private function will load the conversion spec from the iex profile record into the link list node.
Prototype : static int iexlib_config_get_sd(char *fdat, int *f, int *sf,
int *ssf)
Parameters :
Name : fdat
Description: source or destination field soec from iex profile data
Name : f
Description: returned field number
Name : sf
Description: returned subfield number
Name : ssf
Description: returned subsubfield number
Returns : dbeng code
This private function will parse a source or destination field spec into its component parts.
Prototype : static int iexlib_import_get_ascii_field(char *line, char *outf,
struct iex_spec *ot)
Parameters :
Name : line
Description: input ASCII line
Name : outf
Description: output raw, trimed data
Name : ot
Description: link list member
Returns : dbeng code
This private function 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 link list member pointer must point to a valid iex_spec node and the field will be obtained from this spec and placed into output raw, trimed data (which must already be allocated by the caller).
Prototype : static int iexlib_import_match(int tid, char *line)
Parameters :
Name : tid
Description: output table tid
Name : line
Description: input ASCII line
Returns : dbeng code
This private function 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.
Prototype : static int iexlib_import_do_wind_dir(int tid, char *ifield,
struct iex_spec *ot)
Parameters :
Name : tid
Description: output table tid
Name : ifield
Description: input ASCII wind direction (W,NE,SSW etc)
Name : ot
Description: link list member
Returns : dbeng code
This private function 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 link list member specification.
Prototype : static int iexlib_import_do_time(int tid, char *ifield,
struct iex_spec *ot)
Parameters :
Name : tid
Description: output table tid
Name : ifield
Description: input ASCII time (hh:mm[a|p])
Name : ot
Description: link list member
Returns : dbeng code
This private function will convert the input ASCII time to 24 hour notation (with no colon) and place the data into a bbuuzzb record according to the link list member specification.
Prototype : static int iexlib_import_do_fxp(int tid, char *ifield,
struct iex_spec *ot)
Parameters :
Name : tid
Description: output table tid
Name : ifield
Description: input ASCII floating-point number
Name : ot
Description: link list member
Returns : dbeng code
This private function will convert the input ASCII floating-point number and place the data into the bbuuzzb record according to the link list member specification. The result data is in fxp format.
Prototype : static int iexlib_import_do_int(int tid, char *ifield,
struct iex_spec *ot)
Parameters :
Name : tid
Description: output table tid
Name : ifield
Description: input ASCII integer
Name : ot
Description: link list member
Returns : dbeng code
This private function will convert the input ASCII integer and place the data into the bbuuzzb record according to the link list member specification.
Prototype : static int iexlib_import_do_pint(int tid, char *ifield,
struct iex_spec *ot)
Parameters :
Name : tid
Description: output table tid
Name : ifield
Description: input ASCII integer
Name : ot
Description: link list member
Returns : dbeng code
This private function will convert the input ASCII integer plus a constant and place the data into the bbuuzzb record according to the link list member specification.
Prototype : static int iexlib_import_do_month(int tid, char *ifield,
struct iex_spec *ot)
Parameters :
Name : tid
Description: output table tid
Name : ifield
Description: input ASCII month name (3 char. abbr.)
Name : ot
Description: link list member
Returns : dbeng code
This private function will convert the input ASCII month name to a month number (base 1) and place the data into a bbuuzzb record according to the link list member specification.
Prototype : static int iexlib_import_conv_wind_dir(char *ifield,
struct iex_spec *ot,
char *ofield)
Parameters :
Name : ifield
Description: input ASCII wind direction (W,SE,NNW etc)
Name : ot
Description: link list member
Name : ofield
Description: output ASCII wind direction in degrees (fxp, scale 1)
Returns : TRUE upon success, FALSE otherwise
This private function will convert the input ASCII wind direction according to the link list member specification. This function will load the result into the output ASCII wind direction upon success (which must already be allocated to the sufficient size by the caller). This function is used only to match records from iexlib_import_match.
Prototype : static int iexlib_import_conv_time(char *ifield, char *ofield)
Parameters :
Name : ifield
Description: input ASCII time (hh:mm[a|p])
Name : ot
Description: link list member
Name : ofield
Description: output ASCII time (hhmm, no colon)
Returns : TRUE upon success, FALSE otherwise
This private function will convert the input ASCII time. Upon success, the output ASCII time will be loaded with the result (which must already be allocated to the sufficient size by the caller).
Prototype : static int iexlib_import_conv_int(char *ifield,
struct iex_spec *ot,
char *ofield)
Parameters :
Name : ifield
Description: input ASCII integer
Name : ot
Description: link list member
Name : ofield
Description: output ASCII integer
Returns : TRUE upon success, FALSE otherwise
This private function will convert the input ASCII integer according to the link list member specification. This function will load the result into the output ASCII integer upon success (which must already be allocated to the sufficient size by the caller).
Prototype : static int iexlib_import_conv_pint(char *ifield,
struct iex_spec *ot,
char *ofield)
Parameters :
Name : ifield
Description: input ASCII integer
Name : ot
Description: link list member
Name : ofield
Description: output ASCII integer
Returns : TRUE upon success, FALSE otherwise
This private function will convert a plus integer, which is an integer plus a constant according to the link list member specification. This function will load the result into the output ASCII integer upon success (which must already be allocated to the sufficient size by the caller).
Prototype : static int iexlib_import_conv_fxp(char *ifield,
struct iex_spec *ot,
char *ofield)
Parameters :
Name : ifield
Description: input ASCII floating-point number
Name : ot
Description: link list member
Name : ofield
Description: output ASCII fxp number
Returns : TRUE upon success, FALSE otherwise
This private function will convert the input ASCII floating-point number according to the link list member specification. This function will load the result into the output ASCII fxp number upon success (which must already be allocated to the sufficient size by the caller). 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 function is used only to match records with iexlib_import_match.
Prototype : static int iexlib_import_conv_month(char *ifield, char *ofield)
Parameters :
Name : ifield
Description: input ASCII month name (3 chars.)
Name : ofield
Description: output ASCII month number
Returns : TRUE upon success, FALSE otherwise
This private function 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 (which must already be allocated to sufficient size by the caller).
Prototype : static int iexlib_import_put_fxp(int tid, struct fxp *dat,
struct iex_spec *ot)
Parameters :
Name : tid
Description: output table tid
Name : dat
Description: input fxp number
Name : ot
Description: link list member
Returns : dbeng code
This private function will place the input fxp number into a bbuuzzb record according to the link list member specification.
Prototype : static int iexlib_import_put_data(int tid, char *dat,
struct iex_spec *ot)
Parameters :
Name : tid
Description: output table tid
Name : dat
Description: input data
Name : ot
Description: link list member
Returns : dbeng code
This private function will place the input data into a bbuuzzb record according to the link list member specification.
Prototype : static int iexlib_import_conv_get_token(char *keywrd)
Parameters :
Name : keywrd
Description: input conversion keyword
Returns : keyword token ID (defined in iexlib.h)
This private function will translate the input conversion keyword to a keyword token ID.