Get Value Routines
The following routines provide the ability to get the value of any object item. After you have successfully put data into an object item, you can begin retrieving data from the object.
OT GetArray version 1
OT GetArray(inObject; inTag; outArray)
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to set
→
outArray Array Array to receive the item’s contents
←
Discussion
OT GetArray gets an array value in inObject from the item referenced by inTag.
If the object is not a valid object handle, an error is generated, OK is set to zero, and outArray is cleared.
If no item in the object has the given tag, outArray is cleared. If the FailOnNoItem option is set, an error is generated and OK is set to zero.
If an item with the given tag exists and has a compatible type, the array’s contents are replaced.
If an item with the given tag exists and has any other type, an error is generated, OK is set to zero, and array is cleared.
Array Type Compatibility
Except for String and Text arrays, you must put and get arrays into the same type of array variable. String and Text arrays, however, may be mixed and matched, because ObjectTools stores both types of array with an item type of OT Character array (113).
Note If you retrieve into a fixed width String Array, the elements will be tnuncated to the width of the array.
See Also
OT GetArrayBoolean version 1
OT GetArrayBoolean(inObject; inTag; inIndex) Number
→
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to retrieve
→
inIndex Number Index of array element to retrieve
→
Function result Number The array element’s contents
←
Discussion
OT GetArrayBoolean gets a value in inObject from the array item referenced by inTag.
If the object is not a valid object handle, an error is generated, OK is set to zero, and zero is returned.
If no item in the object has the given tag, zero is returned. If the FailOnNoItem option is set, an error is generated and OK is set to zero.
If an item with the given tag exists and has the type Boolean array, and inIndex is in the range (0..OT SizeOfArray(inObject; inTag)), the value of the requested element is returned as a number (0=false, 1=true).
If an item with the given tag exists and has any other type, or if the index is out of range, an error is generated, OK is set to zero, and zero is returned.
See Also
OT GetArrayDate version 1
OT GetArrayDate(inObject; inTag; inIndex) Date
→
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to retrieve
→
inIndex Number Index of array element to retrieve
→
Function result Date The array element’s contents
←
Discussion
OT GetArrayDate gets a value in inObject from the array item referenced by inTag.
If the object is not a valid object handle, an error is generated, OK is set to zero, and a null date (!00/00/00!) is returned.
If no item in the object has the given tag, a null date is returned. If the FailOnNoItem option is set, an error is generated and OK is set to zero.
If an item with the given tag exists and has the type Date array, and inIndex is in the range (0..OT SizeOfArray(inObject; inTag)), the value of the requested element is returned.
If an item with the given tag exists and has any other type, or if the index is out of range, an error is generated, OK is set to zero, and a null date is returned.
See Also
OT PutArray , OT GetDate
OT GetArrayLong version 1
OT GetArrayLong(inObject; inTag; inIndex) Number
→
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to retrieve
→
inIndex Number Index of array element to retrieve
→
Function result Number The array element’s contents
←
Discussion
OT GetArrayLong gets a value in inObject from the array item referenced by inTag.
If the object is not a valid object handle, an error is generated, OK is set to zero, and zero is returned.
If no item in the object has the given tag, zero is returned. If the FailOnNoItem option is set, an error is generated and OK is set to zero.
If an item with the given tag exists and has the type Longint array, and inIndex is in the range (0..OT SizeOfArray(inObject; inTag)), the value of the requested element is returned.
If an item with the given tag exists and has any other type, or if the index is out of range, an error is generated, OK is set to zero, and zero is returned.
See Also
OT PutArray , OT GetLong
OT GetArrayPicture version 1
OT GetArrayPicture(inObject; inTag; inIndex) Picture
→
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to retrieve
→
inIndex Number Index of array element to retrieve
→
Function result Picture The array element’s contents
←
Discussion
OT GetArrayPicture gets a value in inObject from the array item referenced by inTag.
If the object is not a valid object handle, an error is generated, OK is set to zero, and an empty picture is returned.
If no item in the object has the given tag, an empty picture is returned. If the FailOnNoItem option is set, an error is generated and OK is set to zero.
If an item with the given tag exists and has the type Picture array, and inIndex is in the range (0..OT SizeOfArray(inObject; inTag)), the value of the requested element is returned.
If an item with the given tag exists and has any other type, or if the index is out of range, an error is generated, OK is set to zero, and an empty picture is returned.
See Also
OT GetArrayPointer version 1
OT GetArrayPointer(inObject; inTag; inIndex; outPointer)
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to retrieve
→
inIndex Number Index of array element to retrieve
→
outPointer Pointer Receives the array element’s
← contents
Discussion
OT GetArrayPointer gets a value in inObject from the array item referenced by inTag.
If the object is not a valid object handle, an error is generated, OK is set to zero, and a nil pointer is returned.
If no item in the object has the given tag, a nil pointer is returned. If the FailOnNoItem option is set, an error is generated and OK is set to zero.
If an item with the given tag exists and has the type Pointer array, and inIndex is in the range (0..OT SizeOfArray(inObject; inTag)), the value of the requested element is returned.
If an item with the given tag exists and has any other type, or if the index is out of range, an error is generated, OK is set to zero, and a nil pointer is returned.
Warning Under no circumstances should you attempt to store a pointer to a local or process variable in a compiled database and then try to retrieve that pointer in another process.
See Also
OT GetArrayReal version 1
OT GetArrayReal(inObject; inTag; inIndex) Number
→
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to retrieve
→
inIndex Number Index of array element to retrieve
→
Function result Number The array element’s contents
←
Discussion
OT GetArrayReal gets a value in inObject from the array item referenced by inTag.
If the object is not a valid object handle, an error is generated, OK is set to zero, and zero is returned.
If no item in the object has the given tag, zero is returned. If the FailOnNoItem option is set, an error is generated and OK is set to zero.
If an item with the given tag exists and has the type Real array, and inIndex is in the range (0..OT SizeOfArray(inObject; inTag)), the value of the requested element is returned.
If an item with the given tag exists and has any other type, or if the index is out of range, an error is generated, OK is set to zero, and zero is returned.
See Also
OT GetArrayString version 1
OT GetArrayString(inObject; inTag; inIndex) String
→
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to retrieve
→
inIndex Number Index of array element to retrieve
→
Function result String The array element’s contents
←
Discussion
OT GetArrayString gets a value in inObject from the array item referenced by inTag.
If the object is not a valid object handle, an error is generated, OK is set to zero, and an empty string is returned.
If no item in the object has the given tag, an empty string is returned. If the FailOnNoItem option is set, an error is generated and OK is set to zero.
If an item with the given tag exists and has the type OT Character array, and inIndex is in the range (0..OT SizeOfArray(inObject; inTag)), the value of the requested element is returned.
If an item with the given tag exists and has any other type, or if the index is out of range, an error is generated, OK is set to zero, and an empty string is returned.
See “The Character Item Type” on page 11 for more information on storing and retrieving strings.
Note If the result of this method is assigned to a fixed width String variable,
the item’s contents will be truncated to the width of the variable. To retrieve
more than 255 characters from a Character Array, use OT GetArrayText and
assign to a Text variable or field.
See Also
OT PutArray , OT GetArrayText
OT GetArrayText version 1
OT GetArrayText(inObject; inTag; inIndex) Text
→
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to retrieve
→
inIndex Number Index of array element to retrieve
→
Function result Text The array element’s contents
←
Discussion
OT GetArrayText gets a value in inObject from the array item referenced by inTag.
If the object is not a valid object handle, an error is generated, OK is set to zero, and an empty string is returned.
If no item in the object has the given tag, an empty string is returned. If the FailOnNoItem option is set, an error is generated and OK is set to zero.
If an item with the given tag exists and has the type OT Character array, and inIndex is in the range (0..OT SizeOfArray(inObject; inTag)), the value of the requested element is returned.
If an item with the given tag exists and has any other type, or if the index is out of range, an error is generated, OK is set to zero, and an empty string is returned.
See “The Character Item Type” on page 11 for more information on storing and retrieving text.
Note If the result of this method is assigned to a fixed width String variable,
the item’s contents will be truncated to the width of the variable. To retrieve
more than 255 characters from a Character Array, assign the result to a Text
variable or field.
See Also
OT PutArray , OT GetArrayString
OT GetBLOB version 1
OT GetBLOB(inObject; inTag; outBLOB)
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to retrieve
→
outBLOB BLOB The retrieved item
←
Discussion
OT GetBLOB gets a value in inObject from the item referenced by inTag.
If the object is not a valid object handle, an error is generated, OK is set to zero, and an empty BLOB is returned.
If no item in the object has the given tag, an empty BLOB is returned. If the FailOnNoItem option is set, an error is generated and OK is set to zero.
If an item with the given tag exists and has the type Is BLOB, outBLOB’s contents are replaced.
If an item with the given tag exists and has any other type, OK is set to zero, and an empty BLOB is returned.
Warning Do not attempt to pass a BLOB field or a dereferenced pointer to a BLOB field in the blob paremeter, as this will result in a crash. If you want to retrieve a BLOB item into a field, either use an intermediate local variable or assign the result of OT GetNewBLOB to the field. The same applies to passing a dereferenced pointer to a BLOB variable.
This command is being kept for backward compatibility. Because of the problems related to this command, it is recommended that you use OT GetNewBLOB instead, as this command may be removed in future versions.
See Also
OT PutBLOB , OT GetNewBLOB
OT GetDate version 1
OT GetDate(inObject; inTag) Date
→
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to retrieve
→
Function result Date The retrieved item
←
Discussion
OT GetDate gets a value in inObject from the item referenced by inTag.
If the object is not a valid object handle, an error is generated, OK is set to zero, and a null date (!00/00/00!) is returned.
If no item in the object has the given tag, a null date is returned. If the FailOnNoItem option is set, an error is generated and OK is set to zero.
If an item with the given tag exists and has the type Is Date, the value of the requested item is returned.
If an item with the given tag exists and has any other type, OK is set to zero, and a null date is returned.
See Also
OT GetLong version 1
OT GetLong(inObject; inTag) Longint
→
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to retrieve
→
Function result Longint The retrieved item
←
Discussion
OT GetLong gets a value in inObject from the item referenced by inTag.
If the object is not a valid object handle, an error is generated, OK is set to zero, and zero is returned.
If no item in the object has the given tag, zero is returned. If the FailOnNoItem option is set, an error is generated and OK is set to zero.
If an item with the given tag exists and has the type Is Longint, the value of the requested item is returned.
If an item with the given tag exists and has any other type, OK is set to zero, and zero is returned.
See Also
OT GetNewBLOB version 1.5
OT GetNewBLOB(inObject; inTag) BLOB
→
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to retrieve
→
Function result BLOB The retrieved item
←
Discussion
OT GetNewBLOB gets a value in inObject from the item referenced by inTag.
If the object is not a valid object handle, an error is generated, OK is set to zero, and an empty BLOB is returned.
If no item in the object has the given tag, an empty BLOB is returned. If the FailOnNoItem option is set, an error is generated and OK is set to zero.
If an item with the given tag exists and has the type Is BLOB, the value of the requested item is returned.
If an item with the given tag exists and has any other type, OK is set to zero, and an empty BLOB is returned.
Warning Because of the problems related to the OT GetBLOB command, it is recommended that you use this command instead.
See Also
OT GetObject version 1
OT GetObject(inObject; inTag) Longint
→
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to retrieve
→
Function result Longint A handle to a new object
←
Discussion
OT GetObject gets an object value in object from the item referenced by inTag. If this routine successfully returns a new object, the new object handle is added to the ObjectTools handle list.
If the object is not a valid object handle, an error is generated, OK is set to zero, and a null object handle (0) is returned.
If no item in the object has the given tag, a null object handle is returned.
If an item with the given tag exists and has the type OT Is Object (114), its contents are returned as a new object.
If an item with the given tag exists and has any other type, an error is generated, OK is set to zero, and a null object handle is returned.
Warning This method creates and returns a new object in memory. You are responsible for clearing it when you no longer need it by calling OT IsObject .
See Also
OT PutObject, OT IsObject
OT GetPicture version 1
OT GetPicture(inObject; inTag) Picture
→
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to retrieve
→
Function result Picture The retrieved item
←
Discussion
OT GetPicture gets a value in inObject from the item referenced by inTag.
If the object is not a valid object handle, an error is generated, OK is set to zero, and an empty picture is returned.
If no item in the object has the given tag, an empty picture is returned. If the FailOnNoItem option is set, an error is generated and OK is set to zero.
If an item with the given tag exists and has the type Is Picture, the value of the requested item is returned.
If an item with the given tag exists and has any other type, OK is set to zero, and an empty picture is returned.
See Also
OT PutPicture , OT GetArrayPicture
OT GetPointer version 1
OT GetPointer(inObject; inTag; outPointer)
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to retrieve
→
outPointer Pointer The retrieved item
←
Discussion
OT GetPointer gets a value in inObject from the item referenced by inTag.
If the object is not a valid object handle, an error is generated, OK is set to zero, and a nil pointer is returned.
If no item in the object has the given tag, a nil pointer is returned. If the FailOnNoItem option is set, an error is generated and OK is set to zero.
If an item with the given tag exists and has the type Is Pointer, the value of the requested element is returned.
If an item with the given tag exists and has any other type, OK is set to zero, and a nil pointer is returned.
Warning Under no circumstances should you attempt to store a pointer to a local or process variable in a compiled database and then try to retrieve that pointer in another process.
See Also
OT PutPointer , OT GetArrayPointer
OT GetReal version 1
OT GetReal(inObject; inTag) Number
→
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to retrieve
→
Function result Number The retrieved item
←
Discussion
OT GetReal gets a value in inObject from the item referenced by inTag.
If the object is not a valid object handle, an error is generated, OK is set to zero, and zero is returned.
If no item in the object has the given tag, zero is returned. If the FailOnNoItem option is set, an error is generated and OK is set to zero.
If an item with the given tag exists and has the type Is Real, the value of the requested item is returned.
If an item with the given tag exists and has any other type, OK is set to zero, and zero is returned.
See Also
OT GetRecord version 1.5
OT GetRecord(inObject; inTag)
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to retrieve
→
Discussion
OT GetRecord sets the current record of a table from the packed record data in the item referenced by inTag. The contents of the item must have been set with OT PutRecord. The table used to store the packed record is the table which will have its current record set.
If object is not a valid object handle, an error is generated and OK is set to zero.
If no item in object has the given tag, nothing happens.
If an item with the given tag exists and has the type OT Is Record, the current record of the item’s original table is set.
If there is no current record for the item’s table or the current record is locked, an error is generated and OK is set to zero.
Warning Once a record is stored with OT PutRecord, it must be retrieved into the same table. Otherwise the results are undefined (and potentially disastrous). You can use the OT GetRecordTable command to find the source table for a stored record.
See Also
OT PutRecord, OT GetRecordTable
OT GetRecordTable version 1.5
OT GetRecordTable(inObject; inTag) Number
→
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to retrieve
→
Function result Number The retrieved item’s table number
←
Discussion
OT GetRecordTable retrieves the table number from the packed record data in the item referenced by tag. The contents of the item must have been set with OT PutRecord. The table used to store the packed record is the table whose number will be returned.
If the object is not a valid object handle, or no item in object has the given tag, zero is returned, an error is generated and OK is set to zero.
If an item with the given tag exists and has the type OT Is Record, the number of the item’s original table is returned.
If an item with the given tag exists and has any other type, zero is returned, an error is generated and OK is set to zero.
See Also
OT GetString version 1
OT GetString(inObject; inTag) String
→
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to retrieve
→
Function result String The retrieved item
←
Discussion
OT GetString gets a value in inObject from the item referenced by inTag.
If the object is not a valid object handle, an error is generated, OK is set to zero, and an empty string is returned.