JavaScript method: SCFile.setFields()

This method causes any subsequent doSelect() calls to fetch only the specified fields. If setFields has not been called on a table, all fields are selected and a “SELECT *” is performed.

This method is supported for read-only objects. You can make an object read-only specifying the SCFILE_READONLY argument in the SCFile constructor.

Calling setFields with no parameters will reset any previously specified fields. Any subsequent calls to doSelect() will fetch all fields (a SELECT * will be performed).

Syntax

SCFile_object.setFields( field-array );

SCFile_object.setFields( field-string );

SCFile_object.setFields( );

Arguments

The following arguments are valid for this method:

Argument	Data type	Description
field-array	Array	A javascript array of field name strings; for example, setFields(new Array(“contact.name”, “user.id”)).
field-string	String	A string of space-separated field names; for example, setFields(“contact.name user.id”).

Return values

The method returns RC_SUCCESS if successful and RC_ERROR on failure.

The following conditions cause a setFields failure:

• Calling setFields on an uninitialized SCFile or a non read-only SCFile
• Calling setFields with an invalid argument type (not a string or an array of strings)
• Calling setFields with one (or more) invalid fields. (The method performs a basic validation on the field names to ensure they exist in the DBDICT.)

When the method fails, it has no effect, and the last successful call to setFields stays in effect. It issues a warning in the sm.log file.

Limitations

• The main unique key fields of the dbdict are always selected from the table (and for join tables, from each underlying table) even if not explicitly specified in setFields.

• Since only basic field validation is performed in the setFields method, there are certain situations when the call can be successful (returns RC_SUCCESS) but a “SELECT *” is still performed.

  This would be the case if:

  • All specified fields exist in the DBDICT but at least one field is an alias field, a structure name or an unmapped field (which are unsupported).
  • LDAP is the primary data source for the table. (LDAP mapped fields are supported as long as LDAP is not the primary data source.)

Example usage

This example does the following:

• Takes the prefix of a contact name and returns a list of contacts that start with the specified prefix.
• On failure, returns the message "Could not find contact."

This example requires the following sample data:

• a contacts table with some records

function findPrefix( prefix )
{
   var contactList = new SCFile( "contacts", SCFILE_READONLY ); //added new parameter SCFILE_READONLY
   var fields = new Array("contact.name", "user.id"); // build array of fields to be returned from DB
   var rc = contactList.setFields( fields ); // call new setFields method to identify fields to query from DB
   
   if ( rc != RC_SUCCESS )
   {
      print( "setFields() failed, will revert to SELECT * (see log for more info)" );
      return null;
   }
 
   var findContact = contactList.doSelect( "contact.name # \"" + prefix + "\"" );
   if ( findContact == RC_SUCCESS )
   {
      return contactList;
   }
   else
   {
      print( "Could not find contact. " + RCtoString( findContact ) );
      return null;
   }
}