AppRecordList

Description

An AppRecordList contains a list of AppRecords of any subtype. The AppRecord objects on a single AppRecordList need not be from the same table or of the same AppRecord subtype, though homogeneous lists are easier to work with. The list can be iterated with VBScript's "For...Each" statement, and all subtypes of AppRecordList inherit this iteration support.

Inheritance

AppRecordList does not inherit from any object type.

Methods

• Count(): Returns the number of items in the list. Synonym for Length().

  Input: N/A

  Output: N/A

  Return: (long integer) – The number of items in the list.

• DeleteRecord( recordId ): Removes the specified record from the database by calling its Delete() method.

  Input: recordId (long integer) – The TS_ID of the record to delete from the database.

  Output: N/A

  Return: N/A (this method is a subroutine, not a function)

• FindRecord( recordIdOrName ): Find a specific record in the current list by matching its name or TS_ID.

  Input: recordIdOrName (string or long integer) – If this parameter is a non-numeric string, it is taken as the desired record's name. Otherwise, it is converted to a long integer and taken as the desired record's TS_ID.

  Output: N/A

  Return: The first AppRecord in the list that matches the given name or ID. If there is no match, it returns the VBScript value Nothing.

• Length(): Returns the number of items in the list. Synonym for Count().

  Input: N/A

  Output: N/A

  Return: (long integer) – The number of items in the list.

• Read(): Fills the AppRecordList from its table. For each row in the table, there will be an AppRecord object on the list. To select only certain records from the table, use ReadWithWhere().

  Input: N/A

  Output: N/A

  Return: (long integer) – Non-zero if successful, zero otherwise.

  Example:

  Dim prjList, readOK
  Set prjList = Ext.CreateAppRecordList( Ext.TableId( "TS_PROJECTS" ))
  readOK = prjList.Read()

• ReadWithWhere(whereClause, [orderByClause], [appRecord]): An alternative to Read(), this method uses SQL to select only certain records from the calling AppRecordList's table, rather than reading the entire table.

  Input: WhereClause (string) – A SQL "where clause" specifying the records to find. SBM will build a SQL string requesting all fields for the calling AppRecordList's table. The string contents of whereClause will appear after the word "where" in this SQL statement.

  Input: orderByClause ( String ) – Identifies a column in which the AppRecordList is ordered by. By default, the AppRecordList is ordered by the TS_ID column. To use the AppRecord parameter without the orderByClause parameter, use an empty string as a parameter for the orderByClause parameter.

  Input: appRecord ( AppRecord) – Identifies which fields are read into all AppRecords in the AppRecordList. Using this parameter may improve performance when using AppRecordOjbects which contain a VarFieldList from Primary or Auxiliary tables. To use this optional parameter, create a VarRecord against the Primary table you are doing your ReadWithWhere against. Get the VarFieldList of that VarRecord through the Fields() method. Call SelectAll, and pass it false to clear all fields. Then, explicitly turn on the fields you wish to see by finding the Field on the VarFieldList, then calling that Field's Select method and passing it true.

  Output: N/A

  Return: (long integer) – Non-zero if successful, zero otherwise.

  Example:

  Dim incList, sqlWhere, readOK
  sqlWhere = "TS_TITLE like 'This is my Title'"
  Set incList = Ext.CreateAppRecordList( Ext.TableId(  "TTS_INCIDENTS" ))
  readOK = incList.ReadWithWhere( sqlWhere )

  Example of ReadWithWhere(WhereClause) [orderByClause], [appRecord] ):

  CONST ISSUES_TABLE = 1000
  Dim record
  Set record = Ext.CreateVarRecord( ISSUES_TABLE )
  Dim varFieldList
  Set varFieldList = record.Fields()
  varFieldList.SelectAll( False )
  Dim fieldActiveInactive
  Set fieldActiveInactive = varFieldList.FindField( "activeinactive" )
  fieldActiveInactive.Select( True )
  Dim fieldTitle
  Set fieldTitle = varFieldList.FindField( "title" )
  fieldTitle.Select( True )
  Dim issue, issueList, sWhere
  sWhere = Shell.Db.ColName( "id" ) & "> 10"
  Set issueList = Ext.CreateAppRecordList( ISSUES_TABLE )
  Call issueList.ReadWithWhere( sWhere, Shell.Db.ColName( _
    "title" ), record )

• Update: Perform a database update on all records in the list. The update is performed by calling the given records' Update() methods.

  Output: N/A

  Return: (long integer) – Non-zero if all applicable records are successfully updated, zero otherwise.

• Special: "For...Each" iteration support: Any AppRecordList can be iterated using the standard VBScript For...Each statement. All AppRecordList subtypes inherit this iteration support.