Field Mapping

Top  Previous  Next

Position and Size of Fields

If the data is fixed position or delimited without using data delimiters, then specifications must be provided to describe where the field is in the record, its size and, in some cases, its format. 

The position attribute allows fields in delimited files to be out of order with respect to the input or output statement. 

For input, it also facilitates field skipping and re-use of a single input field to fill more than one database column. 
For output, all field positions must be specified exactly one time.  If you need to pass the same data to more than one output field then use aliased columns in your SELECT statement to include them in the output set.

For Input Records

For an import, the position attribute may be omitted for all fields if the input record format is delimited using a separator AND the mapping order of the input fields to the database columns is identical. 

If a generated field {ENUM} or {SYSDATE} is included, it does not necessarily break implicit ordering.

Otherwise, position is required in all cases

Note that you must not have a mix where some fields have a position and some do not.  It must be all or nothing.

The attribute specifications are interpolated after each column identifier in the DML statement.  For example:

UPDATE OR INSERT INTO COUNTRY (COUNTRY {position=1 size=15},  

  CURRENCY {position=16 size=10}) VALUES (?,?)

EXECUTE PROCEDURE ADD_EMP_PROJ (?{position=1 size=2}, ?{position=2 size=5})

The position attribute has different semantics according to whether the input record format is delimited or fixed:

in a delimited record format, position matches field position from left to right, so {position=1} maps the first field, {position=2} the second field, and so on.
in a fixed record format, position matches the position in the record where the field starts, so position 1 is the first byte of the first field (or, in this case, the first variable).  In this example, the size of the first variable is 2 bytes, so the second field is at position 3.  The {size=} attribute is not used in fixed format descriptors.

In the EXECUTE PROCEDURE example above, the input fields would overlap if the input records were fixed format. Overlapping of imported fields is not disallowed so, if you have a good reason to do it, you can.

For Output Records

On exported records, all fields, including filler fields, must be specified on output exactly once.  No overlapping is allowed between either SQL output fields or filler fields.  For output fields retrieved from the SQL query, an example for output to a fixed-length record might be expressed as follows:

options dateform=17 hyphenateDate # dd-mm-yy hh:mm:ss

SELECT 

  EMP_NO {position=1 size=2},

  FIRST_NAME {position=3 size=15},

  LAST_NAME {position=18 size=20},

  PHONE_EXT {position=38 size=4},

  HIRE_DATE {position=38 size=19} 

FROM EMPLOYEE

Text Columns

For CHAR or VARCHAR columns going to fixed output, right-padding with spaces will be performed without the need to describe the attributes of the fields.

Re-mapping Field Position

The default position for delimited data into or out of SQL with no special field positions is the order of their occurrence in the SQL statement.  For delimited records, if the field order of the input or output record is different to the SQL statement order, the {position=} element can optionally be used to re-map the order in which the fields are read from or written to the file. 

Multiple Usage of Input Fields

For reading input from a delimited record, the {position=N} phrase can be used more than once where you want to write the same input field to multiple columns in the destination table.

Alignment Issues

dbFile does not use the input file alignment as all fields use an intermediate area which is aligned for the worst case.  However, given that  it is in the order of things for numbers of all types to require alignment, potential exists for it to be a problem for the program processing an exported file.

Bad Descriptors

If you provide field descriptors that do not fit (wrong size or wrongly qualified for type) for either input or output, a parser error will occur and the run will be aborted.  For filler fields there is some margin for error, provided the specifications allow for a size that is large enough.