VarRecord

Description

A VarRecord is any record that has variable fields. In other words, it represents any primary or auxiliary item. The item's fields are not defined by the database schema. They are configured dynamically by the SBM administrator. VarRecord objects require a table ID at creation, so they cannot be created with CreateObject(). Use Ext.CreateVarRecord().

Inheritance

AppRecord->VarRecord

Methods

• GetDisplayIssueId(): Returns the item's display ID, consisting of a prefix indicating the item's type and a serial number within the item's project. Item types and their prefixes are defined when an SBM designer configures a workflow. See GetItemNumber() and GetItemPrefix() for the components of the display ID.

  Input: N/A

  Output: N/A

  Return: (String) – The item's display ID.

• GetFieldValue(name, value [, fieldList [, field] ]): Gets the value of a field in the calling record's variable field list. The "fieldList" and "field" parameters are optional. If supplied, they can boost efficiency for repeated calls to GetFieldValue() and SetFieldValue(). Note that fields not contained in a variable field list (i.e., system table fields) cannot be accessed with this method.

  Input: name (String) – The name of the field whose value will be retrieved from the calling record's variable field list.

  Output: value (String) – The internal value for the field. For Text fields, this is the exact value entered in the field.

  Note: If the field is a Multi-User field for which the Groups and Users selection mode is enabled, the value can include both pure integers (TS_IDs from the TS_USERS table) and group identifiers (TS_IDs from the TS_GROUPS table). The latter are in the form G1, G2, …

  Input/Output: fieldList (VarFieldList) – Optional. If supplied and equal to the global constant Nothing, this parameter will refer to the calling record's VarFieldList when this method returns. If supplied and not equal to Nothing, this parameter is taken to be the calling record's VarFieldList. Do not set this parameter's value yourself. Always pass a variable set to Nothing and then reuse the variable for subsequent calls to GetFieldValue() and SetFieldValue() on the same VarRecord object. If this parameter is omitted, no functionality changes, but efficiency may suffer.

  Input/Output: field (Field) – Optional. If supplied and equal to the global constant Nothing, this parameter will refer to the Field object on the calling record's VarFieldList whose name matches the "name" input parameter when this method returns. If supplied and not equal to Nothing, this parameter is taken to be that Field object. As with the fieldList parameter, you should never set this value yourself. Always pass a variable equal to Nothing and reuse the variable in subsequent calls to GetFieldValue() and SetFieldValue() on the same VarRecord object and the same value for the "name" input parameter. Passing this parameter only affects the efficiency of repeated GetFieldValue() and SetFieldValue() calls.

  Return: Boolean. True if the named field was found in the calling record's VarFieldList and its value was successfully retrieved.

  Example:

  Dim myRecord, value, whereClause, tableId, ok, fieldList, field
  REM Create and retrieve Contact record
  tableId = Ext.TableId ("TS_CONTACTS")
  Set myRecord = Ext.CreateAppRecord (tableId)
  whereClause = "TS_CONTACTFIRSTNAME like 'Joe'"
  ok = myRecord.ReadWithWhere (whereClause)
  REM If no e-mail address, supply default value
  Set fieldList = Nothing
  Set field = Nothing
  If ok Then ok = myRecord.GetFieldValue ( _
    "EMAIL", value, fieldList, field)
  If ok And value = "" Then
      ok = myRecord.SetFieldValue ( _
        "EMAIL", "joe@company.com", fieldList, field)
  End If
  If Not ok Then Call Ext.LogErrorMsg ("Error in Joe's Email field")

  Note: A GetFieldValue method is also included in the SBM JavaScript Library.

• GetItemNumber(): Returns the numeric portion of the item's display ID. See GetDisplayIssueId() for entire display ID.

  Input: N/A

  Output: N/A

  Return: (long integer) – numeric portion of the item's display ID.

• GetItemPrefix(): Returns the prefix of the item's display ID, indicating the item's type. Item types and their prefixes are defined when an SBM designer configures a workflow. See GetDisplayIssueId() for entire display ID.

  Input: N/A

  Output: N/A

  Return: (String) – prefix of the item's display ID.

• GetStateId(): Identifies the calling record's state within a workflow.

  Input: N/A

  Output: N/A

  Return: (long integer) – TS_ID of the record's state within the item's workflow. If the record is not from a primary table, then it does not have a workflow and the return value is -1.

• SetFieldValue( name, value [, fieldList [, field] ]): This method is identical to GetFieldValue(), except the "value" parameter is for input, as follows:

  Input: value (String) – A value in internal database format to be written to the named field in the calling record's VarFieldList. Field names for variable fields should be provided in upper case for database column names (TITLE, for example) or in lower or mixed case for display names (Title, for example). For details on working with different types of database fields, refer to Working with SBM Database Fields.

  Note that if the field is a journal field, consider using the Field function AppendJournalText to add a single journal entry.

  Note: A SetFieldValue method is also included in the SBM JavaScript Library.