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 the ChaiScript "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 list by calling its Delete() method.

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

  Output: N/A

  Return: N/A

• 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 global constant 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:

  var prjList = Ext.CreateAppRecordList( Ext.TableId( "TS_PROJECTS" ));
  var readOK = prjList.Read();

• ReadWithWhere(whereClause, [, Vector<Pair> params] [, orderBy] [, templateRec] ) (On-premise only): 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: params ( Vector ) – Params is an optional Vector storing SQL bind parameters, where each entry is a Pair, where the first value is the parameter type and the second value is the value to bind to the SQL parameter.

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

  Input: templateRec

  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:

  /*ReadWithWhere with optional "params" parameter and using DBTypeConstants*/
  var userList = Variant();
  var item = Variant();
  var listRecord = Ext.CreateAppRecordList(Ext.TableId("UBG_ISSUES"));
  listRecord.ReadWithWhere("TS_ID between ? and ?", 
  [ Pair(DBTypeConstants.INTEGER,3), Pair(DBTypeConstants.INTEGER,20)], "TS_TITLE ASC" );
  for (item : listRecord) {
  	Ext.WriteStream("Item: " + item.GetName() + "");
  }

• Update (On-premise only): 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 ChaiScript For...Each statement. All AppRecordList subtypes inherit this iteration support.

• ReadByColumn( columnName, value ): Reads any record list type by a column value. "value" must be an integer type, a string type, or a float type. The database column will be expected to be of that same type, so a string with the value "1" will not work when reading an integer column. This can be worked around using the CInt, CStr, and CDbl functions. If the table is cached by Application Engine, the record may be read from the cache instead of the database.

• ReadByColumnAndColumn( columnName, value, column2Name, value2 ): Reads any record list type by two column values. The first column and value must be an integer type. The second column can be integer or string. The database column will be expected to be of that same type, so a string with the value "1" will not work when reading an integer column. This can be worked around using the CInt, CStr, and CDbl functions. If the table is cached by Application Engine, the record may be read from the cache instead of the database.