$SirMsgP: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
m (misc formatting) |
||
| (One intermediate revision by the same user 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="warn"><b>Note: </b> | <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. | <var>$SirMsgP</var> accepts two arguments and returns a numeric code. It is a [[Calling Sirius Mods $functions|callable]] $function . | ||
==Syntax== | ==Syntax== | ||
| Line 16: | Line 12: | ||
</p> | </p> | ||
< | ===Syntax terms=== | ||
< | <table> | ||
<tr><th>%result</th> | |||
<td>A [[#Return codes|numeric code]] set to indicate the success of the function.</td></tr> | |||
<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> | |||
<tr><th>file_name</th> | |||
<td>An optional file name. If this argument is not provided or is a null string, the current file is used. </td></tr> | |||
</table> | |||
===Return codes=== | ===Return codes=== | ||
<p class="code">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 | ||
3 - Specified procedure name is invalid (null) | 3 - Specified procedure name is invalid (null) | ||
4 - Either file name invalid, or no current file, or | 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 | |||
7 - There is insufficient virtual storage to load the | |||
</p> | </p> | ||
| Line 46: | Line 48: | ||
<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. | <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> | <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 %rc to 3:</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> | ||
<p class="code">%rc = $SirMsgP('') | <p class="code">%rc = $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
%rcto 3:%rc = $SirMsgP('')