FUNCTION is a two-word command used in Special Procedures
that gives you control over certain functions such as deleting records, simulating certain keystrokes, record navigation, dynamically changing the PROTECT attribute of fields on the screen, and writing, rewriting, and rereading records.
The basic scenario here is that you are either clicking through or scrolling through a subset of data records on a screen that is up because of an APPEND
, UPDATE
, READ
, or SCROLL
command, and that at any given time the attention is on a particular one of those records. In the descriptions below, we will call that record the currentrecord.
Forms:
FUNCTION CR FUNCTION NEXT
FUNCTION F5 FUNCTION PREV
FUNCTION ATTR FUNCTION HOME
FUNCTION DELETE FUNCTION END
FUNCTION WRITE FUNCTION UP
FUNCTION REREAD FUNCTION TOP
FUNCTION GOTO
FUNCTION CR
A programmable way to simulate the user pressing Carriage Return (a.k.a. Enter). So this is a way to tab to the next field. Control leaves your procedure and goes back to the screen after a FUNCTION CR.
FUNCTION F5
A programmable way to simulate the user pressing F5. For fields that have a control associated with them, pressing F5 accomplishes the same thing as clicking the control. If the control activates a listpick, then %answer=1 if the user made a choice or zero if not.
FUNCTION ATTR
Allows program control of, and dynamic varying of the PROTECT attribute of fields. The syntax is:
FUNCTION ATTR field-name-list +PROTECT
FUNCTION ATTR field-name-list -PROTECT
In the first case the named fields become protected fields, and in the second case they become unprotected.
FUNCTION DELETE
Deletes the current record. Control leaves your procedure and goes back to the screen after a FUNCTION DELETE.
FUNCTION WRITE
Writes the current record immediately. Rewrites if the record already exists. All validations are performed, but a -E Special Procedure is not performed. If you do a FUNCTION WRITE and then your program changes the record further, you must do a FUNCTION REREAD before the user can perform additional data entry on that record.
FUNCTION REREAD
Reread the current record. Useful if your program has selected this record in another collection and then changed it. Your user needs to see the latest content of this record. Also useful after a FUNCTION WRITE. Control stays in your procedure so that you can do other operations (such as a CURSOR TO) after a FUNCTION REREAD.
FUNCTION GOTO
Go to the nth record. The syntax is:
FUNCTION GOTO n where n is a one-relative row number.
You can discover n for any record via a SCREENSTATUS ROW
command.
%answer=n (zero if n does not exist).
FUNCTION NEXT
A programmable way to go to the next record. Control stays in your procedure after a FUNCTION NEXT.
%answer=Row number of the new current record, or zero if you were
on the last row and tried to go to the next record.
FUNCTION PREV
A programmable way to go to the previous record. Control stays in your procedure after a FUNCTION PREV.
%answer=Row number of the new current record, or zero if you were
on the first row and tried to go to the previous record.
FUNCTION HOME
A programmable way to go to the first record of the subset. Control stays in your procedure after a FUNCTION HOME.
FUNCTION END
A programmable way to go to the last record of the subset. Control stays in your procedure after a FUNCTION END.
FUNCTION UP
When you are dealing with hierarchical data entry or updating (such as a one-to-many screen) FUNCTION UP provides a programmable way to go up a level in the hierarchy.
There is an N option on this command, so the full syntax is:
FUNCTION[/N] UP
the purpose for the N option is to suppress the "do you want to write?" question if the current row has changed (or if you are doing an APPEND) when the FUNCTION UP happens. The N option will suppress the question and it will also throw away the current row if you do not write it yourself.
Further, any -B or field entry procedures are not automatically done when a FUNCTION UP happens. The suggested coding sequence goes something like this:
screenstatus changed
if %answer="YES"
function write
function next
function/n up
:
(control stays in so you)
(can do any -B or field )
(entry code here )
:
cursor to ..
endif
The FUNCTION UP and FUNCTION TOP commands both support the following answers:
Ctl.Ans1 =Level you started at
Ctl.Ans2 =Level you ended at
Ctl.Ans3 =Name of the field that gets control
An example can be found at UTILITIES/VARIOUS TESTS/ONE TO MANY APPEND
The name of the procedure that is executed when you make this selection is OM.
FUNCTION TOP
Everything written about FUNCTION UP applies to FUNCTION TOP. The only difference is that FUNCTION UP takes you up one level, and FUNCTION TOP always takes you to the top, that is, level 1.
If you are at level two there is no difference between FUNCTION UP and FUNCTION TOP. Look above to see the answers for FUNCTION TOP.
