7.21 GET_RECORD | GET_RECORD2

Data mapping from a source to a different target format is often required when extracting or replicating data. Although the COLMAP specification supported by both Replicat and Extract works sufficiently for most, user exits may be necessary for some field conversions.

Extract and Replicat pass data records to the exit after converting to the target format. In the event that a few fields do not convert, GET_RECORD and GET_RECORD2 provide a way to obtain information for custom field conversions. For example, an exit could convert a proprietary date field (such as YYDDD) in an Enscribe database to a standard SQL date in the target record, while other columns would be mapped by Extract.

GET_RECORD is only valid for use with record less than 32767. GET_RECORD2 is valid for both these smaller records and the longer records defined with DDL2.

Formats

Deletes, inserts and updates appear in the buffer as full record images. For SQL tables, this is the same format as produced by an INVOKE of the table.

Compressed SQL updates

Compressed SQL updates have the format:

index length value index length value…

Where:

index is a two byte index into the list of columns of the table (first column is zero).
length is the two byte length of the table.
value is the actual column value, including when applicable a two byte null indicator (0 for not null, -1 for null).

Compressed Enscribe updates

Compressed Enscribe updates have the format:

offset length value offset length value

Where:

offset is the offset into the Enscribe record of the data fragment that changed.
length is the length of the fragment and value is the actual data. Fragments can span field boundaries, so full fields are not always retrieved (unless compression is off or FETCHCOMPS is elected).

Compressed Primary Key Updates

Compressed primary key updates contain three parts:

The before-image key length
The before-image key value in field comp format
The after-image in field comp format

You can modify the record keeping the format intact, or use DECOMPRESS_RECORD and COMPRESS_RECORD to obtain a full record format. To use the callback functions, you will need to separate the before and after-images and use the callback on only one portion at a time.

Use the following to move the record pointer so that you can manipulate the before-image up to the before_len. Note that the size of key length fields must be a long.

long before_len;
long after_len;
char *rec_ptr;
memcpy (&before_len, rec, sizeof(before_len));  /* get before len */
rec_ptr = rec + sizeof (before_len);   /* move rec_ptr passed len */

For the after-image, use the following to manipulate the after-image up to the after_len.:

rec_ptr += before_len;
after_len = exit_params->record_len - sizeof (before_len) - before_len;

To see an example of the trail record with its before and after-images, use Logdump with the Detail option set on.

Syntax GET_RECORD

For C:

#include "usrdecs"
char     *buf;
short    len;
short    io_type;
short    source_or_target;
short    result;
result = GET_RECORD (buf, &len, &io_type, source_or_target);

For TAL:

?source usrdect
int result;
string .ext buf;
int    .ext len;
int    .ext io_type;
int    source_or_target;
result := GET_RECORD (buf, len, io_type, source_or_target);

For COBOL:

?CONSULT =EXTRACT (or =REPLICAT)
01 buf              PIC X(32767).
01 len              PIC S9(4) COMP.
01 io-type          PIC S9(4) COMP.
01 source-or-target PIC S9(4) COMP.
01 result           PIC S9(4) COMP.
ENTER C "GET_RECORD" using buf, len, io-type, source-or-target
                     giving result.

buf

The record buffer for data returned by the Extract or Replicat programs. The memory for this buffer must be allocated by the user. Up to X(32767) can be used for the buffer.

io_type

io-type

Indicates the type of operation represented by the record, such as:

3 — Delete

5 — Insert

10 — Update

11 — Compressed Enscribe Update

15 — Compressed SQL Update

115 — Compressed primary key Update

len

LEN is the length of the data returned in BUF.

source_or_target

source-or-target

Represented by either EXIT‐FN‐SOURCE‐VAL or EXIT-FN-TARGET-VAL to indicate whether to retrieve the source or target record.

result

A code indicating whether the call was successful or not.

Syntax GET_RECORD2