$FreeOpt: Difference between revisions
m (1 revision) |
(Automatically generated page update) |
||
| (10 intermediate revisions by 2 users not shown) | |||
| Line 2: | Line 2: | ||
<span class="pageSubtitle">Free optional file or group from subsystem</span> | <span class="pageSubtitle">Free optional file or group from subsystem</span> | ||
<p class=" | <p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $FreeOpt function.</p> | ||
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. | 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. | ||
<var>$FreeOpt</var> accepts one argument and returns a numeric code. It is also callable . | <var>$FreeOpt</var> accepts one argument and returns a numeric code. It is also [[Calling Sirius Mods $functions|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 | 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 | ||
| Line 15: | Line 15: | ||
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. | 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. | ||
==Syntax== | ==Syntax== | ||
<p class="syntax">< | <p class="syntax"><span class="term">%result</span> = <span class="literal">$FreeOpt</span>(<span class="term">fgname</span>) | ||
< | </p> | ||
<p> | <p> | ||
< | <var class="term">%result</var> is set to indicate the success of the function.</p> | ||
<p class="code"> | <p class="code"> | ||
0 - File/group freed | 0 - File/group freed | ||
| Line 38: | Line 38: | ||
<var>$FreeOpt</var> 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. | <var>$FreeOpt</var> 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. | ||
==Example== | |||
The following program frees optional file <tt>BURNS</tt> from a subsystem: | The following program frees optional file <tt>BURNS</tt> from a subsystem: | ||
<p class="code"> B | <p class="code"> B | ||
Latest revision as of 22:51, 20 September 2018
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.
Syntax
%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 return codes
$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.
Example
The following program frees optional file BURNS from a subsystem:
B %RC = $FreeOpt( 'BURNS' ) END