Appendix D: Task Parameters

This mechanism is typically used for tasks of type LIST where it is required that a SEARCH screen be processed first. Any type of task can be used as the passthru task, but note that if it is a POPUP then the normal processing described in this FAQ will not be performed.

NOTE: If a task's session data is removed, such as by the keep data on exit option, then all memory of any previous activity for the task will be lost and any future activation of the task will be treated as if it were the first activation.

Please note the following:

• The use of a SEARCH screen will not alter the contents of the $where variable.
• The contents of the $where variable will NOT be cleared when the RESET button is pressed.
• In page controllers which deal with more than one table object (such as LIST2, LIST3, MULTI2, MULTI3 and MULTI4) this value will be appended to the $where variable for the first object, and the $this->sql_where variable for subsequent objects as it may have been filtered out of the $where variable which is extracted from the previous object.

Note the following:

• The use of a SEARCH screen will cause the contents of the $search variable to be replaced.
• The contents of the $search variable will be cleared if the RESET button is pressed.

• name is the variable name without a leading $ sign
• value is the value for that variable without enclosing quotes.

Multiple entries may be defined by separating them with '&' as in name1=value&name2=value.

Any entries defined here will be available to any script which is run during the execution of this task, and will also be written out in the <params> area of the XML document so that it is also available to the XSL transformation process.

select_one=TRUE

This affects a POPUP task by changing the select controls from checkboxes to radio buttons, thus allowing only a single row to be selected. This is demonstrated in Choose Task (menu).

<fieldname>=$logon_user_id

This can also be used in tasks of type UPDATE 1 and DELETE 1 to restrict updates and deletes to the person who created the record. Simply insert an entry where <fieldname> is typically created_user (the field which identifies who created the record).

allow_empty_where=TRUE

Patterns like LIST 2 which deal with more than one entity cannot normally be run directly from a menu as there is nothing available in the $where string, which causes the task to fail. This setting will bypass that check, but be aware that without any selection criteria this will retrieve all available records from the outer database table.

no_filepicker=Y

When a batch task is activated it normally logs its progress in a file which is written to the LOGS directory. If that task is activated from a navigation button in an online screen it will, by default, automatically jump to a filepicker screen so that the log file can be viewed. This behaviour can be overridden with this setting.

Other settings may be used, but they will be ignored by the framework and therefore must be dealt with by custom code.

This switch has the following options:

• Yes - details for the task will persist, so if it is activated again it will resume from where it left off.
• No - details for the task will not persist, so if it is activated again it will start afresh.

This should only be used for tasks of type LIST, POPUP or TREE which are suitable for restarting from the previous state. It will be ignored for enquire, update and delete forms where a new selection is always passed down from the previous form. If used in an ADD form it will cause the data for the previous addition to be loaded as default values, which could cause confusion.

A task can be in one of the following states:

• Active - It is the current task. It is shown as the last entry in the bottom line of the menu bar.
• Suspended - It has passed control to another task, usually from a button on the navigation bar, and will resume processing once that other task has finished. All tasks which appear in the bottom line of the menu bar in front of the current task are suspended tasks.
• Terminated - It no longer appears in the bottom line of the menu bar.

When a task is active or suspended data is stored in the SESSION array so that if it is reactivated later it can resume processing from where it left off.

When a task is terminated, either by pressing the SUBMIT or CANCEL/CLOSE buttons, the default behaviour is to erase this data so that the next activation can start afresh. This behaviour can be altered by changing this switch from 'NO' to 'YES'.

NOTE: If control is passed to another task by any means other than by the use of the SUBMIT, CANCEL or CLOSE buttons then the data for the current task will remain in the session file. This data will be reused on the next activation unless it is overridden by new selection criteria.

This facility has the following limitations:

• The main task must have a screen which displays a single record, not multiple records.
• The main task cannot be given a selection of records to display which would cause the scrolling area to be displayed. This is because it can only pass the primary key from a single occurrence to the run_at_end task.
• If the run_at_end task is run manually before the main task ends it will not be run again automatically.

Note that if the run_at_cancel task has any user dialog it opens up the possibility that it may be cancelled before it completes its task.

If the main task performs a commit (database update) before it terminates then it wasn't cancelled, so the run_at_cancel task will not be run.

If a value for quick_navigation task is entered then whenever this task is run an extra column will be added to the screen at the start of each row and will contain a quicknav icon which, when pressed, will automatically jump to the specified child task and pass to it the primary key of the current row.

This button will have "QNav" as its column heading. If you hover your mouse over it the task description will be displayed a s a tooltip.

Note that this option is only valid for LIST screens.