Free optional file or group from subsystem
Note: Many $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $FreeOpt function.
The $FreeOpt function allows a user to free an optional file or group from a subsystem. It is intended as a workaround to the problem that once an optional file or group is opened in a subsystem, the subsystem holds an enqueue on the file until either the subsystem or the file is STOP'ped.
$FreeOpt accepts one argument and returns a numeric code. It is also callable.
The only argument is the name of the file or group to be freed. This name can be either an unqualified name, in which case the standard 204 search order (TEMP GROUP, PERM GROUP, FILE) will be used to try to identify the file or group; or it can be a qualified name that explicitly indicates whether $FreeOpt is to act on a file or group. Some examples of qualified names are
'FILE HOHO' 'PERM GROUP CHUCKLES' 'GROUP KRUSTY'
Note that the last example is not fully qualified so $FreeOpt will first look for a temp group and then a perm group if passed this string. Note also that $FreeOpt will not free a temporary group.
%result = $FreeOpt(fgname)
%result is set to indicate the success of the function.
0 - File/group freed 1 - File/group name missing 2 - File/group name invalid 3 - Temp group invalid 4 - Function invalid outside of subsystem 5 - Not a subsystem file or group 6 - Can't free required subsystem file or group 7 - File or group already freed 8 - File or group still open by some user in subsystem 9 - Can't close because saved compiled code accesses file/group
$FreeOpt is mainly intended to be used with procedure files or groups. Any saved compiled requests that reference a file will prevent $FreeOpt from freeing that file. In addition, because of the difficulties in determining whether any compiled request references a group, $FreeOpt will not free any group that might have saved requests compiled against it. This is determined by testing the group's privilege bits in each subsystem SCLASS for bits that would allow compiled request access (such as FIND statements, STORE RECORD statements, etc..). The X'2DC6' bit must be off in all SCLASSes for $FreeOpt to be able to free a group.
The following program frees optional file BURNS from a subsystem:
B %RC = $FreeOpt( 'BURNS' ) END