$SirMsgP: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (misc formatting)
 
(25 intermediate revisions by 3 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">Load procedure for retrieval via $SirMsg</span>
<span class="pageSubtitle">Load procedure for retrieval via $SirMsg</span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $SirMsgP function.</p>
<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $SirMsgP function.</p>


The <var>$SirMsgP</var> function is used to load a procedure into virtual storage for use as the current <var>$SirMsg</var> procedure.  
The <var>$SirMsgP</var> function is used to load a procedure into virtual storage for use as the current <var>$SirMsg</var> procedure.  


<var>$SirMsgP</var> accepts two arguments and returns a numeric code. As of <var class="product">[[Sirius Mods]]</var> Version 6.8, it is a callable $function .  
<var>$SirMsgP</var> accepts two arguments and returns a numeric code. It is a [[Calling Sirius Mods $functions|callable]] $function .  


The first argument is required and identifies the <var class="product">User Language</var> procedure to be made the current <var>$SirMsg</var> procedure.
==Syntax==
<p class="syntax"><span class="term">%result</span> = <span class="literal">$SirMsgP</span>(<span class="term">proc_name</span>, [<span class="term">file_name</span>])
</p>
 
===Syntax terms===
<table>
<tr><th>%result</th>
<td>A [[#Return codes|numeric code]] set to indicate the success of the function.</td></tr>


The second argument is an optional file name. If the second argument is not provided, or is a null string, the current file is used.
<tr><th>proc_name</th>
<td>This required argument identifies the <var class="product">SOUL</var> procedure to be made the current <var>$SirMsg</var> procedure. </td></tr>


==Syntax==
<tr><th>file_name</th>
<p class="syntax"><section begin="syntax" /> %RESULT = $SirMsgP(proc_name, file_name)
<td>An optional file name. If this argument is not provided or is a null string, the current file is used. </td></tr>
<section end="syntax" /></p>
</table>
<p class="caption">$SirMsgP Function
</p>
<p class="caption">%RESULT is set to indicate the success of the function.</p>


<p class="code">  
===Return codes===
0 - Procedure set as current <var>$SirMsg</var> procedure
<p class="code">0 - Procedure set as current <var>$SirMsg</var> procedure
1 - Procedure is locked for edit or delete
1 - Procedure is locked for edit or delete
2 - Procedure does not exist or the current user does not
2 - Procedure does not exist or the current user does not have access privilege
        have access privilege
3 - Specified procedure name is invalid (null)
3 - Specified procedure name is invalid (null)
4 - Either file name invalid, or no current file, or caller does not have  
4 - Either file name invalid, or no current file, or
    sufficient privilege to display/include procedures
        caller does not have sufficient privilege to
7 - There is insufficient virtual storage to load the procedure
        display/include procedures
7 - There is insufficient virtual storage to load the
        procedure
</p>
<p class="caption">$SirMsgP return codes
</p>
</p>


<var>$SirMsgP</var> and [[$SirMsg]] allow a programmer to use a <var class="product">Model 204</var> procedure as a message repository. Each line of the procedure corresponds to a message that can be requested by line number with $SirMsg.  
==Usage notes==
 
<ul>
<li><var>$SirMsgP</var> and <var>[[$SirMsg]]</var> allow a programmer to use a <var class="product">Model 204</var> procedure as a message repository. Each line of the procedure corresponds to a message that can be requested by line number with <var>$SirMsg</var>.  
<p>
The advantages of using <var>$SirMsg</var> are:
The advantages of using <var>$SirMsg</var> are:
 
</p>
<ul>
<ul>
<li>No server space is wasted holding infrequently used error messages.  
<li>No server space is wasted holding infrequently used error messages.  
Line 44: Line 46:
</ul>
</ul>


<li>If <var>$SirMsgP</var> determines that another thread has the same procedure as its current <var>$SirMsg</var> procedure then that thread's virtual storage copy is shared. <var>$SirMsgP</var> considers another thread to be using the same <var>$SirMsg</var> procedure if the procedure name, file name and contents of the procedure are identical to the one being set.
<p>
If not released explicitly, the virtual storage occupied by a <var>$SirMsg</var> procedure will not be released until user logoff or restart. To release the virtual storage used by a <var>$SirMsg</var> procedure without setting a new one, simply invoke <var>$SirMsgP</var> with a null procedure name. For example, the following statement would clear the current <var>$SirMsg</var> procedure and set <code>%rc</code> to 3:</p>


If <var>$SirMsgP</var> determines that another thread has the same procedure as its current <var>$SirMsg</var> procedure then that thread's virtual storage copy is shared. <var>$SirMsgP</var> considers another thread to be using the same <var>$SirMsg</var> procedure if the procedure name, file name and contents of the procedure are identical to the one being set.
<p class="code">%rc = $SirMsgP(&apos;&apos;)
 
If not released explicitly, the virtual storage occupied by a <var>$SirMsg</var> procedure will not be released until user logoff or restart. To release the virtual storage used by a <var>$SirMsg</var> procedure without setting a new one, simply invoke <var>$SirMsgP</var> with a null procedure name. For example
<p class="code"> %RC = $SirMsgP('')
</p>
</p>
would clear the current <var>$SirMsg</var> procedure and set %RC to 3.


[[Category:$Functions|$SirMsgP]]
[[Category:$Functions|$SirMsgP]]

Latest revision as of 19:43, 7 August 2017

Load procedure for retrieval via $SirMsg

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

The $SirMsgP function is used to load a procedure into virtual storage for use as the current $SirMsg procedure.

$SirMsgP accepts two arguments and returns a numeric code. It is a callable $function .

Syntax

%result = $SirMsgP(proc_name, [file_name])

Syntax terms

%result A numeric code set to indicate the success of the function.
proc_name This required argument identifies the SOUL procedure to be made the current $SirMsg procedure.
file_name An optional file name. If this argument is not provided or is a null string, the current file is used.

Return codes

0 - Procedure set as current $SirMsg procedure 1 - Procedure is locked for edit or delete 2 - Procedure does not exist or the current user does not have access privilege 3 - Specified procedure name is invalid (null) 4 - Either file name invalid, or no current file, or caller does not have sufficient privilege to display/include procedures 7 - There is insufficient virtual storage to load the procedure

Usage notes

  • $SirMsgP and $SirMsg allow a programmer to use a Model 204 procedure as a message repository. Each line of the procedure corresponds to a message that can be requested by line number with $SirMsg.

    The advantages of using $SirMsg are:

    • No server space is wasted holding infrequently used error messages.
    • The virtual storage holding the messages is shared among users.
    • It simplifies sharing common messages among procedures in a subsystem or online.
  • If $SirMsgP determines that another thread has the same procedure as its current $SirMsg procedure then that thread's virtual storage copy is shared. $SirMsgP considers another thread to be using the same $SirMsg procedure if the procedure name, file name and contents of the procedure are identical to the one being set.

    If not released explicitly, the virtual storage occupied by a $SirMsg procedure will not be released until user logoff or restart. To release the virtual storage used by a $SirMsg procedure without setting a new one, simply invoke $SirMsgP with a null procedure name. For example, the following statement would clear the current $SirMsg procedure and set %rc to 3:

    %rc = $SirMsgP('')