IEDTGET - Read a record

This access function can be used to read a record from a work file.

The record that is to be read is defined by means of the following specifications:

• Work file ($0..$22) in the field EAMFILE (EDTAMCB): work file from which the record is to be read

• Line number of a work file record in the buffer EDTKEY1 (the record does not have to exist).

• Displacement n (0, +N, -N) in the field EAMDISP (EDTAMCB): distance (in records) from the specified line number in binary format

• Character set in which the record is to be made available, in the field EGLCCSN (EDTGLCB)

Records with record mark 13 (see section “IEDTPTM - Mark a record”) are only taken into account if the flag EAMIGN13 is set in the field EAMFLAG in the control block EDTAMCB. Otherwise, they are handled as if they did not exist.

The interface permits two types of addressing:

• Absolute addressing

• Relative addressing

Reading a record with a specific line number – absolute addressing

Displacement specification (EAMDISP): n = 0

If the value 0 is specified for the displacement then the record with the corresponding line number (EDTKEY1) is searched for.

If this record is not present then the record with the next line number is passed (possibly the first or last record).

Summary of the return codes and the read record:

EDTKEY1	EAMDISP	EGLMRET	EAMSR1	EDTREC
Line number of an existing record	0	EAMRETOK	EAMOK00	Record with line number = EDTKEY1
Smaller than line number of first record	0	EAMRETOK	EAMOK08	First record
Larger than line number of last record	0	EAMRETOK	EAMOK12	Last record
Larger than line number of first record and smaller than line number of last record and not the line number of an existing record	0	EAMRETOK	EAMOK04	Next record after EDTKEY1
Work file does not contain any records		EAMACERR	EAMAC16

If the search is successful, EDT passes the line number of the record that was actually read in EDTKEY.
For the meaning of the return codes, see section “EDTGLCB - Global EDT control block”.

Reading a record with relative addressing

Displacement specification (EAMDISP): n = +N/-N (Nî0)

The address of the record to be read consists of

• the line number of a record (EDTKEY1),

• the displacement N of the record relative to the specified line number:

  +N: the Nth (logical) record after the specified line number is read,

  -N: the Nth (logical) record before the specified line number is read,

If the required record lies outside of the work file's line number range then the first or last record is returned.

If either of the line numbers X'0000000000000000' or X'FFFFFFFFFFFFFFFF' is specified as the number of the record that is to be read then the displacement specification is calculated relative to a fictitious record occurring either in front of or after all the others. I.e. the displacement specification 1 or -1 then returns either the first or the last record in the work file.

Summary of the return codes and the read record:

EDTKEY1	EAMDISP	EGLMRET	EAMSR1	EDTREC
EDTKEY1 = XXXXXXXX	+N (N <= records after EDTKEY1)	EAMRETOK	EAMOK00	Record N after EDTKEY1
EDTKEY1 = XXXXXXXX	-N (N <= records before EDTKEY1)	EAMRETOK	EAMOK08	Record N before EDTKEY1
EDTKEY1 = XXXXXXXX	+N (N > records after EDTKEY1)	EAMRETOK	EAMOK12	Last record
EDTKEY1 = XXXXXXXX	-N (N > records before EDTKEY1)	EAMRETOK	EAMOK04	First record
Work file does not contain any records		EAMACERR	EAMAC16

If the search is successful, EDT passes the line number of the record that was actually read in EDTKEY.

For the meaning of the return codes, see section “EDTGLCB - Global EDT control block”.

Call

The following specifications are required (see overview):

• Entry of values in the required fields in the EDTGLCB and EDTAMCB control blocks.

• Entry of values in the EDTKEY1 buffer

• Provision of storage space for the buffers EDTKEY and EDTREC

• Call of the entry point address IEDTGET with the parameter list

Overview

(For the control blocks, see section “Generation and structure of the control blocks”).

Entry point address     :     IEDTGET

Parameter list         :     A (EDTGLCB, EDTAMCB, EDTKEY1, EDTKEY,

EDTREC)

Call parameter		Return parameter
EDTGLCB:	EGLUNIT EGLVERS EGLCCSN	EDTGLCB:	EGLRETC EGLRMSG
EDTAMCB:	EAMUNIT EAMVERS EAMFILE EAMDISP EAMLKEY1 EAMPKEY EAMPREC	EDTAMCB:	EAMMARK EAMLKEY EAMLREC
EDTKEY1 EDTKEY EDTREC		EDTKEY EDTREC

For the possible return codes, see “Logical record access functions”.

Return parameters on successful record access

Alongside the EGLRETC field in EDTGLCB (EGLMRET = EAMRETOK), EDT specifies the following parameters:

Record	EDTREC
Record length	EAMLREC in EDTAMCB
Line number	EDTKEY (always 8 bytes in length)
Length of line number	EAMLKEY in EDTAMCB (always 8 bytes)
Record mark	EAMMARK in EDTAMCB

If the buffer length (EAMPREC) is not sufficient to accommodate the record, EAMACERR is entered for EGLMRET and EAMAC12 is entered for EGLSR1. The record is truncated. The actual length read is entered in the EAMLREC field in AMCB.

In compatibility mode (as in EDT V16.6), the buffer length required to read the record in full is stored here. In Unicode mode, however, it is necessary to specify the number of bytes actually transferred since multi-byte coding always requires the record to be truncated between two valid characters and, consequently, fewer bytes may be transferred than are specified in EAMPREC.

If access is unsuccessful, the fields EAMLKEY and EAMLREC are filled with the value 0.

Call in the C program

Required include files:

#include <stdio.h>

#include <iedtgle.h>

The control block EDTAMCB is declared and initialized as follows (the value 1024 here was selected as an example of the maximum expected record length):

iedamcb amcb = IEDAMCB_INIT;
char rec[1024];
char key[8], key1[8];
amcb.length_key1 = 8;
amcb.length_key_outbuffer = 8;
amcb.length_rec_outbuffer = 1024;

The specifications for the other parameters are user-dependent. If, for example, the1st record in work file 0 is searched for:

strncpy(amcb.filename,"$0     ",8);
strncpy(key1,"00000001",8); 
amcb.displacement = 0;

Function call:

IEDTGET(&glcb,&amcb,key1,key,rec);