SBM AppScript Reference → Programming SBM AppScript → Application Objects → Object Types → AppRecord
AppRecord is the base object type for the majority of SBM objects. An AppRecord can represent any row of any table from the current SBM database. The table is specified by a numeric table ID which must be supplied when the AppRecord is created. Thus, AppRecord objects must be created using Ext.CreateAppRecord() and cannot be created with CreateObject(). For details on Ext.CreateAppRecord, refer to Ext.CreateAppRecord( tableId [, recType] ). For details on working with SBM database records, refer to Working with SBM Database Records.
After an AppRecord has been created for a specific table, its methods can retrieve data from any row of that table. However, the AppRecord can never be used with a different table; you must create a separate AppRecord object for that purpose.
When discussions of AppRecord objects refer to the "table ID of the current item," it means the table ID given when the AppRecord was created. AppRecord subtypes have hard-coded table IDs and can thus be created without supplying the table ID. For example, a User object is an AppRecord subtype that is always associated with the TS_USERS table. Thus, the table ID of any User object is the TS_ID associated with the TS_NAME of "Users" in the TS_TABLES table. The "Ext" object provides functions to look up table names and IDs.
AppRecord does not inherit from any object type.
Add(): This method adds a new row to a table. After creating an AppRecord from the desired table and setting any desired field values, use this method to add the record as a new row in its table. This is not for use with Primary tables, because those items must go through a Submit transition. However, it is possible to make a copy of a Primary table item using this method.
Input: N/A
Output: N/A
Return: Long Integer – The TS_ID of the record added, which is unique to this table. Zero means the record could not be added due to an error.
Example:
Dim myRecord, myLong, tableId REM Create a Contact record tableId = Ext.TableId("TS_CONTACTS") Set myRecord = Ext.CreateAppRecord (tableId) myRecord.SetName("First Middle LastName") myLong = myRecord.Add() If myLong = 0 Then Call Ext.LogErrorMsg("Error adding Contact.") End If
Delete(): On most tables, this method removes the record from the database. On tables such as States and Users, the records are marked as deleted but remain in the database.
Input: N/A
Output: N/A
Return: Boolean. True if the record is deleted from or marked as deleted in the database.
Example:
Dim myRecord, whereClause, tableId REM Create a Contact record tableId = Ext.TableId ("TS_CONTACTS") Set myRecord = Ext.CreateAppRecord(tableId) whereClause = "TS_CONTACTFIRSTNAME = 'Joe'" If myRecord.ReadWithWhere(whereClause) Then If Not myRecord.Delete() Then Call Ext.LogErrorMsg("Error Deleting Contact record.") End If End If
Fields(): AppRecords from an Auxiliary or Primary table have a variable field list. That is, their fields can be defined using SBM Composer. The Fields() method returns a VarFieldList object containing all such fields. For AppRecords from tables without a variable field list, this method returns the VBScript value Nothing. See the VarFieldList object for details on manipulating field data.
Input: N/A
Output: N/A
Return: VarFieldList – List of fields from this AppRecord.
GetDisplayName(): Every database table has a display name format. SBM Composer enables you to define display name formats for Primary and Auxiliary tables. For other tables, the display name is found in the TS_NAME column.
Input: N/A
Output: N/A
Return: String – This record's display name, formatted according to table settings.
GetFieldValue(name, value): Gets the value of any field. If the calling AppRecord is an item from a Primary or Auxiliary table, its variable field list is searched. Otherwise, the schema for its table is searched.
Input: name (String) – The name of the field whose value will be retrieved from the variable field list or system field list. System table field names must be entirely in lowercase characters or they will not be found. Field names for variable fields should be provided in uppercase characters for database column names or in lowercase or mixed case characters for display names (for Title, for example).
Output: value (String) – The field's value, converted to a String. The value is returned as it is stored in the database. For example, for selection fields, the return value is the database ID for the selection.
Return: Boolean – True if the named field was found successfully.
Example:
Dim myRecord, value, tableId, ok REM Create and retrieve Project record tableId = Ext.TableId ("TS_PROJECTS") Set myRecord = Ext.CreateAppRecord (tableId) ok = myRecord.Read("Image Builder") If ok <> 0 Then ok = myRecord.GetFieldValue( "parentid", value ) If ok <> 0 Then Call Ext.LogInfoMsg ("Parent ID of Image Builder is " & value) Else Call Ext.LogErrorMsg( "Unable to get Parent ID of " _ & "Image Builder project" ) End If
GetId(): Retrieves the current AppRecord's TS_ID. Note that TS_ID is uninitialized on a newly-created object. This method will only return a meaningful result if the calling object has been read from or written to the database.
Input: N/A
Output: N/A
Return: (Long Integer) – TS_ID of the calling AppRecord.
Example:
Dim myRecord, whereClause, ContactTSID, tableId REM Create a Contact record tableId = Ext.TableId ("TS_CONTACTS") Set myRecord = Ext.CreateAppRecord(tableId) whereClause = "TS_CONTACTFIRSTNAME like 'Joe'" If myRecord.ReadWithWhere(whereClause) Then REM Read the TS_ID of the record ContactTSID = myRecord.GetId() End If
GetName(): Gets the calling AppRecord's "name" system field. For more details on the "name" system field, refer to Working with SBM Database Records.
Input: N/A
Output: N/A
Return: (String) – A text string from the associated Name field.
Example:
Dim myRecord, whereClause, name, tableId REM Create a Contact record tableId = Ext.TableId ("TS_CONTACTS") Set myRecord = Ext.CreateAppRecord(tableId) whereClause = "TS_CONTACTFIRSTNAME like 'Joe'" If myRecord.ReadWithWhere(whereClause) Then REM On the contact record, this will return back REM the contact's full name name = myRecord.GetName() End If
GetRecTableId(): Returns the calling AppRecord's table ID.
Input: N/A
Output: N/A
Return: (Long Integer) – The calling AppRecord's table ID.
Example:
Dim myRecord, tableId, result tableId = Ext.TableId ("TS_CONTACTS") Set myRecord = Ext.CreateAppRecord(tableId) result = myRecord.GetRecTableId() If result <> tableId Then Call Ext.LogInfoMsg("Error was expecting 'Contacts' to be table " _ & tableId) End If
HasVariableDBFields(): Tests whether the calling AppRecord is from a table with variable fields.
Input: N/A
Output: N/A
Return: (Boolean) – True if the calling AppRecord's table has variable fields.
IsFieldEqual( fieldNameOrId, value ): Tests for equivalence between the specified field and a value formatted as a string.
Input: fieldNameOrId (string or integer) – If a non-numeric string, the name of the field to be tested. Otherwise, it is converted to a number and taken as the TS_ID of the field to be tested.
Input: value (string) – The value to be compared to. The field's value will be formatted as a string and compared to this value.
Output: N/A
Return: (Long Integer) – Zero if the field value does not match, otherwise non-zero.
IsLocked(): Tests whether the calling AppRecord has been locked, meaning it is in use by another user. This means IsLocked() should return True if another user is using the item. If the item is locked by the current user who is calling IsLocked(), the return is False, which indicates that no one else can prevent an update to the item that was just locked.
Input: (Boolean) – Without an input parameter ( or with "False" as the input ), IsLocked() means "Does someone else have this record locked?" With "True" as the input parameter (IsLocked(True)), the meaning is "May I (as the current user) update this record?"
Output: N/A
Return: (Boolean) – True if the record is locked by another user.
Lock( [stealLock] ): Locks the calling AppRecord, so other users will not attempt to update it.
Input: stealLock (Boolean) – Optional, defaults to False. If True, any existing lock on this record will be broken, and changes made by the former lock holder are lost.
Output: N/A
Return: (Boolean) – True if the record is successfully locked.
Read(recordIdOrName): Look up a row of this AppRecord's table. Depending on the parameter's type (numeric vs. string), a different type of lookup is performed.
Input: recordIdOrName (string or number) – If this is a number or string that VBScript can convert to a number, it is taken as the value to search for in the TS_ID column. All other parameter types are converted to a string and searched for in the "name" system field.
Output: N/A
Return: Boolean – True if the TS_ID or name was found, in which case the calling AppRecord object becomes a copy of that row in the table.
Example:
Dim myRecord, tableId REM Create a Contact record tableId = Ext.TableId ("TS_CONTACTS") Set myRecord = Ext.CreateAppRecord(tableId) If not myRecord.Read("Smith") Then Call Ext.LogErrorMsg("Error looking for Contact with " _ & "TS_CONTACTLASTNAME of 'Smith'") End If
ReadWithWhere(WhereClause): Used to find a record by passing in a string containing a SQL "where" clause, not including the keyword "where". All fields will start with "TS_" and normal SQL syntax will apply. The calling object will become a copy of the first record found. This is the most general way of finding particular AppRecords.
Input: whereClause ( String ) – The SQL "where" clause to find the specific record in the table, not including the keyword "where."
Output: N/A
Return: (Boolean) – True if the method found the record, in which case the calling object becomes a copy of the record found. If more than one record is found, the first one is copied to the calling object.
Example:
Dim myRecord, tableId, whereClause REM Create a Contact record tableId = Ext.TableId ("TS_CONTACTS") Set myRecord = Ext.CreateAppRecord(tableId) whereClause = "TS_CONTACTFIRSTNAME like 'Joe'" If Not myRecord.ReadWithWhere(whereClause) Then Call Ext.LogErrorMsg("Error finding contact with " _ & "first name equal to 'Joe'") End If
SetFieldValue( name, value ): Sets the value of any field. If AppRecord is calling an item from a Primary or Auxiliary table, its field in its variable field list is set. Otherwise, the schema for its table is set. System table field names must be entirely in lowercase characters or they will not be found. Field names for variable fields should be provided in uppercase characters for database column names or in lowercase or mixed case characters for display names (Title, for example).
Input: name (String) – The name of the field whose value will be set in the variable field list or system table field list.
Input: value (String or Number) – The new value for the field. The value must be specified as it is stored in the database. For example, for selection fields, the value must be the database ID for the selection.
"00:00:" & elapsedTimeSBM converts the seconds into the correct hours, minutes, and seconds for you.
Return: Boolean – True if the field value was successfully set.
SetName(newName): Sets the "name" value of the calling object. For system tables, this is the "TS_NAME" column. For Primary and Auxiliary tables, this is the column corresponding to the "name" system field. For more details on the "name" system field, refer to Working with SBM Database Records.
Input: newName (String) – Text to be used as the new name field.
Output: N/A
Return: N/A
Example:
Option Explicit Dim myRecord, whereClause, bOk REM Create a Contact record Set myRecord = Ext.CreateAppRecord( Ext.TableId ( "TS_CONTACTS" )) whereClause = "TS_CONTACTFIRSTNAME like 'Joe'" bOk = myRecord.ReadWithWhere( whereClause ) If bOk = True Then REM Set the last name of the contact to Pepperbrooke Call myRecord.SetName( "Pepperbrooke" ) REM Commit change to database Call myRecord.UpdateWithLock( True ) End If
Unlock( [currentUserOnly] ): Unlocks the calling AppRecord, signaling that it is available for other users.
Input: currentUserOnly (Boolean) – Optional, defaults to False. If True, only the current user's locks are unlocked. If False, any user's locks on this record are removed.
Output: N/A
Return: (Boolean) – True if the record was successfully unlocked or was not locked to begin with.
Update(): This method replicates the functionality of the system Update transition. The values of all fields in the calling AppRecord are written to the database. Any fields that the current user has privileges to update may be modified and the Update method commits them to the database. This method modifies an existing record, based on the TS_ID of the calling AppRecord. To add a new record, see the Add() method.
Input: N/A
Output : N/A
Return: (Boolean) – True if the record is updated in the database. The same cache rules apply as in Add().
Example:
Dim myRecord, tableId, whereClause REM Create a Contact record tableId = Ext.TableId ("TS_CONTACTS") Set myRecord = Ext.CreateAppRecord(tableId) whereClause = "TS_CONTACTFIRSTNAME like 'Joe'" If myRecord.ReadWithWhere(whereClause) Then myRecord.SetName("Smithy") If Not myRecord.Update() Then Call Ext.LogErrorMsg("Error updating Contact record.") End If End If
UpdateWithLock( [stealLock] ): Updates the record that has been previously locked with Lock() function.
Input: stealLock (Boolean) – Optional parameter that allows the user to skip the Lock function and steal the lock during the update. Defaults to False. If True, any other user's existing locks will be broken, causing that user's changes to be lost.
Output: N/A
Return: (Boolean) – True if the record was successfully updated.
Copyright © 2007–2015 Serena Software, Inc. All rights reserved.