$SirMsg: Difference between revisions

Latest revision as of 16:49, 14 August 2017

Line of current $SirMsgP procedure

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

The $SirMsg function is used to retrieve a line from the current $SirMsg procedure as set by $SirMsgP.

Syntax

%msg = $SirMsg (line_num [,%arg1][,%arg2][,%arg3])

Syntax terms

%msg	A string set to the contents of `line_num` in the current `$SirMsg` procedure.
line-num	The number of the line within the current `$SirMsg` procedure to be returned. A zero returns the name of the current `$SirMsg` procedure. If there is no current `$SirMsg` procedure or the requested line number is invalid (negative or greater than the number of lines in the `$SirMsg` procedure), `$SirMsg` returns a null string.
%arg1	An optional substitution argument that will replace the first occurrence of the literal `%C`, if one is present, in the message. See the example in the "Examples" section, below.
%arg2	An optional substitution argument that will replace the second `%C`, if one is present, in the message.
%arg3	An optional substitution argument that will replace the third `%C`, if one is present, in the message.

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 can be shared among users.
- It simplifies sharing common messages among procedures in a subsystem or online.

Examples

Suppose the current $SirMsg procedure as set by $SirMsgP contains these lines:

MSG0001: Invalid PF key. MSG0002: Processing record number=%C in file=%C. MSG0003: Invalid data in input field.

If this Print statement is in a For loop against file HISTORY, on record number 355:

Print $SirMsg(2,$Currec,$Curfile)

The output is:

MSG0002: Processing record number=355 in file=HISTORY

The value of $Currec replaces the first %C substitution string, and the value of $Curfile replaces the second. As many as three, optional, substitution strings (%C) might be present in one message.

The following statement prints a null string:

Print $SirMsg(4)

@@ Line 1: / Line 1: @@
 {{DISPLAYTITLE:$SirMsg}}
-<span class="pageSubtitle"><section begin="desc" />Line of current $SirMsgP procedure<section end="desc" /></span>
+<span class="pageSubtitle">Line of current $SirMsgP procedure</span>
-<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $SirMsg function is [[to be entered]].</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 <var>$SirMsg</var> function.</p>
-The $SirMsg function is used to retrieve a line from the current $SirMsg procedure as set by $SirMsgP.
+The <var>$SirMsg</var> function is used to retrieve a line from the current <var>$SirMsg</var> procedure as set by <var>[[$SirMsgP]]</var>.
-$SirMsg accepts one required argument, and it returns a string.
+==Syntax==
+<p class="syntax"><span class="term">%msg</span> = $SirMsg (<span class="term">line_num</span> [,<span class="term">%arg1</span>][,<span class="term">%arg2</span>][,<span class="term">%arg3</span>])
+</p>
+===Syntax terms===
+<table>
+<tr><th>%msg</th>
+<td>A string set to the contents of <var class="term">line_num</var> in the current <var>$SirMsg</var> procedure.</td></tr>
+<tr><th nowrap>line-num</th>
+<td>The number of the line within the current <var>$SirMsg</var> procedure to be returned. A zero returns the name of the current <var>$SirMsg</var> procedure.
+<p>
+If there is no current <var>$SirMsg</var> procedure or the requested line number is invalid (negative or greater than the number of lines in the <var>$SirMsg</var> procedure), <var>$SirMsg</var> returns a null string.</p></td></tr>
-The argument is the number of the line within the current $SirMsg procedure to be returned. A zero returns the name of the current $SirMsg procedure.
+<tr><th>%arg1</th>
+<td>An optional substitution argument that will replace the first occurrence of the literal <code>%C</code>, if one is present, in the message. See the example in the "Examples" section, below. </td></tr>
-If there is no current $SirMsg procedure or the requested line number is invalid (negative or greater than the number of lines in the $SirMsg procedure), $SirMsg returns a null string.
+<tr><th>%arg2</th>
-==Syntax==
+<td>An optional substitution argument that will replace the second <code>%C</code>, if one is present, in the message.</td></tr>
-<p class="syntax"><section begin="syntax" /> %MSG = $SirMsg (line_num)
-<section end="syntax" /></p>
-<p class="caption">$SirMsg Function
-</p>
-<p class="caption">%MSG is set to the contents of line_num in the current $SirMsg procedure.</p>
+<tr><th>%arg3</th>
+<td>An optional substitution argument that will replace the third <code>%C</code>, if one is present, in the message.</td></tr>
+</table>
-$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:
+==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>. The advantages of using <var>$SirMsg</var> are:
+<ul>
 <li>No server space is wasted holding infrequently used error messages.
 <li>The virtual storage holding the messages can be shared among users.
 <li>It simplifies sharing common messages among procedures in a subsystem or online.
+</ul>
 </ul>
+==Examples==
+Suppose the current <var>$SirMsg</var> procedure as set by <var>$SirMsgP</var> contains these lines:
-Suppose the current $SirMsg procedure as set by $SirMsgP contains these lines:
+<p class="code">MSG0001: Invalid PF key.
-<p class="code"> MSG0001 Invalid PF key.
+MSG0002: Processing record number=%C in file=%C.
- MSG0002 Record not found.
+MSG0003: Invalid data in input field.
- MSG0003 Invalid data in input field.
 </p>
-The following statement would print: :lit.MSG0002 Record not found.:elit.
-<p class="code"> PRINT $SirMsg(2)
-</p>
-The following statement would print a null string:
-<p class="code"> PRINT $SirMsg(4)
-</p>
-<p class="code">
-<ul>
-<li>No authorizers for $function
+If this <var>Print</var> statement is in a <var>For</var> loop against file <code>HISTORY</code>, on record number 355:
+<p class="code">Print $SirMsg(2,$Currec,$Curfile)</p>
-</ul>
+<p>
+The output is:
 </p>
-<p class="caption">Products authorizing $SirMsg
+<p class="output">MSG0002: Processing record number=355 in file=HISTORY </p>
+<p>
+The value of <var>[[$Currec]]</var> replaces the first <code>%C</code> substitution string, and the value of <var>[[$Curfile]]</var> replaces the second. As many as three, optional, substitution strings (<code>%C</code>) might be present in one message.
 </p>
+<p>
+The following statement prints a null string: </p>
+<p class="code">Print $SirMsg(4)
 [[Category:$Functions|$SirMsg]]