Using Function Object In Script

When a user execute a menu option, the session will activate the function object linked to the menu option. You can handle the object using variant name of "instance" in scripts. Followings are properties and methods of the function object you can access.

instance.callFunction(String id)
Method to launch the internal function(function defined in spec file). All parameters that calling function hold will be exchanged to the function called. You can launch external function using method of session object.

instance.cancelWithMessage(String message)
Method to show a dialog with specified message to inform user of canceling the function. By this method the return parameter with ID of RETURN_MESSAGE is exchanged back.

instance.commit()
Method to commit pending transactions explicitly. Used in scripts of Script Launcher(XF000).

instance.setVariant(String id, Object value)
Method to set value to the instance variant specified by the ID. If it is already existing, the value will be updated.

instance.getVariant(String id)
Method to get value of the instance variant specified by the ID. If not found, blank will be returned.

instance.createTableOperator(String sql)
Method to get an object of Table Operator to execute a specific SQL command. Refer to following for methods.

instance.createTableOperator(String operation, String tableID)
Method to get an object of Table Operator for a specific table. Operations you can specify are Select, Count, Insert, Update and Delete. Notice that join tables are not read and scripts are not executed while operating table. Available methods of the object are as follow.

-TableOperator#setValueOf(String fieldID, Object value)
Method to declare field values for Update and Insert. You can do the same by addValue().
-TableOperator#addKeyValue(String fieldID, Object value)
Method to set Where criteria for Select, Count, Update, Insert and Delete. If you put value more than once, they work as AND conditions.
-TableOperator#addKeyValue(String prefix, String fieldID, Object value, String postfix)
Method to set Where criteria with 'and' & 'or' for Select, Count, Update, Insert and Delete. Refer to Example3&4.
TableOperator#addWhere(String text)
Method to set Where criteria with explicit text.
-TableOperator#setSelectFields(String text)
Method to set fields to be read for Select. Use field IDs and comma to separate them.
-TableOperator#setDistinctFields(String text)
Method to set distinct fields for Select. You can not use this method together with setSelectFields().
-TableOperator#setOrderBy(String text)
Method to set Order By for Select.
-TableOperator#setSqlText(String text)
Method to set SQL command. The value has to be consistent with the operation specified in createTableOperator().
-TableOperator#getSqlText()
Method to get SQL command that this object is being executed. Useful method to test script code.
-TableOperator#next()
Method to read the next row in the record set. If it has found the row it returns true.
-TableOperator#previous()
Method to read the previous row in the record set. If it has found the row it returns true.
-TableOperator#resetCursor()
Method to set cursor position before the first record.
-TableOperator#execute()
Method to execute table operation according to settings. It will returns count of rows processed. You do not have to use this method for Select as it is executed implicitly in the first next().
-TableOperator#getValueOf(String fieldID)
Method to get field value of a specific field for Select. If next() is not executed, it will returns null. Note that you need to use Number() to process numeric field(Refer to Example1&2).

Example1 Processing a numeric value in a single record fetched
var rTABLE000 = instance.createTableOperator('Select', 'TABLE000');
rTABLE000.setSelectFields('FIELD3');
rTABLE000.addKeyValue('FIELD1', value1);
rTABLE000.addKeyValue('FIELD2', value2);
if (rTABLE000.next()) {
   summary = summary + Number(rTABLE000.getValueOf('FIELD3'))
}

Example2 Processing a numeric value in multiple records selected
var rTABLE000 = instance.createTableOperator('Select', 'TABLE000');
rTABLE000.setSelectFields('FIELD3');
rTABLE000.addKeyValue('FIELD1', value1);
rTABLE000.setOrderBy('FIELD2, FIELD3');
while (rTABLE000.next()) {
   summary = summary + Number(rTABLE000.getValueOf('FIELD3'))
}

Example3 Counting records with criteria specified
var rTABLE000 = instance.createTableOperator('Count', 'TABLE000');
rTABLE000.addKeyValue('FIELD1 >', value1);
rTABLE000.addKeyValue('FIELD2 <', value1);
var count = rTABLE000.execute();
*With operand omitted it works as equal.

Example4 Selecting records with complicated criateria
var rTABLE000 = instance.createTableOperator('Select', 'TABLE000');
rTABLE000.addKeyValue('FIELD1 !=', '');
rTABLE000.addKeyValue('and ((', 'FIELD2 >', valueA, ') or');
rTABLE000.addKeyValue('(', 'FIELD2 =', valueA, ' and');
rTABLE000.addKeyValue('', 'FIELD3 >=', valueB, '))');
while (rFT100.next()) {
   summary = summary + Number(rFT100.getValueOf('FIELD4'))
}

Sample5 Checking key break in Select
var year = 0;
var rTABLE000 = instance.createTableOperator('Select', 'TABLE000');
rTABLE000.setSelectFields('YEAR, AMOUNT');
rTABLE000.setOrderBy('YEAR, MONTH');
while (rTABLE000.next()) {
   if (year != 0 && Number(rTABLE000.getValueOf('YEAR')) != year) {
      ...processing in key break of year...
   }
   year = rTABLE000.getValueOf('YEAR')
   ...processing each record...
}

Sample6 Inserting a new record
var cTABLE000 = instance.createTableOperator('Insert', 'TABLE000');
cTABLE000.addValue('FIELD1', value1);
cTABLE000.addValue('FIELD2', value2);
cTABLE000.addValue('FIELD3', value3);
var count = cTABLE000.execute();

Sample7 Updating an existing record
var uTABLE000 = instance.createTableOperator('Update', 'TABLE000');
uTABLE000.addValue('FIELD3', value3);
uTABLE000.addValue('FIELD4', value4);
uTABLE000.addValue('FIELD5', value5);
uTABLE000.addKeyValue('FIELD1', value1);
uTABLE000.addKeyValue('FIELD2', value2);
var count = uTABLE000.execute();

Sample8 Deleting existing records
var dTABLE000 = instance.createTableOperator('Delete', 'TABLE000');
dTABLE000.addKeyValue('FIELD1', value1);
dTABLE000.addKeyValue('FIELD2', value2);
var count = dTABLE000.execute();
*Note that this may select multiple records that eventually delete them.

instance.createTableEvaluator(String tableID)
Method to get an object of Table Evaluator for a specific table. Difference to Table Operator is that by using Table Evaluator you can get values of virtual fields and fields on join tables. Field objects are not identified by field ID but datasource ID(TableID_FieldID). Available methods of the object are as follow.

-TableEvaluator#setValueOf(String dataSourceID, Object value)
Method to declare field values for Update and Insert. You can do the same by addValue().
-TableEvaluator#addKeyValue(String fieldID, Object value)
Method to set Where criteria for selecting. If you put value more than once, they work as AND conditions.
-TableEvaluator#addKeyValue(String prefix, String fieldID, Object value, String postfix)
Method to set Where criteria with 'and' & 'or' for selecting.
-TableEvaluator#setOrderBy(String text)
Method to set Order By for selecting.
-TableEvaluator#select()
Method to select records according to creteria specified. It returns count of rows selected. Note that value of record is not read until you execute next().
-TableEvaluator#next()
Method to read the next row in the record set. If it has found the row it returns true. Note that select() will be executed implicitly when you execute next() first time after addKeyValue().
-TableEvaluator#insert(boolean isCheckOnly)
Method to execute inserting. It returns 1 if processing is succeeded. If isCheckOnly is true(false if value omitted), it only validates.
-TableEvaluator#update(boolean isCheckOnly)
Method to execute updating and return count of records processed. It has to be executed after values are ready to be updated by using method of next() and setValueOf()(Refet to Example3&4). If isCheckOnly is true(false if value omitted), it only validates.
-TableEvaluator#delete(boolean isCheckOnly)
Method to execute deleting and return count of records processed. If isCheckOnly is true(false if value omitted), it only validates.
-TableEvaluator#getValueOf(String dataSourceID)
Method to get value of a field specified by datasource ID(null will be returned if not found with ID). Equivalent to value property of field object.
-TableEvaluator#getFieldOf(String dataSourceID)
Method to get a field object(null will be returned if not found with ID). Available properties are dataSourceID, dataSourceID, tableID, fieldID, name, value, oldValue, valueChanged, color, enabled, editable, valueList, and error.
-TableEvaluator#getFieldCount()
Method to get count of fields(including virtual field and join field). It is used in for statement to getFieldAt(index).
-TableEvaluator#getFieldAt(int index)
Method to get a field object at the index(null will be returned if not found with the index).
-TableEvaluator#clear()
Method to set clear value of all fields and When conditions and dataset selected.
-TableEvaluator#getTableName()
Method to get table name.

Sample1 Putting field values selected in arrays
eTABLE000 = instance.createTableEvaluator('TABLE000');
eTABLE000.addKeyValue('FIELD1', value1);
eTABLE000.addKeyValue('FIELD2', value2);
eTABLE000.setOrderBy('FIELD3 DESC, FIELD4');
eTABLE000.select();
while (eTABLE000.next()) {
   valueArray[i] = eTABLE000.getValueOf('TABLE000_FIELD5');
   i++;
}

Sample2 Insert a record to the table and setup message
eTABLE000 = instance.createTableEvaluator('TABLE000');
eTABLE000.setValueOf('TABLE000_FIELD1', value1);
eTABLE000.setValueOf('TABLE000_FIELD2', value2);
eTABLE000.setValueOf('TABLE000_FIELD3', value3);
var count = eTABLE000.insert();
if (count == 1) {
   message = 'Inserted successfully.';
} else {
   message = 'Insertinf failed: ';
   while (var i=0; i < eTABLE000.fieldCount; i++) {
      field = eTABLE000.getFieldAt(i);
      if (field.error != '') {
         message = message + ';' + field.error;
      }
   }
}
instance.commit();

Sample3 Updating a record and setup message.
eTABLE000 = instance.createTableEvaluator('TABLE000'); // PK:KEY1
eTABLE000.addKeyValue('KEY1', key1);
if (eTABLE000.next()) {
   eTABLE000.setValueOf('TABLE000_FIELD1', value1);
   eTABLE000.setValueOf('TABLE000_FIELD2', value2);
   eTABLE000.setValueOf('TABLE000_FIELD3', value3);
   count = eTABLE000.update();
   if (count == 1) {
      message = 'Updated successfully.';
   } else {
      message = 'Updating failed: ';
      for (var i=0; i < eTABLE000.fieldCount; i++) {
         field = eTABLE000.getFieldAt(i);
         if (field.error != '') {
            message = message + '\n' + field.name + ':' + field.error;
         }
      }
   }
} else {
  message = 'The record not found.';
}
showMessage(keyValues + ':' + message);
instance.commit();

Example4 Updating multiple rows with message
eTABLE010 = instance.createTableEvaluator('TABLE010'); // PK:KEY1+KEY2
eTABLE010.addKeyValue('KEY1', key1);
while (eTABLE010.next()) {
   eTABLE010.setValueOf('TABLE010_FIELD1', value1);
   eTABLE010.setValueOf('TABLE010_FIELD2', value2);
   eTABLE010.setValueOf('TABLE010_FIELD3', value3);
   count = eTABLE010.update();
   if (count == 1) {
      message = 'Updated successfully';
   } else {
      message = 'Updating failed: ';
      for (var i=0; i < eTABLE010.fieldCount; i++) {
         field = eTABLE010.getFieldAt(i);
         if (field.error != '') {
            message = message + '\n' + field.name + ':' + field.error;
         }
      }
   }
  keyValues = eTABLE010.getValueOf('TABLE010_KEY1') + '+' + eTABLE010.getValueOf('TABLE010_KEY2');
  showMessage(keyValues + ':' + message);
}
instance.commit();

Example5 Deleting to setup messages
eTABLE000 = instance.createTableEvaluator('TABLE000'); PK:KEY1
eTABLE000.addKeyValue('KEY1', key1);
if (eTABLE000.next()) {
   count = eTABLE000.delete();
   if (count == 1) {
      message = 'Deleted successfully.';
   } else {
      message = 'Deleting failed: ';
      for (var i=0; i < eTABLE000.fieldCount; i++) {
         field = eTABLE000.getFieldAt(i);
         if (field.error != '') {
            message = message + '\n' + field.name + ':' + field.error;
         }
      }
   }
}
instance.commit();
showMessage(message);


instance.executeScript(String text)
Method to run specified text as a script.

instance.functionID
Property of the function expressing its ID

instance.getFieldObjectByID(String tableID, String fieldID)
Method to get field object which have properties like value and color. Normally you can access field objects by scripting like "AT010_NRITEM.value". Refer to Table Script for details.

instance.parmMap
Property of exchanging parameter of the function. As it is a HashMap<String, Object> object, use instance.parmMap.get(Key) to get a value, and use instance.parmMap.put(Key, Value) to register a value. It contains values with keys as follow.

-Field ID
Value of processing key for primary table or header table.
-Datasouce ID
Value of field on processing tables(including join tables). Used as criteria parameters of Inquire List or Update List.
-'INITIAL_MESSAGE'
Value of message shown on the form when the function activated
-'INSTANCE_MODE'
Value of mode for the function of Single Update. Specify value INQ, EDIT, or ADD to specify mode explicitly.

instance.returnMap
Return parameter in type of HashMap<String, Object> exchanged by functions. Get parameter value by using method of instance.returnMap.get(KeyValue) and register parameter value by instance.returnMap.put(KeyValue, ParameterValue). You can also remove parameter value by instance.returnMap.remove(KeyValue). Return parameters contains all parameters revieved when function launched and they also contains values with keys as follow.

-Field ID
Key value for the table processed.
-Datasource ID
XF100 and XF300 will return datasource values if you set them as to do so.
-'RETURN_CODE'
Status of the function executed. The value of code means as follow.
'00'=Normaly processed
'01'=Processing canceled
'10'=Normaly inserted
'11'=Inserting canceled
'20'=Normaly updated
'21'=Updating canceled
'30'=Normaly deleted
'99'=Abnormaly ended (error messages are written in session log)
-'RETURN_MESSAGE'
Message to be shon on the function that called function return to.
-'FILE_NAME'
Pdf file name returned by XF290 and XF390. Used in Email processing as follow.
var addressFrom = session.userEmailAddress;
var addressTo = 'abcdefg@xxxxx.com';
var addressCc = session.userEmailAddress;
var subject = 'P/O is attached';
var message = 'We order as attached. ABC co.ltd PIC';
var fileName = instance.returnMap.get('FILE_NAME');
var attachedName = 'PurchaseOrder.pdf';
var charset = '';
session.sendMail(addressFrom, addressTo, addressCc, subject, message, fileName, attachedName, charset);

instance.rollback()
Method to rollback pending transactions. Used in scripts of XF000.

instance.setProcessLog(String process)
Method to write message in the session log.

instance.setStatusMessage(String message)
Method to set specified message on the screen shown.

H O M E