$Setg Subsys: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
(Automatically generated page update)
 
(28 intermediate revisions by 3 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">Set subsystem-wide global</span>
<span class="pageSubtitle">Set subsystem-wide global</span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $Setg_Subsys function is the [[SetGlobal (System/Subsystem subroutine)]].</p>
<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $Setg_Subsys function is the <var>[[SetGlobal (System subroutine)|SetGlobal]]</var> subroutine.</p>


This function allows a user to set the value of a <var class="product">Model 204</var> "global variable" which has a subsystem-wide scope. These are used for the value of the $GetG function or dummy string ("?&amp;amp;amp.") substitution. The order in which the different scopes of global variables are searched can be controlled using $SirParm parameters: for $GetG, with 'GETGSYS', and for dummy strings, with 'DUMMYSYS'.
This function allows a user to set the value of a <var class="product">Model 204</var> "global variable" which has a subsystem-wide scope. These are used for the value of the $GetG function or dummy string ("?&") substitution. The order in which the different scopes of global variables are searched can be controlled using <var>$SirParm</var> parameters: for $GetG, with 'GETGSYS', and for dummy strings, with 'DUMMYSYS'.


The $Setg_Subsys function accepts three arguments and returns zero, indicating success, or a number indicating the cause of error, if there is one.  
The $Setg_Subsys function accepts three arguments and returns zero, indicating success, or a number indicating the cause of error, if there is one.  
Line 17: Line 17:


==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" />%rc = $Setg_Subsys(glob_name, value, subsys_name)
<p class="syntax"><span class="term">%rc</span> = <span class="literal">$Setg_Subsys</span>([<span class="term">glob_name</span>], [<span class="term">value</span>], <span class="term">subsys_name</span>)
<section end="syntax" /></p>
<p class="caption">$Setg_Subsys Function
</p>
</p>
<p class="caption">%RC is set to 0 or to an error indicator.</p>


<p class="code">  
<p>
0 - No errors
<var class="term">%rc</var> is set to 0 or to an error indicator.</p>
1 - Not system administrator
 
2 - Insufficient storage
===Return codes===
3 - Subsystem name missing
<p class="code">0 - No errors
</p>
1 - Not system administrator
<p class="caption">$Setg_Subsys return codes
2 - Insufficient storage
3 - Subsystem name missing
</p>
</p>


This function can be used to set a global variable which is used for all users of a subsystem. The value can be set during <var class="product">Model 204</var> initialization (that is, in the CCAIN stream), so values can be calculated once, rather than every time a user enters the subsystem. For example, the following request can be run from CCAIN:


<p class="code"> OPEN CALENDAR
==Usage notes==
BEGIN
<ul>
%DAYS STRING LEN 100
<li>This function can be used to set a global variable which is used for all users of a subsystem. The value can be set during <var class="product">Model 204</var> initialization (that is, in the CCAIN stream), so values can be calculated once, rather than every time a user enters the subsystem. For example, the following request can be run from CCAIN:
%X FLOAT
 
%DAYS = ''
<p class="code">OPEN CALENDAR
D: FOR EACH VALUE OF DAY
BEGIN
%DAYS = %DAYS WITH ' ' WITH VALUE IN D
%DAYS STRING LEN 100
END FOR
%X FLOAT
%X = $Setg_Subsys('DAYS', %DAYS, 'TIMESHEET')
%DAYS = ''
END
D: FOR EACH VALUE OF DAY
%DAYS = %DAYS WITH ' ' WITH VALUE IN D
END FOR
%X = $Setg_Subsys('DAYS', %DAYS, 'TIMESHEET')
END
</p>
</p>


Then, during execution of the TIMESHEET subsystem, the global variable DAYS can be used to obtain the days of the week.  
Then, during execution of the <code>TIMESHEET</code> subsystem, the global variable <code>DAYS</code> can be used to obtain the days of the week.  


Also, since there is one shared subsystem global table for the entire system, a smaller GTBL value for each user can be achieved than if the global values are set with user global variables.  
Also, since there is one shared subsystem global table for the entire system, a smaller GTBL value for each user can be achieved than if the global values are set with user global variables. </li>


The order in which the different scopes of global variables are searched can be controlled using $SirParm parameters: for $GETG, with 'GETGSYS', and for dummy strings, with 'DUMMYSYS'.
<li>The order in which the different scopes of global variables are searched can be controlled using <var>[[$SirParm]]</var> parameters: for <var>$Getg</var>, with 'GETGSYS', and for dummy strings, with 'DUMMYSYS'.
Here is an example to show the effects of DUMMYSYS and GETGSYS; assume the following procedure is executed in the CCAIN input stream:
Here is an example to show the effects of DUMMYSYS and GETGSYS; assume the following procedure is executed in the CCAIN input stream:


<p class="code"> BEGIN
<p class="code">BEGIN
%X = $Setg_Subsys('JUNK', 'HELLO', 'MY_SUBSYS')
%X = $Setg_Subsys('JUNK', 'HELLO', 'MY_SUBSYS')
END
END
</p>
</p>


and the login procedure of MY_SUBSYS contains the following requests:
And assume the login procedure of <code>MY_SUBSYS</code> contains the following requests:


<p class="code"> BEGIN
<p class="code">BEGIN
%Y = $SETG('JUNK', 'GOODBYE')
%Y = $SETG('JUNK', 'GOODBYE')
END
END
BEGIN
BEGIN
PRINT '?&amp;amp;amp.JUNK'
PRINT '?&amp.JUNK'
PRINT $GETG('JUNK')
PRINT $GETG('JUNK')
END
END
</p>
</p>


Then here are various command streams, and their results:  
Then here are various command streams, and their results:  
<ol>
<li>DUMMYSYS=0, GETGSYS=0:


1. DUMMYSYS=0, GETGSYS=0:
<p class="code">BEGIN
 
%X FLOAT
<p class="code"> BEGIN
%X = $SirParm('DUMMYSYS', 0)
%X FLOAT
%X = $SirParm('GETGSYS', 0)
%X = $SirParm('DUMMYSYS', 0)
END
%X = $SirParm('GETGSYS', 0)
MY_SUBSYS </p>
END
MY_SUBSYS
   
   
'''produces the following print lines:'''
Produces the following print lines:
   
   
GOODBYE
<p class="output">GOODBYE
GOODBYE
GOODBYE
</p>
</p></li>




 
<li>DUMMYSYS=0, GETGSYS=1:
1. DUMMYSYS=0, GETGSYS=1:
<p class="code">BEGIN
<p class="code"> BEGIN
%X FLOAT
%X FLOAT
%X = $SirParm('DUMMYSYS', 0)
%X = $SirParm('DUMMYSYS', 0)
%X = $SirParm('GETGSYS', 1)
%X = $SirParm('GETGSYS', 1)
END
END
MY_SUBSYS </p>
MY_SUBSYS
'''produces the following print lines:'''
   
   
GOODBYE
Produces the following print lines:
HELLO
<p class="output">GOODBYE
</p>
HELLO
 
</p></li>




1. DUMMYSYS=1, GETGSYS=0:
<li>DUMMYSYS=1, GETGSYS=0:
<p class="code"> BEGIN
<p class="code">BEGIN
%X FLOAT
%X FLOAT
%X = $SirParm('DUMMYSYS', 1)
%X = $SirParm('DUMMYSYS', 1)
%X = $SirParm('GETGSYS', 0)
%X = $SirParm('GETGSYS', 0)
END
END
MY_SUBSYS
MY_SUBSYS </p>
   
   
'''produces the following print lines:'''
Produces the following print lines:
   
   
HELLO
<p class="output">HELLO
GOODBYE
GOODBYE
</p>
</p></li>




 
<li>DUMMYSYS=1, GETGSYS=1:
1. DUMMYSYS=1, GETGSYS=1:
<p class="code">BEGIN
<p class="code"> BEGIN
%X FLOAT
%X FLOAT
%X = $SirParm('DUMMYSYS', 1)
%X = $SirParm('DUMMYSYS', 1)
%X = $SirParm('GETGSYS', 1)
%X = $SirParm('GETGSYS', 1)
END
END
MY_SUBSYS </p>
MY_SUBSYS
   
   
'''produces the following print lines:'''
Produces the following print lines:
<p class="output">HELLO
HELLO
HELLO
HELLO
</p></li>
</p>
</ol></li>


<li>The current values of subsystem globals can be retrieved using <var>[[$Setg_Subsys_List]]</var>. </li>


The current values of subsystem globals can be retrieved using $Setg_Subsys_List.  
<li>Retrieval of subsystem global variables is highly efficient; updates, however, are not, so use this $function appropriately. </li>
</ul>


Retrieval of subsystem global variables is highly efficient; updates, however, are not, so use this $function appropriately.
==Products authorizing {{PAGENAMEE}}==
 
<ul class="smallAndTightList"></li>
See [[$SirParm]].
<li>[[List of $functions|Sirius functions]]</li>
 
<li>[[Janus Web Server]]</li>
This $function is new in Version 5.5 of the <var class="product">[[Sirius Mods]]</var>.
 
<ul class="smallAndTightList">
<li>[[Sirius functions]]
<li>[[Janus Web Servert]]
</ul>
</ul>
<p class="caption">Products authorizing $Setg_Subsys
</p>


[[Category:$Functions|$Setg_Subsys]]
[[Category:$Functions|$Setg_Subsys]]

Latest revision as of 22:52, 20 September 2018

Set subsystem-wide global

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $Setg_Subsys function is the SetGlobal subroutine.

This function allows a user to set the value of a Model 204 "global variable" which has a subsystem-wide scope. These are used for the value of the $GetG function or dummy string ("?&") substitution. The order in which the different scopes of global variables are searched can be controlled using $SirParm parameters: for $GetG, with 'GETGSYS', and for dummy strings, with 'DUMMYSYS'.

The $Setg_Subsys function accepts three arguments and returns zero, indicating success, or a number indicating the cause of error, if there is one.

The first argument is the name of the global variable to be set. This is an optional argument; it defaults to the null string.

The second argument is the value to which the global variable is to be set. This is an optional argument; it defaults to the null string.

The third argument is the name of the subsystem that the variable is associated with. This is an optional argument if the $function is invoked from within a subsystem; it defaults to the null string. A non-null subsystem name is required if the $function is invoked from outside a subsystem. If invoked from a subsystem and the third argument is null, the name of the subsystem is used.

System administrator privileges are required to invoke this $function, unless the third argument is omitted or is the null string, and the $function is invoked from a precompiled procedure; in that case, no privileges are required, and the subsystem name used is the active subsystem.

Syntax

%rc = $Setg_Subsys([glob_name], [value], subsys_name)

%rc is set to 0 or to an error indicator.

Return codes

0 - No errors 1 - Not system administrator 2 - Insufficient storage 3 - Subsystem name missing


Usage notes

  • This function can be used to set a global variable which is used for all users of a subsystem. The value can be set during Model 204 initialization (that is, in the CCAIN stream), so values can be calculated once, rather than every time a user enters the subsystem. For example, the following request can be run from CCAIN:

    OPEN CALENDAR BEGIN %DAYS STRING LEN 100 %X FLOAT %DAYS = D: FOR EACH VALUE OF DAY %DAYS = %DAYS WITH ' ' WITH VALUE IN D END FOR %X = $Setg_Subsys('DAYS', %DAYS, 'TIMESHEET') END

    Then, during execution of the TIMESHEET subsystem, the global variable DAYS can be used to obtain the days of the week.

    Also, since there is one shared subsystem global table for the entire system, a smaller GTBL value for each user can be achieved than if the global values are set with user global variables.
  • The order in which the different scopes of global variables are searched can be controlled using $SirParm parameters: for $Getg, with 'GETGSYS', and for dummy strings, with 'DUMMYSYS'. Here is an example to show the effects of DUMMYSYS and GETGSYS; assume the following procedure is executed in the CCAIN input stream:

    BEGIN %X = $Setg_Subsys('JUNK', 'HELLO', 'MY_SUBSYS') END

    And assume the login procedure of MY_SUBSYS contains the following requests:

    BEGIN %Y = $SETG('JUNK', 'GOODBYE') END BEGIN PRINT '?&amp.JUNK' PRINT $GETG('JUNK') END

    Then here are various command streams, and their results:

    1. DUMMYSYS=0, GETGSYS=0:

      BEGIN %X FLOAT %X = $SirParm('DUMMYSYS', 0) %X = $SirParm('GETGSYS', 0) END MY_SUBSYS

      Produces the following print lines:

      GOODBYE GOODBYE


    2. DUMMYSYS=0, GETGSYS=1:

      BEGIN %X FLOAT %X = $SirParm('DUMMYSYS', 0) %X = $SirParm('GETGSYS', 1) END MY_SUBSYS

      Produces the following print lines:

      GOODBYE HELLO


    3. DUMMYSYS=1, GETGSYS=0:

      BEGIN %X FLOAT %X = $SirParm('DUMMYSYS', 1) %X = $SirParm('GETGSYS', 0) END MY_SUBSYS

      Produces the following print lines:

      HELLO GOODBYE


    4. DUMMYSYS=1, GETGSYS=1:

      BEGIN %X FLOAT %X = $SirParm('DUMMYSYS', 1) %X = $SirParm('GETGSYS', 1) END MY_SUBSYS

      Produces the following print lines:

      HELLO HELLO

  • The current values of subsystem globals can be retrieved using $Setg_Subsys_List.
  • Retrieval of subsystem global variables is highly efficient; updates, however, are not, so use this $function appropriately.

Products authorizing $Setg_Subsys