Xbase DBMS Chapter 13

#

Field Methods

Chapter Updated 2/1/99

This chapter lists the field methods and provides examples of how to use them.

### Xbase Field Method List

Method | Description
xbLong cnt FieldCount() | Returns the number of fields in the file
xbDouble d GetDoubleField(char * FieldName) | Returns a xbDouble field for field name
xbDouble d GetDoubleField(xbShort FieldNo) | Returns a xbDouble field for field number
xbShort rc GetField(xbShort,char *buf) | Gets field data from the record buffer
xbShort d GetFieldDecimal(xbShort FieldNo) | Gets field decimal count
xbShort len GetFieldLen(xbShort FieldNo) | Returns the length of a given field
char * name GetFieldName(xbShort FieldNo) | Returns field name for field number
xbShort FieldNo GetFieldNo(char * FieldName) | Returns the field ID number for a given field
char type GetFieldType(xbShort FieldNo) | Returns the type of a given field
xbFloat f GetFloatField(char * FieldName) | Returns a float field for field name
xbFloat f GetFloatField(xbShort FieldNo) | Returns a float field for field number
xbShort l GetLogicalField(xbShort FieldNo) | Returns logical field data
xbShort l GetLogicalField(char * FieldName) | Returns logical field data
xbLong l GetLongField(char * FieldName) | Returns a long field for field name
xbLong l GetLongField(xbShort FieldNo) | Returns a long field for field number
xbShort rc GetMemoField(xbShort FieldNo, xbLong len,char * buf) | Get memo field data
xbLong len GetMemoFieldLen(xbShort FieldNo) | Get memo field data length
xbShort s MemoFieldsPresent() | Determine if memo fields exist in DBF file
xbShort s MemoFieldExists(xbShort FieldNo) | Determine if a particular memo field has data
xbShort rc PutDoubleField(char * FieldName, xbDouble d) | Updates a xbDouble field for field name
xbShort rc PutDoubleField(xbShort FieldNo, xbDouble d) | Updates a xbDouble field for field number
xbShort rc PutField(xbShort FieldNo,char * val) | Fills or overlays a field in the current record buffer

### Xbase Field Method List (cont)

Method | Description
xbShort rc PutFloatField(char * FieldName, xbFloat f) | Updates a float field for field name
xbShort rc PutFloatField(xbShort FieldNo, xbFloat f) | Updates a float field for field number
xbShort rc PutLongField(char * FieldName, xbLong l) | Updates a long field for field name
xbShort rc PutLongField(xbShort FieldNo, xbLong l) | Updates a long field for field number
xbShort rc UpdateMemoData(xbShort FieldNo, xbLong len,char * buf, xbShort LockOpt) | Update memo field data
xbShort l ValidLogicalData( char * buf ) | Check for valid logical data
xbShort l ValidNumericData( char * buf ) | Check for valid numeric data

## Method Definitions

### Method xbLong xbDbf::FieldCount( void )

This method returns the number of fields which exist in the database.

#### Method Return Codes

If successful, this method returns the number of fields in the database.

#### Example Program:

See sample program sample3.cpp for an example of how to use this method.

### Method xbDouble xbDbf::GetxbDoubleField( char * FieldNo )

This method returns a xbDouble value for field FieldNo. Fieldno can be retrieved by using method GetFieldNo.

### Method xbDouble xbDbf::GetxbDoubleField( char * FieldName )

This method returns a xbDouble value for field FieldName. If multiple accesses for this particular field will be made from within the program, it is more efficient to access the data utlizing the field's number, rather than its name.

### Method xbShort xbDbf::GetField( xbShort FieldNo, char * buf )

This method fills an application program supplied buffer *buf with data from the record buffer for field number FieldNo. FieldNo can be retrieved by using method GetFieldNo.
It is the responsibility of the application program to verify the buffer is large enough to hold the data. No checking is done by method GetField to verify the buffer is large enough to hold the data.
If successful, this method returns the length of the field in bytes.

#### Example Program:

See sample program sample3.cpp for an example of how to use this method.

### Method xbShort xbDbf::GetFieldDecimal( xbShort FieldNo )

This method returns the decimal count of field FieldNo. FieldNo can be retrieved by using method GetFieldNo.
If successful, this method returns the decimal count.

### Method xbShort xbDbf::GetFieldLen( xbShort FieldNo )

This method returns the length of field FieldNo. FieldNo can be retrieved by using method GetFieldNo.
If successful, this method returns the length of the field in bytes.

#### Example Program:

See sample program sample3.cpp for an example of how to use this method.

### Method char * xbDbf::GetFieldName( xbShort FieldNo )

This method returns a pointer to the name of field FieldNo. FieldNo can be retrieved by using method GetFieldNo.
If successful, this method returns the field name.

#### Example Program:

See sample program dumpdbt.cpp for an example of how to use this method.

### Method xbShort xbDbf::GetFieldNo( char * FieldName )

This method is used to get a field's ID number based on paramater FieldName. Where FieldName is a valid name of a field in the database.

### Method Return Codes

Return Code | Description
-1 | Field not found in record
0 through n | The field number for field FieldName

#### Example Program:

See sample program sample2.cpp for an example of how to use this method.

### Method xbShort xbDbf::GetFieldType( xbShort FieldNo )

This method returns the type of field FieldNo. FieldNo can be retrieved by using method GetFieldNo.

#### Method Return Codes

If successful, this method returns the field type.
C = character
D = Date
L = Logical
M = Memo
N = Numeric
F = Float

#### Example Program:

See sample program sample3.cpp for an example of how to use this method.

### Method xbFloat xbDbf::GetFloatField( char * FieldName )

This method returns a float value for field FieldName. If multiple accesses for this particular field will be made from within the program, it is more efficient to access the data utlizing the field's number, rather than its name.

#### Example Program:

See sample program sample3.cpp for an example of how to use this method.

### Method xbFloat xbDbf::GetFloatField( xbShort * FieldNo )

This method returns a float value for field number FieldNo.

#### Example Program:

See sample program sample3.cpp for an example of how to use this method.

### Method xbShort xbDbf::GetLogicalField( xbShort FieldNo )

### Method xbShort xbDbf::GetLogicalField( char * FieldName )

This method returns -1 if field FieldName or FieldNo is not a logical field. It returns 1 if field FieldName is a 'T','t','Y' or 'y'. It returns 0 if not 'T','t','Y' or 'y'.

### Method xbLong xbDbf::GetLongField( xbShort * FieldNo )

### Method xbLong xbDbf::GetLongField( char * FieldName )

This method returns a long value for field FieldName. If multiple accesses for this particular field will be made from within the program, it is more efficient to access the data utlizing the field's number, rather than its name.

#### Example Program:

See sample program zipinit.cpp for an example of how to use this method.

### Method xbLong xbDbf::GetLongField( xbShort * FieldNo )

This method returns a long value for field FieldNo. FieldNo can be determined by utilizing method GetFieldNo.

#### Example Program:

See sample program zipinq.cpp for an example of how to use this method.

### Method xbShort xbDbf::GetMemoField( xbShort FieldNo, xbLong len, char * Buf, xbShort LockOption )

This method returns Len bytes of memo field FieldNo. Buf is a user supplied buffer large enough to contain the data. No checking of the field's size is performed by this method.
Lock Optionis one of:
F_SETLK - return immediately if lock fails
F_SETLKW - wait until lock function executes

### Method Return Codes

Return Code | Description
XB_INVALID_FIELDNO | An invalid field number was used
XB_NOT_MEMO_FIELD | Not a memo field
XB_NO_MEMO_DATA | No memo data exists
XB_INVALID_BLOCK_NO | Internal error, notify tech support
XB_SEEK_ERROR | Disk Error
XB_READ_ERROR | Disk Error
XB_NO_ERROR | No Error

#### Example Program:

See sample program dumpdbt.cpp for an example of how to use this method.

### Method xbLong xbDbf::GetMemoFieldLen( xbShort FieldNo )

This method returns the length of memo field FieldNo. FieldNo can be retrieved by using method GetFieldNo.
If successful, this method returns the length of the memo field in bytes.

#### Example Program:

See sample program dumpdbt.cpp for an example of how to use this method.

### Method xbShort xbDbf::MemoFieldExists( xbShort FieldNo )

This method returns true (1) if field FieldNo has any memo data. Otherwise it returns false (0).

### Method Return Codes

Return Code | Description
0 | Data file does not have any memo fields
1 | Data file has memo fields

#### Example Program:

See sample program dumpdbt.cpp for an example of how to use this method.

### Method xbShort xbDbf::MemoFieldsPresent( void )

This method returns true (1) if the file has any memo fields. Otherwise it returns false (0).

### Method Return Codes

Return Code | Description
0 | Data file does not have any memo fields
1 | Data file has memo fields

#### Example Program:

See sample program dumpdbt.cpp for an example of how to use this method.

### Method xbShort xbDbf::PutxbDoubleField( char * FieldName, xbDouble d )

This method puts a xbDouble value d for field FieldName. If multiple accesses for this particular field will be made from within the program, it is more efficient to access the data utlizing the field's number.

### Method Return Codes

Return Code | Description
XB_INVALID_FIELDNO | An invalid field number was used
XB_INVALID_DATA | Attempt to load invalid numeric or logical data

### Method xbShort xbDbf::PutxbDoubleField( xbShort FieldNo, xbDouble d )

This method puts a xbDouble value d for field FieldNo.

### Method Return Codes

Return Code | Description
XB_INVALID_FIELDNO | An invalid field number was used
XB_INVALID_DATA | Attempt to load invalid numeric or logical data

### Method xbShort xbDbf::PutField( xbShort FieldNo, char * buf )

This method fills field number FieldNo, with the data from buffer *buf.
It copies data from *buf until a 0x00 character is encountered or the buffer is filled. The field will be truncated if it is to long.
Use method GetFieldNo to determine the value for FieldNo.
If the field is type N or F, the field is loaded right justified, left blank filled onto the record buffer.
This method does check the validity of NUMERIC and LOGICAL data it is loading onto the record buffer. Ther can be no spaces or non-numeric data for numeric fields.

### Method Return Codes

Return Code | Description
XB_INVALID_FIELDNO | An invalid field number was used
XB_INVALID_DATA | Attempt to load invalid numeric or logical data

#### Example Program:

See sample program sample2.cpp for an example of how to use this method.

### Method xbShort xbDbf::PutFloatField( char * FieldName, FLOAT f )

This method puts a float value f for field FieldName. If multiple accesses for this particular field will be made from within the program, it is more efficient to access the data utlizing the field's number.

### Method Return Codes

Return Code | Description
XB_INVALID_FIELDNO | An invalid field number was used
XB_INVALID_DATA | Attempt to load invalid numeric or logical data

#### Example Program:

See sample program sample2.cpp for an example of how to use this method.

### Method xbShort xbDbf::PutFloatField( xbShort FieldNo, FLOAT f )

This method puts a float value f for field number FieldNo.

### Method Return Codes

Return Code | Description
XB_INVALID_FIELDNO | An invalid field number was used
XB_INVALID_DATA | Attempt to load invalid numeric or logical data

#### Example Program:

See sample program sample2.cpp for an example of how to use this method.

### Method xbLong xbDbf::PutLongField( char * FieldName, xbLong Val )

This method puts a long value Val for field FieldName. If multiple accesses for this particular field will be made from within the program, it is more efficient to access the data utlizing the field's number.

#### Example Program:

See sample program zipinit.cpp for an example of how to use this method.

### Method xbLong xbDbf::PutLongField( xbShort FieldNo, xbLong Val )

This method puts a long value Val for field FieldNo. FieldNo can be determined by utilizing method GetFieldNo.

#### Example Program:

See sample program zipinq.cpp for an example of how to use this method.

### Method xbShort xbDbf::UpdateMemoData( xbShort FieldNo, xbLong len, char * Buf, xbShort LockOption )

This method updates field FieldNo with Len bytes of data from Buf.
This is the only routine necessary to add, revise or delete memo field data. To delete a memo field, set the length to zero (0L).
LockOption is one of
- F_SETLK - return immediately if lock fails
- F_SETLKW - wait until lock function executes

  ### Method Return Codes

  Return Code | Description
  XB_LOCK_FAILED | Lock Failed
  XB_INVALID_BLOCK_NO | Internal error, notify tech support
  XB_SEEK_ERROR | Disk Error
  XB_READ_ERROR | Disk Error
  XB_WRITE_ERROR | Disk Error
  XB_NO_ERROR | No Error

  #### Example Program:

  See sample program sample2.cpp for an example of how to use this method.

  ### Method xbShort xbDbf::ValidLogicalData( char * data )

  This method returns true if data contains a valid logical data value. Otherwise, it returns false.

  ### Method Return Codes

  Return Code | Description
  1 | Valid logical data
  0 | Invalid logical data

  ### Method xbShort xbDbf::ValidNumericData( char * data )

  This method returns true if data contains a valid numeric data value. Otherwise, it returns false.

  ### Method Return Codes

  Return Code | Description
  1 | Valid numeric data
  0 | Invalid numeric data