Field Information


General

CouNT Fields

Get the number of fields in the file.

Sbasic
    number = NRfields(#bufferid)
Assembler
    CNTF
    bufferid
    return short number of fields
C
    long DDnrfields(long bufferid, short *result);
  
errors, code,   meaning
itnf     -7     invalid bufferid

CYCle Fields

This command allows you to find out all you want to know about all the fields in as few calls as possible. Given a seed fieldid, you can get fieldname, type and fieldid all in one go.

A fieldname is maximum 16 characters long and that amount of space has to be available in the return string (no problem in Sbasic).

This command can't give any information about fieldid zero, but that is no problem as that field always is the memo field.

Sbasic
    name$ = CYCLEfield$(#bufferid, seed, type)
    seed : short, updated with fieldid
    type : updated short
Assembler
    CYCF
    bufferid
    short seed, can be updated
    short type, can be updated
    return string fieldname
C
    long DDcyclefield(long bufferid, short *seed,
                      short *type, long *return);
  
errors, code,   meaning
itnf    -7      invalid bufferid
orng    -4      a fieldid always has to be in the 0-255 range
eof     -10     no fields left (seed updated to zero)

FieLD Type

Get the type of the given field.

Sbasic
    type = fieldTYPE(#indexid, field)
Assembler
    FLDT
    indexid
    field
    return short field type
C
    long DDfieldtype(long indexid, short field, short *result);
  
errors, code,   meaning
itnf    -7      invalid bufferid or indexid
ipar    -15     field doesn't exist

FieLDName

Get the name of a field with given id.

A fieldname is maximum 16 characters long and that amount of space has to be available in the return string (no problem in Sbasic).

Sbasic
    name$ = fieldNAME$(#bufferid, field)
Assembler
    FLDN
    bufferid
    field
    return string fieldname
C
    long DDfieldname(long bufferid, short field, char *result);
  
errors, code,   meaning
itnf    -7      invalid bufferid
ipar    -15     fieldid doesn't exist

ID of FIeld

Get the id of the field with the given name (case dependant).

Sbasic
    id = fieldID(#bufferid, name)
    name : string
Assembler
    IDFI
    bufferid
    string fieldname
    return short fieldid
C
    long DDfieldtype(long bufferid, short field, short *result);
  
errors, code,   meaning
itnf    -7      invalid bufferid
                or fieldname not found
inam    -12     null name invalid

LENgth of Field

Get the length of the given field, that is the number of elements in the field.

Sbasic
    len = fieldLEN(#bufferid, field)
Assembler
    LENF
    bufferid
    field
    return long length
C
    long DDfieldlen(long bufferid, short field, long *result);
  
errors, code,   meaning
itnf    -7      invalid bufferid
                or field not found

LENgth of String in field

Get the length of a line in a character field.

Sbasic
    length = lineLEN(#bufferid, field, line)
    line : short[1]
Assembler
    LENS
    bufferid
    field
    short line
    return long length
C
    long DDlinelen(long bufferid, short field, long *result);
  
errors, code,   meaning
itnf    -7      invalid bufferid
                or field not present (i.e. field is clear)
                or line not present
ipar    -15     field doesn't exist
                or isn't a character field
orng    -4      line has to be >=0, but has to exist

NumbeR of LiNes in field

Get the number of lines in a character field.

Sbasic
    number = NRlines(#bufferid, field)
Assembler
    NRLN
    bufferid
    field
    return long number of lines
C
    long DDnrlines(long bufferid, short field, long *result);
  
errors, code,   meaning
itnf    -7      invalid bufferid
                or field not present (i.e. field is clear)
ipar    -15     field doesn't exist
                or isn't a character field

Extracting data

This is probably the most important part of the DATAdesign engine. These are the commands you need to examine the contents of a record. Of course you have to be able to find out what information is contained in your file, and here is the way to do so.

Get FieLD

Get the contents of an entire field at once. This is also the only way you can get the contents of a 'raw' field.

If the field is not found (that is cleared or invalid), then zero is returned as length.

The pointer to the place where the contents of the field has to be filled in doesn't have to be even. You have to indicate the size of the buffer as it is used to prevent a buffer overflow. If the buffer is not long enough, then it will be filled and the length of the buffer will be returned.

Sbasic
    length = GETfield (#bufferid, field, length, place)
    length : short
    place : long, ptr to buffer
Assembler
    GFLD
    bufferid
    field
    long length of buffer
    pointer to buffer
    return long length of field
C
    long DDgetfield(long bufferid, short field, long length,
                    char *buffer, long *return);

errors, code,   meaning
itnf     -7     invalid bufferid
                field not found (cleared or invalid)
bffl     -5     buffer full

Get CHaRacter

Get a character from a character field.

Sbasic
    char$ = GETchar$(#bufferid, field, element)
    element : short[1]
Assembler
    GCHR
    bufferid
    field
    long element
    return char
C
    long DDgetchar(long bufferid, short field,
                   long element, char *return);

errors, code,   meaning
itnf    -7      invalid bufferid
                or field not present in this record
ipar    -15     invalid fieldid
                or field has wrong type
orng    -4      element has to be >=1, but may not exist

Get SHoRt

Get a short from a field of shorts.

Sbasic
    value = GETshort (#bufferid, field, element)
    element : short[1]
Assembler
    GSHR
    bufferid
    field
    long element
    return short
C
    long DDgetshort(long bufferid, short field,
                    long element, short *return);

errors, code,   meaning
itnf    -7      invalid bufferid
                or field not present in this record
ipar    -15     invalid fieldid
                or field has wrong type
orng    -4      element has to be >=1, but may not exist

Get LoNG

Get a long from a field of longs.

Sbasic
    value = GETlong (#bufferid, field, element)
    element : short[1]
Assembler
    GLNG
    bufferid
    field
    long element
    return long
C
    long DDgetlong(long bufferid, short field,
                   long element, long *return);

errors, code,   meaning
itnf    -7      invalid bufferid
                or field not present in this record
ipar    -15     invalid fieldid
                or field has wrong type
orng    -4      element has to be >=1, but may not exist

Get DouBLe

Get a double from a field of ieee doubles.

Sbasic
    value = GETfloat (#bufferid, field, element)
    element : short[1]
  or if you want to get the value as an ieee double :
    GETdouble #bufferid, field, element, place
    element : short[1]
    place : long pointer to 8 byte space to fill in double
Assembler
    GDBL
    bufferid
    field
    long element
    return ieee double
C
    long DDgetdouble(long bufferid, short field,
                     long element, double *return);

errors, code,   meaning
itnf    -7      invalid bufferid
                or field not present in this record
ipar    -15     invalid fieldid
                or field has wrong type
orng    -4      element has to be >=1, but may not exist

Get STRing

Get a line from a character field.

Sbasic
    line$= GETline$(#bufferid, field, line)
    line : short[1]
Assembler
    GSTR
    bufferid
    field
    long line
    return string
C
    long DDgetline(long bufferid, short field, long line,
                   char *return, short space);
    space : the space which is available for the string

errors, code,   meaning
itnf    -7      invalid bufferid
                or field not present in this record
ipar    -15     invalid fieldid
                or field has wrong type
orng    -4      line has to be >=1, but may not exist
bffl    -5      buffer full (line is longer than return string can contain,
                the return buffer will be filled)

Setting data

Set FieLD

Set the contents of an entire field. The type of the field is not considered. This is the only way you can set the contents of a 'raw' field.

Sbasic
    SETfield #bufferid, field, length, place
    length : short
    place : long, ptr to buffer
Assembler
    SFLD
    bufferid
    field
    long length of data in buffer (in bytes)
    pointer to buffer
C
    long DDsetfield(long bufferid, short field, long length, char *buffer);

errors, code,   meaning
itnf    -7      invalid bufferid
ipar    -15     invalid fieldid
imem    -3      insufficient memory
rdo     -20     read only buffer

Set CHaRacter

Set a character in a character field. If the field was not present, it will be created. If the element already existed, it will be overwritten. If there were fewer elements in the field, then new spaces will be created as filling.

Sbasic
    SETchar #bufferid, char$, field, element
    char$ : character
    element : short[1]
Assembler
    SCHR
    bufferid
    field
    char value
    long element
C
    long DDsetchar(long bufferid, short field, long line, char value);

errors, code,   meaning
itnf    -7      invalid bufferid
ipar    -15     invalid fieldid
                or field has wrong type
orng    -4      element has to be >=1
imem    -3      insufficient memory
rdo     -20     read only buffer

Set SHoRt

Set a short in a field of shorts. If the field was not present, it will be created. If the element already existed, it will be overwritten. If there were fewer elements in the field, then new zero elements will be created as filling.

Sbasic
    SETshort #bufferid, value, field, element
    value : short
    element : short[1]
Assembler
    SSHR
    bufferid
    field
    short value
    long element
C
    long DDsetshort(long bufferid, short field, long line, short value);

errors, code,   meaning
itnf    -7      invalid bufferid
ipar    -15     invalid fieldid
                or field has wrong type
orng    -4      element has to be >=1
imem    -3      insufficient memory
rdo     -20     read only buffer

Set LoNG

Set a long in a field of long. If the field was not present, it will be created. If the element already existed, it will be overwritten. If there were fewer elements in the field, then new zero elements will be created as filling.

Sbasic
    SETlong #bufferid, value, field, element
    value : long
    element : short[1]
Assembler
    SLNG
    bufferid
    field
    long value
    long element
C
    long DDsetlong(long bufferid, short field, long line, long value);

errors, code,   meaning
itnf    -7      invalid bufferid
ipar    -15     invalid fieldid
                or field has wrong type
orng    -4      element has to be >=1
imem    -3      insufficient memory
rdo     -20     read only buffer

Set DouBLe

Set a double in a field of doubles. If the field was not present, it will be created. If the element already existed, it will be overwritten. If there were fewer elements in the field, then new zero elements will be created as filling.

Sbasic
    SETfloat #bufferid, value, field, element
    value : float
    element : short[1]
    or if you want to set the value as an ieee double :
    SETdouble #bufferid, place, field, element
    place : long, pointer to 8 bytes where the double can be found
    element : short[1]
Assembler
    SDBL
    bufferid
    field
    double value
    long element
C
    long DDsetdouble(long bufferid, short field, long line, double value);

errors, code,   meaning
itnf    -7      invalid bufferid
ipar    -15     invalid fieldid
                or field has wrong type
orng    -4      element has to be >=1
imem    -3      insufficient memory
rdo     -20     read only buffer

Set STRing

Set a line in a character field.
If the field field was not present it will be created.
If the line already existed it is overwritten.
If there were fewer lines in the field, then some empty lines will be created for filling.

Sbasic
    SETline #bufferid, line$, field, line
    line$ : string
    line : short[1]
Assembler
    SSTR
    bufferid
    field
    string line to fill in
    long line
C
    long DDsetline(long bufferid, short field, long line, char *string);

errors, code,   meaning
itnf    -7      invalid bufferid
ipar    -15     invalid fieldid
                or field has wrong type
orng    -4      line has to be >=1
imem    -3      insufficient memory
rdo     -20     read only buffer

Changing

As you may have noticed, you can think of a field as an array of a certain type. This array can grow or shrink without limitation (except memory of course). However, it may be necessary to remove a part of this array, or insert a part, and this either at the end, or somewhere in the middle of this array.

INSert Elements

This command allows you to insert some array elements in a field. Inserted elements will be cleared to zero. The elements will be inserted before the element given as place.
Sbasic
    INSERTel #bufferid, field, place, number
    place : short[1]
    number : short[1]
Assembler
    INSE
    bufferid
    field
    short place
    short number
C
    long DDinsertel(long bufferid, short field, short place, short number);

errors, code,   meaning
itnf    -7      invalid bufferid
ipar    -15     field doesn't exist
                place has to be >=0
                number has to be >=0
imem    -3      insufficient memory
rdo     -20     read only buffer

ReMoVe Elements

This command allows you to remove some array elements from a field.

The first elements to be removed is given in place.

Sbasic
    REMOVEel #bufferid, field, place, number
    place : short[1]
    number : short[1]
Assembler
    RMVE
    bufferid
    field
    short place
    short number
C
    long DDremoveel(long bufferid, short field, short place, short number);
  
errors, code,   meaning
itnf    -7      invalid bufferid
ipar    -15     field doesn't exist
orng    -4      place has to be >=0
                number has to be >=0
imem    -3      insufficient memory
rdo     -20     read only buffer
PROGS, Professional & Graphical Software
last edited September 3, 1996