New (Journal constructor): Difference between revisions
Jump to navigation
Jump to search
mNo edit summary |
m (→Syntax terms) |
||
| (5 intermediate revisions by 2 users not shown) | |||
| Line 6: | Line 6: | ||
<tr><th>%journal</th> | <tr><th>%journal</th> | ||
<td>A reference to an instance of a <var>Journal</var> object. </td></tr> | <td>A reference to an instance of a <var>Journal</var> object. </td></tr> | ||
<tr><th><var>%(Journal)</var></th> | |||
<tr><th><var>[%(Journal):]</var></th> | |||
<td>The optional class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>. See [[#Usage notes|"Usage notes"]], below, for more information about invoking a <var>Journal</var> <var>Constructor</var>.</td></tr> | <td>The optional class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>. See [[#Usage notes|"Usage notes"]], below, for more information about invoking a <var>Journal</var> <var>Constructor</var>.</td></tr> | ||
<tr><th>string</th> | <tr><th>string</th> | ||
<td>A string that is the DDname of the journal dataset or the name of the stream that is to be accessed.</td></tr> | <td>A string that is the DDname of the journal dataset, or the name of the stream, that is to be accessed.</td></tr> | ||
</table> | </table> | ||
==Usage notes== | ==Usage notes== | ||
<ul> | <ul> | ||
<li>As described in [[Object variables#Using New or other Constructors|"Using New or other Constructors"]], <var>New</var> can be invoked with no object, with an explicit class name, or with an object variable in the class, even if that object is <var>Null</var>:<p class="code">%journal = new | <li>As described in [[Object variables#Using New or other Constructors|"Using New or other Constructors"]], <var>New</var> can be invoked with no object, with an explicit class name, or with an object variable in the class, even if that object is <var>Null</var>:<p class="code">%journal = new('MYJRNL') | ||
%journal = %(Journal):new | %journal = %(Journal):new('MYJRNL') | ||
%journal = %journal:new | %journal = %journal:new('MYJRNL') | ||
</p> | </p> | ||
<li>In <var class="product">Sirius Mods</var> version 7.7, | <li>In <var class="product">Sirius Mods</var> version 7.7, | ||
the New method returns a Null object if the journal is not present or is not a | the <var>New</var> method returns a <var>Null</var> object if the journal is not present or is not a | ||
valid journal. | valid journal. | ||
In <var class="product">Sirius Mods</var> version 7.8 and later, New also throws a | In <var class="product">Sirius Mods</var> version 7.8 and later, <var>New</var> also throws a <var>[[BadJournal class|BadJournal]]</var> exception on an error, | ||
and it will not return a <var>Null</var> <var>Journal</var> object without throwing an exception. | |||
and it will not return a Null Journal object without throwing an exception. | |||
Consequently, invocations of New in <var class="product">Sirius Mods</var> version 7.7 | Consequently, invocations of <var>New</var> in <var class="product">Sirius Mods</var> version 7.7 | ||
need to include a test with an On Error unit and a test for a Null result. | need to include a test with an <var>On Error</var> unit and a test for a <var>Null</var> result. | ||
<li>In <var class="product">Sirius Mods</var> version 7.7, | <li>In <var class="product">Sirius Mods</var> version 7.7, | ||
New does not require the input journal to be from the same | <var>New</var> does not require the input journal to be from the same <var class="product">Model 204</var> release as | ||
the Online. | the Online. | ||
However, if the releases are different, an [[AppendJournalData (Stringlist function)|AppendJournalData]] call | However, if the releases are different, an <var>[[AppendJournalData (Stringlist function)|AppendJournalData]]</var> call | ||
that references this journal | that references this journal | ||
will silently fail to add any data to its output Stringlist. | will silently fail to add any data to its output <var>Stringlist</var>. | ||
As of <var class="product">Sirius Mods</var> version 7.8, an attempt to instantiate a journal object variable | As of <var class="product">Sirius Mods</var> version 7.8, an attempt to instantiate a journal object variable | ||
that references a journal from a different version than the Online produces | that references a journal from a different version than the Online produces | ||
a BadJournal exception. | a <var>BadJournal</var> exception. | ||
</ul> | </ul> | ||
==See also== | ==See also== | ||
{{Template:Journal:New footer}} | {{Template:Journal:New footer}} | ||
Latest revision as of 21:04, 6 November 2012
Create a new Journal object (Journal class)
Syntax
%journal = [%(Journal):]New( string) Throws BadJournal
Syntax terms
| %journal | A reference to an instance of a Journal object. |
|---|---|
| [%(Journal):] | The optional class name in parentheses denotes a Constructor. See "Usage notes", below, for more information about invoking a Journal Constructor. |
| string | A string that is the DDname of the journal dataset, or the name of the stream, that is to be accessed. |
Usage notes
- As described in "Using New or other Constructors", New can be invoked with no object, with an explicit class name, or with an object variable in the class, even if that object is Null:
%journal = new('MYJRNL') %journal = %(Journal):new('MYJRNL') %journal = %journal:new('MYJRNL')
- In Sirius Mods version 7.7, the New method returns a Null object if the journal is not present or is not a valid journal. In Sirius Mods version 7.8 and later, New also throws a BadJournal exception on an error, and it will not return a Null Journal object without throwing an exception. Consequently, invocations of New in Sirius Mods version 7.7 need to include a test with an On Error unit and a test for a Null result.
- In Sirius Mods version 7.7, New does not require the input journal to be from the same Model 204 release as the Online. However, if the releases are different, an AppendJournalData call that references this journal will silently fail to add any data to its output Stringlist. As of Sirius Mods version 7.8, an attempt to instantiate a journal object variable that references a journal from a different version than the Online produces a BadJournal exception.