$Close: Difference between revisions

Latest revision as of 12:51, 7 November 2018

Close file or group in SOUL request

Note: Many $functions have been deprecated in favor of Object Oriented methods. There is currently no OO equivalent for the $Close function.

The $Close function allows a user to close a file or group from within a SOUL request.

$Close accepts one argument and returns a numeric code. It is also callable.

Syntax

%result = $Close(fgname)

Syntax terms

%result

A numerical variable set to indicate the success of the function. See Status codes.

fgname

The name of the file or group to be closed. This name can be unqualified or qualified. If unqualified, the standard Model 204 search order (TEMP GROUP, PERM GROUP, FILE) is used to try to identify the file or group. If qualified, this name explicitly indicates whether $Close is to act on a file or group.

Some examples of qualified names are:

'TEMP GROUP FOO' 'FILE HOHO' 'PERM GROUP CHUCKLES' 'GROUP KRUSTY'

Note that the last example is not fully qualified, so $Close will first look for a temporary group and then a permanent group.

Status codes

The $Close function operates like the CLOSE command, only it allows you to close a file from within a SOUL request. $Close restrictions are listed below among the non-zero values of %result. In short, you cannot close a file or group that has requests compiled against it, has currently included procedures, or is a non-optional subsystem file or group:

0 - File/group closed 1 - File/group name missing 2 - File/group not open 3 - Can't close because of INCLUDE'd proc 4 - Can't close because compiled code accesses file/group, or file is group default file 5 - Can't close required subsystem member 6 - Can't close member of open temp group

Example

The following program closes file KRUSTY:

b %rc = $Close('KRUSTY') End

Products authorizing $Close

SirPro

@@ Line 1: / Line 1: @@
 {{DISPLAYTITLE:$Close}}
-<span class="pageSubtitle">Close file or group in User Language request</span>
+<span class="pageSubtitle">Close file or group in SOUL request</span>
-<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. There is currently no OO equivalent for the $Close function.</p>
+<p class="warn"><b>Note:</b> Many $functions have been deprecated in favor of Object Oriented methods. There is currently no OO equivalent for the <var>$Close</var> function. </p>
-The <var>$Close</var> function allows a user to close a file or group from within a <var class="product">User Language</var> request.
+The <var>$Close</var> function allows a user to close a [[Introduction to User Language#Files|file]] or [[Files, groups, and reference context#File groups|group]] from within a <var class="product">SOUL</var> request.
-<var>$Close</var> accepts one argument and returns a numeric code. It is also callable.
+<var>$Close</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 closed. 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 <var>$Close</var> is to act on a file or group. Some examples of qualified names are :
+==Syntax==
+<p class="syntax"><span class="term">%result</span> = <span class="literal">$Close</span>(<span class="term">fgname</span>)
+</p>
+===Syntax terms===
+<table>
+<tr><th>%result</th>
+<td>A numerical variable set to indicate the success of the function. See [[#Status codes|Status codes]]. </td></tr>
+<tr><th>fgname</th>
+<td>The name of the file or group to be closed. This name can be unqualified or qualified. If unqualified, the standard Model&nbsp;204 search order (TEMP GROUP, PERM GROUP, FILE) is used to try to identify the file or group. If qualified, this name explicitly indicates whether <var>$Close</var> is to act on a file or group.
+<p>
+Some examples of qualified names are: </p>
 <p class="code"> 'TEMP GROUP FOO'
   'FILE HOHO'
   'PERM GROUP CHUCKLES'
-  'GROUP KRUSTY'
+  'GROUP KRUSTY' </p>
-</p>
+<p>
-Note that the last example is not fully qualified so that <var>$Close</var> will first look for a temporary group and then a permanent group.
+Note that the last example is not fully qualified, so <var>$Close</var> will first look for a temporary group and then a permanent group. </p>
-==Syntax==
+</td></tr>
-<p class="syntax"><section begin="syntax" />%result = $Close(fgname)
+</table>
-<section end="syntax" /></p>
-<p class="caption">$Close Function
+===Status codes===
-</p>
+The <var>$Close</var> function operates like the <var>[[CLOSE command]]</var>, only it allows you to close a file from within a <var class="product">SOUL</var> request. <var>$Close</var> restrictions are listed below among the non-zero values of <var class="term">%result</var>.  In short, you cannot close a file or group that has requests compiled against it, has currently included procedures, or is a non-optional subsystem file or group:
-<p class="caption">%result is set to indicate the success of the function.</p>
+<p class="code"> 0 - File/group closed
-<p class="code">
-- File/group closed
 - File/group name missing
 - File/group not open
 - Can't close because of INCLUDE'd proc
-- Can't close because compiled code accesses file/group
+- Can't close because compiled code accesses file/group, or file is group default file
 - Can't close required subsystem member
 - Can't close member of open temp group
 </p>
-<p class="caption">$Close return codes
+==Example==
+The following program closes file <code>KRUSTY</code>:
+<p class="code">b
+%rc = $Close('KRUSTY')
+End
 </p>
-The following program closes file 'KRUSTY'.
+==Products authorizing {{PAGENAMEE}}==
-<p class="code"> B
+<ul class="smallAndTightList">
- %RC = $Close( 'KRUSTY' )
+<li>[[SirPro|SirPro]]</li>
- END
+</ul>
+<p>
 </p>
-<p class="code">
 [[Category:$Functions|$Close]]