ddlGetRec() - read record from database(collection)

ddlGetRec() - read record from database(collection) ddlGetRec() - read record from database (collection)

Prototype:

   void ddlGetRec(
      CONTROL *ctl,
      char *OptnStr,
      char *ArgList,
      char *Image);

Permitted values in OptnStr:

   /F - force physical read from database
   /Knnn - read up to 'nnn' records per call [Ref Description]

Form of ArgList:
      <cx> [<dgname>] <rdname> [(<piPathName>)] [<RecOrdinal>]
            <cx> is the name of the collection
            <dgname> is the ASCII name of the desired data group in the database.
                  If <dgname> is omitted, the global collection is used; in this case, <rdname> must not duplicate a dgname.
            <rdname> is the ASCII name of the record description that describes Image;
            <piPathName> is the path and name of the .pi file for an external RD
            <RecOrdinal> is the ASCII representation of the ordinal within the collection to use; for example,
                  1 - use the first record in the collection
                  9 - use the ninth record in the collection

Form of Image:
       Image must reflect exactly the record described by rdname.

Description:

Reads a record from the open database. The contents of the record are stored into a record image whose form is described by the record description <rdname>.

Note that the <dgname> argument is optional. This allows a record to be read from the global collection after a RELATE. In this case, ddlGetRec() reads a single record, not a mapped frame.

The omission of the <dgname> argument also requires that the <rdname> be distinct from any <dgname>, even though Thunderbolt does not enforce this restriction.

Each call to ddlGetRec() gets the next record in the collection. The end of data condition is indicated by Control.Ans1 == 0.

If the /Knnn option is specified, up to 'nnn' records are read; and are stored consecutively (without delimiters) in Image. In this case, Control.Ans1 contains the number of records read.

The current record pointer in a collection is reset to the beginning of the collection by ddlClear(), ddlFind(), ddlFill(), ddlMatch(), ddlPick() and by ddlGetRec() at end of data.

ddlGetRec() does not support data type TEXT.

When an external RD in specified [by (piPathName)], the RD is automatically cached for possible future use.

ddlGetRec() forces a physical read from the database to ensure that the latest record is read:
. the first time it is called after PICK, FILL, FIND
. the first time it is called after ddlGetRecReset()
. if the /F option is specified
. if RecOrdinal is non-zero

ddlGetRec() returns to the first record of a collection:
. after a PICK, FILL, FIND
. after "end of data"
. after ddlGetRecReset()

Values returned in Control Structure:

Control.Ans1 If end of data: 0
If Table-specific collection: 1
       If the /Knnn options is specified, this is the
       number of records read
If global collection: hierarchy level of record - 1 thru N

Control.Ans2 Record number of record read

Control.Ans3str[] If global collection, Table name of record read

Control.Ans1	If end of data: 0 If Table-specific collection: 1 If the /Knnn options is specified, this is the number of records read If global collection: hierarchy level of record - 1 thru N
Control.Ans2	Record number of record read
Control.Ans3str[]	If global collection, Table name of record read