READ

Contents


Read is used to perform reads on a table via an access key or a temporary index.

Syntaxes

   Read [ class ] [ key ] [ read_modet [ key_value ] ]

Parameters

Element

Description

Restrictions

  Key :

Description of the key of a file under one of the following forms:
variable_name
variable_name '('
exp_ind ')'

The key must be defined in an Order By clause or by default in the
parameterization.

exp_ind

Expression entière du nombre de parties de clés utilisées. Par défaut, toute la clé est utilisée.

0<= exp_ind <=number of key components (at most 8).

read_mode

One of the following key-words or one of the following operators:

keyword

operator

Read mode used

First
Last
Curr
Prev
Next






>=
>
=
<
<=

First recording
Last recording
Current recording
Previous recording
Next recording
Key>=key_value
Key > key_value
Key=key_value
Key< key_value
Key<=key_value

key_value

List of expressions separated by ';' corresponding to the values of the sub-keys.

value comptatible with the sub-key type .

Examples

# Sequence of reads in a [TEST] file whose keys are
# - a CLE1 key (an alphanumerical element);
# - a CLE2 key (a date element, an alphanumerical element, a # Integer
element).
   # In these instances, it is assumed that the return codes are not managed.

   # Read of the 1st recording for which the 1st element of CLE2 is
   # the current days' date, then the date of the previous day, then of the previous one, in the order of the CLE1 key
    Read [TEST]CLE2(1) = date$
   
Read [TEST]CLE1 Prev

   # Read of a recording whose key CLE1 is >= "ABCD"
    Read [TEST]CLE1 >= "ABCD"

   # Read of the 1st recording of the file in the order of the key
   # CLE1; the [TEST] file is assumed to be the default file
    Read CLE1 First

   # Read the last recording in the order of the key used
   # previously. The [TEST] file is assumed to be the default file
    Read Last

Description and comments

Read is used to perform reads on an indexed, sequential file according to various modes listed in the grid below. If no key value is specified for the modes that require one ( '<', '>', '<=', '>=', '=' ), the current value of the variables of class [F] corresponding to the file is used.

The keys that can be used in Read are:

When using the link abbreviation (defined on the occasion of a previous Link) in a "Read", Adonix tries to read a recording of the main file on the basis of the key given, then a recording in each linked file based on the key and the read mode provided in Link.

The abbreviation of the file or the key name can be left out of the syntax of Read:

Reading a recording, with the details of a key part, automatically positions the [G]currlen variable; in effect, this variable contains the number of the key part being used; Caution, any subsequent read, without any details on the key, will be performed on the same key part. To read an entire key, specify the key or position the [G]currlen variable to the value 0. The value 0 is the default value.

The fstat variable indicates how the read went.

fstat

Code

Read

Explanation

0

Yes

The read was successful.

2

ERECIND

Yes

In read mode, <= or >= means that the read duly took place but the key found is < or > to the searched value.

4

ERDEBF

No

In Prev or Next mode, it indicates the end of the file. In First or Last mode, it indicates that the file (or the selection) is empty.

5

ERPALEC

No

In >=, >, =, <=, < or Curr mode, indicates that there is no recording corresponding to the requested values.

Read is used to read a locked recording but it does not indicate whether or not it is locked. To that end, the Readlock instruction needs to be used.

After a sucessful read (i.e if fstat is nul or equal to ERECIND), the variables of class [F] corresponding to the file contain the values of the recording read. This recording becomes the current recording of the file. Otherwise, nothing is modified.

Remarks

Whenever there are several recordings to be read in a table, the use of the For instruction will be preferred to Read. In effect it simplifies the write by, among other things, performing the necessary Read Next internally and speeding up access when working on a database under Oracle. As a matter of fact, each Read instruction generates a query to the server.

Some Read orders make it necessary to browse nearly the entire table, thus generating excessive execution times, especially with Oracle. It is the case with the ">=" and "<=" modes on keys with several parts. In fact :

Read CLE >= value1;value2 enables two types of recordings to be read:

Very often, only the first type of recording is of interest to the programmer, but to meet the second type, many other recordings can be browsed.

In that case, it is much quicker to execute:

Filter [ABV] Where part1 = value1 & part2 >= value2 Order by CLE
Read [ABV]CLE First.

This Read order will have to be replaced by a For loop whenever several reads should be performed. The more key parts there are, the more important this phenomenon is.

For version DB2, there is a limit on the number of fields retrieved by a query. The read of a file exceeding 255 columns generates an error, including the read of a linked file. There are no problems regarding the definiton of the table, since this check is already in place when entering these fields. On the other hand, there is a problem regarding the read based on an abbreviation derived from the Link instruction.

New to version 140

When performing a direct Read using a key with a homonym, the Sql query is generated with a systematic sort on the rowid. This is a good solution as long as other recordings need to be subseqsuently read via the Read next, otherwise it is not very efficient in case of a single read. The sort on the rowid will not be generated in the query if the total number of key parts is specified. For instance:

   # ACCES table with the key with homonym CODACC ( USR, CODACC ) 
   # sort on USR, CODACC and rowid

   Local File ACCES[ABR]
   Read [ABC] CODACC First
   Read [ABC] CODACC="XY","ZZZ"

   # sort on USR, CODACC 
   Local File ACCES[ABR]
   Read [ABC] CODACC(2) First
   Read [ABC] CODACC(2)="XY","ZZZ"

 

Associated errors

Error

Description

MODIN (22)

Read mode incorrect.

ERINDI ( 8)

The number of given values or the index mentioned, exceeds the number of elements of the key.

PACLE (21)

The key does not exist for this file.

ERCLAS (7)

The file class does not exist (file not open).

Associated keywords

READLOCK - FILE - LINK - FOR - REWRITE - DELETE - LOOK - WRITE - FSTAT - FILTER - UPDATE

CURRIND  -   CURRLEN


CONTENTS

Copyright © Sage 1999 - 2007