$SirMsgP: Difference between revisions
m (1 revision) |
mNo edit summary |
||
| Line 2: | Line 2: | ||
<span class="pageSubtitle"><section begin="desc" />Load procedure for retrieval via $SirMsg<section end="desc" /></span> | <span class="pageSubtitle"><section begin="desc" />Load procedure for retrieval via $SirMsg<section end="desc" /></span> | ||
<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. | <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> | ||
The $SirMsgP function is used to load a procedure into virtual storage for use as the current $SirMsg procedure. | The $SirMsgP function is used to load a procedure into virtual storage for use as the current $SirMsg procedure. | ||
| Line 11: | Line 11: | ||
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. | 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. | ||
==Syntax== | ==Syntax== | ||
<p class="syntax"><section begin="syntax" /> %RESULT = $SirMsgP(proc_name, file_name) | <p class="syntax"><section begin="syntax" /> %RESULT = $SirMsgP(proc_name, file_name) | ||
| Line 17: | Line 18: | ||
</p> | </p> | ||
<p class="caption">%RESULT is set to indicate the success of the function.</p> | <p class="caption">%RESULT is set to indicate the success of the function.</p> | ||
<p class="code"> | <p class="code"> | ||
0 - Procedure set as current $SirMsg procedure | 0 - Procedure set as current $SirMsg 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 | 7 - There is insufficient virtual storage to load the | ||
procedure | |||
</p> | </p> | ||
<p class="caption">$SirMsgP return codes | <p class="caption">$SirMsgP return codes | ||
</p> | </p> | ||
$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: | |||
<ul> | <ul> | ||
<li>No server space is wasted holding infrequently used error messages. | <li>No server space is wasted holding infrequently used error messages. | ||
<li>The virtual storage holding the messages is shared among users. | <li>The virtual storage holding the messages is shared among users. | ||
| Line 49: | Line 50: | ||
<p class="code"> %RC = $SirMsgP('') | <p class="code"> %RC = $SirMsgP('') | ||
</p> | </p> | ||
would clear the current $SirMsg procedure and set %RC to 3. | would clear the current $SirMsg procedure and set %RC to 3. | ||
[[Category:$Functions|$SirMsgP]] | [[Category:$Functions|$SirMsgP]] | ||
Revision as of 18:33, 8 February 2011
<section begin="desc" />Load procedure for retrieval via $SirMsg<section end="desc" />
Most Sirius $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. As of Sirius Mods Version 6.8, it is a callable $function .
The first argument is required and identifies the User Language procedure to be made the current $SirMsg procedure.
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.
Syntax
<section begin="syntax" /> %RESULT = $SirMsgP(proc_name, file_name) <section end="syntax" />
$SirMsgP Function
%RESULT is set to indicate the success of the function.
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
$SirMsgP return codes
$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
%RC = $SirMsgP()
would clear the current $SirMsg procedure and set %RC to 3.