https://m204wiki.rocketsoftware.com/api.php?action=feedcontributions&user=Admin&feedformat=atomm204wiki - User contributions [en]2024-03-28T11:48:45ZUser contributionsMediaWiki 1.40.1https://m204wiki.rocketsoftware.com/index.php?title=New_and_updated_messages_in_Model_204_version_7.8&diff=117751New and updated messages in Model 204 version 7.82019-12-18T00:34:34Z<p>Admin: Redirected page to New and updated messages in Model 204 version 7.8 (Beta)</p>
<hr />
<div>#REDIRECT [[New and updated messages in Model 204 version 7.8 (Beta)]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Draft:_New_and_updated_messages_in_Model_204_version_7.8&diff=117750Draft: New and updated messages in Model 204 version 7.82019-12-18T00:33:02Z<p>Admin: Admin moved page Draft: New and updated messages in Model 204 version 7.8 to New and updated messages in Model 204 version 7.8 (Beta): Beta period has begun</p>
<hr />
<div>#REDIRECT [[New and updated messages in Model 204 version 7.8 (Beta)]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=New_and_updated_messages_in_Model_204_version_7.8&diff=117749New and updated messages in Model 204 version 7.82019-12-18T00:33:02Z<p>Admin: Admin moved page Draft: New and updated messages in Model 204 version 7.8 to New and updated messages in Model 204 version 7.8 (Beta): Beta period has begun</p>
<hr />
<div> <br />
[[Release notes for Model 204 version 7.8|Back to release notes]]<br />
<br />
<div class="noautonum">__TOC__</div><br />
This topic lists messages that were added or changed for Model 204 version 7.8.<br />
<br />
<p style="color:red"><b>******THIS IS A DRAFT DOCUMENT.******</b></p><br />
<br />
==M204 messages==<br />
===<b id="M204.0141:"></b>M204.0141: Bug .. duplicate file name in checkpoint record===<br />
<P><br />
A duplicate file name was encountered while attempting to add a deferred update data set to the file directory during recovery. This indicates a potential bug in the Model 204 software. </P><br />
<p><br />
<b>System manager response:</b> Contact [[Contacting Rocket Software Technical Support|Technical Support]] with the following documentation: </p><br />
<ul><br />
<li>Audit trail from the previous run </li><br />
<li>Journal from the previous run </li><br />
</ul><br />
<p><br />
<b>Operator response:</b> Notify the system manager. </p><br />
{{Template:M204.0141 footer}}<br />
<br />
===<b id="M204.0143:"></b>M204.0143: No files changed after last checkpoint, RESTART bypassed===<br />
<P>This message indicates that no updates were detected while scanning the checkpoint data set beyond the last checkpoint or the specified checkpoint. </P><br />
{{Template:M204.0143 footer}}<br />
<br />
===<b id="M204.0165:"></b>M204.0165: Missing an update unit from ICL (InComplete List)===<br />
<P><br />
While scanning the CCARF data set, Model&nbsp;204 has detected the end of an update unit for which no corresponding start of update unit was found. Possible explanations for this error are: </P><br />
<ul><br />
<li>A utility program was used to copy the original journal to data set being used as CCARF, and a portion of the original data set was not copied. </li><br />
<li>A copy was not done. </li><br />
</ul><br />
<p><br />
<b>System manager response:</b> If the original journal was a multi-volume data set and was copied to another data set for input to this run, verify that all volumes were in fact copied, and rerun the job. If CCARF was the original data set, contact [[Contacting Rocket Software Technical Support|Technical Support]]. Have the following documentation available: </p><br />
<ul><br />
<li>Audit trail of the original run </li><br />
<li>Snap </li><br />
<li>UTILJ of the CCARF data set or a copy of this data set on tape </li><br />
<li>UTILC of the restart data set or a copy of this data set on tape </li><br />
</ul><br />
{{Template:M204.0165 footer}}<br />
<br />
===<b id="M204.0352:"></b>M204.0352: IODEV=nn, Ok uuuuuuuuuu aaaaaaaaaa llllll yy.ddd mmm dd hh.mm.ss ccc nnnnnnnn===<br />
<br />
The layout of this message has been reformatted to accommodate five digit user numbers.<br />
<br />
{{Template:M204.0352 footer}}<br />
<br />
===<b id="M204.0479:"></b>M204.0479: process group not found: <i>processgroupname</i>===<br />
<br />
A <var>[[Statement syntax#TRANSFER|TRANSFER]]</var> statement was evaluated, resulting in an attempt to perform a VTAM trusted logon in another Online (the target Online). The <var>PARTNER</var> processgroup, identified in the <var>[[DEFINE PROCESS command: Transfer Control partner|DEFINE PROCESS]]</var> command in the transferring Online, was not found in the target Online. As a result, the TRANSFER fails and the user remains in the transferring online.<br />
<br />
<b>System manager response:</b> The <code>PARTNER=</code> token in the <var>DEFINE PROCESS</var> command of the transferring Online has an incorrect value for <var class="term">processgroupName</var>. Check the spelling to ensure that it is the correct name of the intended processgroup in the target Online.<br />
<br />
<b>Return codes:</b> I 0 0 AUDITMS<br />
----<br />
<br />
===<b id="M204.0480:"></b>M204.0480: Invalid backpage request: backPage===<br />
<p><br />
A backpage command of the form <var>P -<i>n</i></var> or <var>P +<i>n</i></var> was issued, but <var>[[NBKPG parameter|NBKPG]]</var> is 0, or the value of <var class="term">n</var> is invalid. The command is echoed in hex, so you can see exactly what was entered. For example, if <code>P -99</code> was issued but <var>NBKPG</var> is 50, then the following message would be issued:</p><br />
<p class="code">M204.0480: Invalid backpage request: P -99(X'D74060F9F9')</p><br />
<p><br />
<b>Response:</b> Correct the backpage command, or set <var>NBKPG</var> greater than 0.<br />
</p><br />
{{Template:M204.0480 footer}}<br />
<br />
===<b id="M204.0481:"></b>M204.0481: Procedure procName in subsysName could not be made resident; increase RESPAGE or RESSIZE ===<br />
<p><br />
The named procedure in the named subsystem could not be made resident in resident request storage. <br />
</p><br />
<p><br />
<b>Response:</b> Increase the size of resident request storage with a <var>[[RESSIZE parameter|RESSIZE]]</var> or <var>[[RESPAGE parameter|RESPAGE]]</var> parameter in CCAIN. <var>RESSIZE</var> (below-the-bar storage) can be dynamically reset, but <var>RESPAGE</var> (above-the-bar storage) cannot.<br />
</p><br />
{{Template:M204.0481 footer}}<br />
<br />
===<b id="M204.0541:Procedure"></b>M204.0541:Procedure is in use: procedure===<br />
<P>The procedure named in the message is currently in use by another user. The command entered cannot be processed until the procedure is no longer in use. </P><br />
<p><b>Response:</b> Retry the command when the procedure is no longer in use. </p><br />
{{Template:M204.0541 footer}}<br />
<br />
===<b id="M204.0569:"></b>M204.0569: File filename?,? Find: Table B records to be searched ?=? number===<br />
The message test now includes the filename, to help track down the cause of the direct search. This change has been enabled within v7.7 with the application of zap 77z032, and within V7.6 with the application of zap 76z386.<br />
{{Template:M204.0569 footer}}<br />
<br />
===<b id="M204.1070:"></b>M204.1070: ALLOCATE ddName failed - reason===<br />
This message has been changed to add the ddname of the failing dataset to the message text. <br />
{{Template:M204.1070 footer}}<br />
<br />
===<b id="M204.1500:"></b>M204.1500: <i>token</i> ===<br />
<p>Message M204.1500: <var class="term">token</var> has a new form relevant to the [https://m204wiki.rocketsoftware.com/index.php/CA-ACF2_MVS_interface CA-ACF2 MVS], [https://m204wiki.rocketsoftware.com/index.php/CA-ACF2_VM_interface CA-ACF2 VM], [https://m204wiki.rocketsoftware.com/index.php/Security_Server_(formerly_RACF)_interface Security Server (formerly RACF)], and [https://m204wiki.rocketsoftware.com/index.php/CA-Top_Secret_interface CA-Top Secret] Model 204 security interfaces.</p><br />
<br />
<p>When the default user fails to log in, the security interface is operational but CCASTAT logons are not allowed. The following error message is displayed:</p><br />
<p class="syntax">M204.1500: CCASTAT logons not allowed</p><br />
{{Template:M204.1500 footer}}<br />
<!-- skeleton as it was in pdf/message number message text /--><br />
----<br />
<br />
===<b id="M204.1899"></b>M204.1899 Transfer statement from sourceVtamName to targetVtamName complete, User userId disconnected===<br />
The message, issued when a VTAM Transfer statement completes, now contains the source and target VTAM names for the transfer process. <br />
<br />
The change in message text is enabled within V7.7 with the application of zap 77z310.<br />
{{Template:M204.1899 footer}}<br />
<br />
===<b id="M204.1900"></b>M204.1900 User userId transferred to targetVtamName from sourceVtamName===<br />
This message, issued on the target ONLINE when a user has transferred to that ONLINE, now displays the source and target VTAM names involved in the VTAM Transfer.<br />
<br />
The change in message text is enabled within V7.7 with the application of zap 77z310.<br />
{{Template:M204.1900 footer}}<br />
<br />
===<b id="M204.2020"></b>M204.2020 File fileName; condition?,? OPEN command rejected===<br />
The first change to this message is that the filename of the affected file is now displayed at the beginning of the message text.<br />
<br />
The second change is that a second error type affecting file opens is now support. The original error type of "Unsupported device for Model 204 database %F" was reported for all condition,s even where the device type wasn't the underlying issue. Whilst this error type has been retained for conditions where it is valid, a new error type of "DDNAME not found" is now available for the message. Thus, in a situation where one thread is attempting to allocate a ddname, and another thread in parallel is trying to open a file with the same ddname, the following message variant may be produced<br />
<br />
M204.2020: File filename; DDNAME not found, OPEN command rejected<br />
<br />
{{Template:M204.2020 footer}}<br />
<br />
===<b id="M204.2700"></b>M204.2700 CHECKPOINT command ignored: sub-transaction checkpoint in progress===<br />
<P><br />
A <code>[[CHECKPOINT_command|CHECKPOINT]] (TRAN | SUBTRAN | ABORT)</code> command was issued while the system was taking a sub-transaction checkpoint. The command is ignored. If this message was issued in response to a <code>CHECKPOINT ABORT</code> command, the<br />
sub-transaction in progress has passed that phase of its processing during which it can be aborted.<br />
</P><br />
{{Template:M204.2700 footer}}<br />
<br />
===<b id="M204.2964"></b>M204.2964 Password missing or too long===<br />
<p><br />
A password string within an IFSTRTN call has not been delimited with a semicolon.<br />
</p><br />
<p><br />
<b>Response:</b><br />
Ensure that the password string is delimited by a semicolon, as in the following example<br />
</p><br />
<p class="code>CALL IFSTRTN(RC,'logonid;password;'...)</p><br />
<p><b>Version introduced:</b><br />
7.8<br />
</p><br />
<b>Return codes:</b> E 00 04 AUDITMS NOCOUNT<br />
<br />
===<b id="M204.2965"></b>M204.2965 Unable to cleanly close log file(s)===<br />
<p>Introduced in zap 77z243.</p><br />
<p>This message causes a snap/dump if the log file (such as a journal, jlog, or checkpoint) cannot be cleanly quiesced when bringing down an Online. The problem with the log file is rare but caused a hang further along in processing. This message causes a snap/dump much closer to the time of error, making it easier to diagnose the problem.</p><br />
<p><b>Response:</b> Use the snap/dump generated by the message to diagnose the cause of the error.</p><br />
<b>Return codes:</b> E 88 88 DUMP SNAP AUDITAD NOTERM OPR<br />
----<br />
<br />
===<b id="M204.2966"></b>M204.2966 <i>what</i> line <i>number?</i>,? procedure <i>proc</i> in file <i>file</i>===<br />
<p><br />
This message provides diagnostic information following various types of error messages. </p><br />
<p><br />
The first M204.2966 message after an error has <var class="term">what</var> set to <code>Error at</code>. Subsequent M204.2966 messages (if any) have <var class="term">what</var> set to <code>Called from</code>. </p><br />
<p><br />
<var class="term">number</var>, <var class="term">proc</var>, and <var class="term">file</var> indicate the line number, procedure, and file where the error occurred or from where the previous M204.2966 entry was called. Essentially, this provides a call stack trace to aid in diagnosing problems. No more than 20 levels of calls are shown for an error. </p><br />
<p><br />
<b>Response:</b> Use the M204.2966 messages after an error to try to diagnose the cause of the error.<br />
</p><br />
{{Template:M204.2966 footer}}<br />
----<br />
===<b id="M204.2967"></b>M204.2967 <i>what</i> line <i>number</i> of command level program===<br />
<p><br />
This message provides diagnostic information after various types of error messages. </p><br />
<p><br />
The first M204.2967 message after an error has <var class="term">what</var> set to <code>Error at</code> and subsequent M204.2967 messages (if any) have <var class="term">what</var> set to <code>Called from</code>. </p><br />
<p><br />
<var class="term">number</var> indicates the line number for a command line program (counting from the <var>Begin</var>) where the error occurred, or where the previous [[M204.2966]] entry was called from. Essentially, this provides a call stack trace to aid in diagnosing problems. No more than 20 levels of calls are shown for an error. </p><br />
<p><br />
<b>Response:</b> Use the M204.2967 (and M204.2966, if any) after an error to try to diagnose the cause of the error.<br />
</p><br />
{{Template:M204.2967 footer}}<br />
----<br />
===<b id="M204.2968"></b>M204.2968 <i>what</i>: no debug info===<br />
<p><br />
An error message (immediately preceding M204.2968) was issued, but insufficient compile-time information was collected to provide the diagnostic information provided in the [[M204.2966]] and [[M204.2967]] messages.<br />
To get that additional information to help diagnose the problem, set the [[SIRFACT parameter|SIRFCAT X'01']] bit if authorized for [[SirFact]], or set the [[DEBUGUL parameter]] to a non-zero value. The latter requires no product authorization, but it does increase QTBL requirements. </p><br />
<p><br />
<b>Response:</b> If you are unable to diagnose the problem, consider setting one of the parameters described above to aid in problem diagnosis.<br />
</p><br />
{{Template:M204.2968 footer}}<br />
----<br />
===<b id="M204.2969"></b>M204.2969 MBSCAN (<i>mbscan</i>) exceeded?,? records to be searched ?=? <i>number</i>===<br />
<p><br />
A Table B scan would exceed the setting of <var>[[MBSCAN parameter|MBSCAN]]</var>, so the request is cancelled. </p><br />
<p><br />
<b>Response:</b> Correct the <var>Find</var> statement at the line indicated by the following [[M204.2966]] message (hopefully available), or increase <var>MBSCAN</var> to tolerate the number of scanned records, if reasonable.<br />
</p><br />
{{Template:M204.2969 footer}}<br />
----<br />
===<b id="M204.2970"></b>M204.2970 Maximum call stack limit (<i>limit</i>) reached===<br />
<p><br />
The number of messages describing the call stack reached the maximum allowed for such messages (currently 20). This message is largely informational; it is more useful to focus on the preceding [[M204.2966]] messages. </p><br />
<p><br />
<b>Response:</b> Examine the preceding M204.2966 messages.<br />
</p><br />
{{Template:M204.2970 footer}}<br />
==MSIR messages==<br />
===<b id="MSIR.0942"></b>MSIR.0942 Debugger token0 port defaulted to token2===<br />
This message has been changed from an error message to an informational message<br />
{{Template:MSIR.0942 footer}}</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=M204wiki_main_page&diff=117748M204wiki main page2019-12-18T00:31:06Z<p>Admin: /* Release notes */</p>
<hr />
<div>Welcome to M204wiki, the platform for Rocket Software Model&nbsp;204 technical documentation. Here you can find product information, installation and reference documentation, and release notes.<br />
<br />
M204wiki contains the current version of Model 204 documentation, with release-specific features noted in the text. In some cases, documentation is provided in [[Model 204 documentation|PDF format]]. <br />
<br />
In addition to plentiful page links, [[Searching M204wiki|M204wiki searching features]] help you quickly locate the information you need. <br />
<br />
__TOC__<br />
<br />
==Model 204==<br />
<dl><br />
<dt>Installation<br />
<dd>[[Model 204 installation]]<br />
<br />
<dt>Introductions to core Model 204 areas<br />
<dd>[[SOUL|SOUL/User Language]]<br />
<br>[[File management overview|File management]]<br />
<br>[[File architecture overview|File architecture]]<br />
<br>[[Model 204 configurations and operating environments|System management]]<br />
<br />
<dt>Commands<br />
<dd>[[List of Model 204 commands]]<br />
<br />
<dt>Parameters<br />
<dd>[[List of Model 204 parameters]]<br />
<br />
<dt>Security<br />
<dd>[[Model 204 security features]]<br />
<br>[[Storing security information (CCASTAT)#Overview|Storing security information (CCASTAT)]]<br />
<br>[[:Category:Security interfaces|Security interfaces]]<br />
<br>[[Janus Network Security]]<br />
<br />
<dt>PDF manuals<br />
<dd>[[Model 204 documentation|Model 204 documentation conversion]]<br />
</dl><br />
<br />
==$Functions==<br />
[[SOUL $functions#Summary of standard functions|SOUL $functions]]<br />
<br />
==Messages==<br />
<div id="messages"></div><br />
<ul><br />
<li>[[List of Model 204 messages|Model 204 messages]]</li><br />
<li>[[:Category:Fast/Unload messages|Fast/Unload messages]] </li><br />
<li>[[:Category:SirAud messages|SirAud messages]] </li><br />
<li>[[:Category:SirTune data collector messages|SirTune data collector messages]] </li><br />
<li>[[:Category:RockZap messages|RockZap messages]] </li><br />
<li>[[Dictionary/204 messages]] </li><br />
<li>[[SoftSpy messages]] </li><br />
<li>[[Connect* messages]] </li><br />
</ul><br />
<br />
==Tools==<br />
<ul><br />
<li>[[Debugger]] and [[Introduction to SoftSpy|SoftSpy]] </li><br />
<li>[[SirAud]] - Audit trail analysis</li><br />
<li>[[SirFact]] - SOUL dump analysis</li><br />
<li>[[SirLib]] - SOUL code management</li><br />
<li>[[SirMon]] - Model 204 performance monitor</li><br />
<li>[[SirPro]] - SOUL programmers' interface</li><br />
<li>[[SirScan]] - Real-time Model 204 journal queries</li><br />
<li>[[SirTune]] - SOUL tuning</li><br />
<li>[[SoulEdit]] - Advanced SOUL-based editor</li><br />
<li>[[RKWeb]] - Browser-based access to [[RKTools]] members</li><br />
<li>[[RKTools installation]]</li><br />
</ul><br />
<br />
==Release notes==<br />
<dl><br />
<dt>Model 204<br />
<dd>[[Release notes for Model 204 version 7.8|Release notes for Model 204 V7.8 (Beta)]]<br />
<dd>[[Release notes for Model 204 version 7.7|Release notes for Model 204 V7.7]]<br />
<dd>[[Release notes for Model 204 version 7.6|Release notes for Model 204 V7.6]]<br />
<dd>[[Release notes for Model 204 version 7.5|Release notes for Model 204 V7.5]]<br />
<dd>[[Media:M204_ReleaseNotes_V74.pdf|Release notes for Model 204 V7.4 (PDF)]]<br />
<dd>[[Media:M204_ReleaseNotes_V71.pdf|Release notes for Model 204 V7.1 (PDF)]]<br />
<br />
<dt>SoftSpy<br />
<dd>[[Release notes for SoftSpy V7.6]]<br />
<dd>[[Release notes for SoftSpy V7.5]]<br />
<br />
<dt id="rktools_notes">SOUL tools <br />
<dd>[[Release notes for RKTools V7.7]]<br />
<dd>[[Release notes for RKTools V7.5]]<br />
<br />
<dt id="Sirius_Mods_release_notes">Sirius Mods<br />
<dd>[[Release notes for Sirius Mods V8.1]]<br />
<br>[[Release notes for Sirius Mods V8.0]]<br />
<br>[[Release notes for Sirius Mods V7.9]]<br />
<br>[[Release notes for Sirius Mods V7.8]]<br />
<br />
<dt id="funRel">Fast/Unload</dt><br />
<p class="note"><b>Note:</b> Fast/Unload is integrated with the Model 204 load module starting with [[Release notes for Model 204 version 7.7#funldIntegrat|Model 204 V7.7]] </p><br />
<dd>[[Release notes for Fast/Unload V4.7]]<br />
<br>[[Release notes for Fast/Unload V4.6]]<br />
<br>[[Media:Funrel44New.pdf|Release notes for Fast/Unload V4.4 (PDF)]]<br />
</dl><br />
<br />
==Overviews and tutorials==<br />
<dl><br />
<dt>Overviews of core Model 204 areas<br />
<dd>[[Introduction to User Language]]<br />
<br>[[File management overview]]<br />
<br>[[File architecture overview]]<br />
<dt>OO structures and concepts<br />
<dd>[[Getting started with OOP for User Language programmers]]<br />
<br>[[Longstrings]]<br />
<br>[[$lists]]<br />
<br>[[Sessions]]<br />
<br>[[Sdaemons]]<br />
<br>[[Regex processing]]<br />
<br>[[XML processing in Janus SOAP]]<br />
<br>[[Unicode]]<br />
</dl><br />
<br />
==Contribute to M204wiki==<br />
Anyone who works with [[Model 204]] is encouraged to contribute to M204wiki, either by providing new content or correcting or improving content. Before you can edit content you must [[M204wiki:Get M204wiki User ID|obtain an M204wiki User ID]].<br />
<br />
==Download a local copy of M204wiki==<br />
You can [[M204wiki:Database download|download your own copy of M204wiki]].</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Draft:_Release_notes_for_Model_204_version_7.8&diff=117747Draft: Release notes for Model 204 version 7.82019-12-18T00:30:14Z<p>Admin: Admin moved page Draft: Release notes for Model 204 version 7.8 to Release notes for Model 204 version 7.8 (Beta): Beta period has begun</p>
<hr />
<div>#REDIRECT [[Release notes for Model 204 version 7.8 (Beta)]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Release_notes_for_Model_204_version_7.8&diff=117746Release notes for Model 204 version 7.82019-12-18T00:30:14Z<p>Admin: Admin moved page Draft: Release notes for Model 204 version 7.8 to Release notes for Model 204 version 7.8 (Beta): Beta period has begun</p>
<hr />
<div><br />
<p style="color:red"><b>******THIS IS A DRAFT DOCUMENT.******</b></p><br />
<br />
These release notes list the enhancements and other changes contained in Model 204 version 7.8, <b><i>which is still in development</i></b>. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein. <br />
<br />
==Overview==<br />
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.<br />
Before beginning your installation, please read through this information about product installation and changes.<br />
<br />
==New in this release==<br />
The table below cites some highlights of Model&nbsp;204 version 7.8. For a full list of features, refer to the Table of Contents. <br />
<p>See also the [[#Compatibility Issues|Compatibility]] section for possible issues.</p><br />
<table><br />
<tr class="head"><th>Category</th><br />
<th>Feature</th></tr><br />
<tr><br />
<td>SOUL</td><br />
<td><br />
<ul><br />
<li>The new [[#AmIndependent method|AmIndependent]] method returns TRUE for daemons spawned by RunIndependently.<br />
</li><br />
<li>The Object class now supports the [[#Support for copying Object class objects|copy and deepCopy methods]].<br />
</li><br />
</ul><br />
</td></tr><br />
<br />
<tr><br />
<td>Janus Web</td><br />
<td><br />
<ul><br />
<li>[[#Web Sockets|Janus Web Sockets]] are now supported.</li><br />
</ul><br />
</td></tr><br />
<br />
<tr><br />
<td nowrap>Networking</td><br />
<td><br />
<b>Note:</b> The two-phase commit and commit exits features are licensed and purchased separately from Model 204.<br />
<ul><br />
<li>Two-phase commit. A Model 204 online can now be configured to use two-phase commit (2PC). The Janus internal socket API is used for the calls to the coordinator. JANUS commands are used for all 2PC configuration. A new JANUS port type has been added, 2PC.</li><br />
<li>Commit exits are now supported. The commit exit runs within the APSY, which is defined by the <var>COMMITX</var> parameter and uses normal APSY processing. </li><br />
</ul></td></tr><br />
<br />
<tr><br />
<td>ECF tables</td><br />
<td><br />
<ul><br />
<li>The new <var>DISPLAY ECF</var> command and <var>EXTERNAL REMOVE</var> statement enable more efficient management of [[#Managing ECF tables more efficiently|ECF tables]].</li><br />
</ul><br />
</td></tr><br />
<tr><br />
<td>Performance</td><br />
<td><br />
<ul><br />
<li>[[#MP/204 offload improvements|MP/204 offload improvements]] -- application code for these SOUL statements is now fully offloadable: <br />
<ul><br />
<li><var>File Records In/On</var></li><br />
<li><var>Remember</var></li><br />
<li><var>Position</var></li><br />
<li><var>Sort Values</var></li><br />
<li><var>Reset Header/Trailer</var></li><br />
<li><var>Find and Print Count</var></li><br />
<li><var>Find All Values</var></li><br />
<li><var>For Each Value</var></li><br />
</ul><br />
</li><br />
</ul><br />
</td></tr><br />
<br />
<tr><br />
<td>Security</td><br />
<td><br />
<ul><br />
<li>CA-Top Secret can [[#CA-Top Secret can disallow CCASTAT logins|disallow CCASTAT logins]].</li><br />
<li>[[#DEFUSER can specify a jobname not authorized to access M204|DEFUSER]] can specify a jobname not authorized to access M204.</li><br />
</ul><br />
</td></tr><br />
<br />
<tr><br />
<td nowrap>System enhancements</td><br />
<td><br />
<ul><br />
<li>The <var>MONITOR USERS</var> command output displays [[#New wait types for daemon/master waits|two new wait types]].</li><br />
</ul></td></tr><br />
<br />
<br />
<tr><br />
<td nowrap>AUDIT204 enhancements</td><br />
<td><br />
<ul><br />
<li>The new TIMEHH parameter on the <var>[[#FORMAT command|FORMAT]]</var> command of the AUDIT204 utility provides greater time stamp precision.</li><br />
</ul></td></tr><br />
<br />
<tr><br />
<td nowrap>New commands</td><br />
<td><br />
<ul><br />
<li><var>[[#DISPLAY ECF|DISPLAY ECF]]</var> displays details from ECF tables, or the current status of users accessing ECF modules.</li><br />
</ul></td></tr><br />
<br />
<tr><br />
<td nowrap>New parameters</td><br />
<td><br />
<ul><br />
<li><var>[[#ENQTIME|ENQTIME]]</var> specifies the number of milliseconds waited for each record locking retry wait.</li><br />
<li><var>[[#EVALOPT|EVALOPT]]</var> controls the cancellation of a request on truncation of string data.</li><br />
<li><var>[[#MAXPRE, MAXBOUT, MAXSUBT|MAXPRE, MAXBOUT, and MAXSUBT]]</var> can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.</li><br />
<li><var>[[#NLDAPBUF|NLDAPBUF]]</var> allows the number of LDAP buffers allocated during startup to be set in CCAIN.</li><br />
<li><var>[[#SERV4G|SERV4G]]</var> allows testing of server tables that span a 4-gigabyte boundary.</li><br />
<li><var>[[#WEBDFLT|WEBDFLT]]</var> changes the default JANUS WEB ALLOW rule back to ALLOW.</li><br />
</ul></td></tr><br />
<br />
<tr><br />
<td nowrap>Janus and TN3270 debuggers</td><br />
<td><br />
<ul><br />
<li>The debuggers can now view or watch the values of [[#Access to exposed variables|variables exposed to local routines/methods]].</li><br />
<li>When execution pauses, the debuggers now [[#Subroutine or method display|display the subroutine or method]] being executed.</li><br />
</ul></td><br />
</tr><br />
<br />
<tr><br />
<td nowrap>User/system statistics</td><br />
<td><br />
<ul><br />
<li><var>[[#MPR, MBO, MCP, and RCV|MPR, MBO, MCP, and RCV]]</var> provide high water mark transaction information in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. <br />
</li><br />
<li>[[#DKWTS and DKWTMICS|New system statistics]] DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.</li><br />
</ul></td></tr><br />
</table><br />
<br />
==Operating system and hardware requirements==<br />
<br />
===Operating system requirements===<br />
<br />
<ul><br />
<li><b>IBM z/OS versions supported:</b> <br />
<ul><br />
<li>All IBM supported releases up to and including z/OS 2.3. <br />(For z/OS 2.2, see [[IBM z/OS 2.2 PTF requirement]].)</li><br />
<p>Version 1.07 is sufficient for all functionality except for the following features:</p><br />
<ul><br />
<li>zHPF support requires version [[IBM z/OS 2.1 compatibility issue|2.1]].</li><br />
<li>Large (1 MB) page support requires version 1.9.</li><br />
<li>Extended address volumes (EAV) requires version 1.12.</li><br />
</ul><br />
</li><br />
</ul><br />
On z/OS, Model 204 release 7.8 operates as an APF authorized load module, as required by many 7.8 features. <br /><br />
To run Model 204 unauthorized, [[Contacting Rocket Software Technical Support|contact Technical Support]].<br />
<br />
<li><b>IBM z/VM versions supported:</b> <br />
<ul><br />
<li>All IBM supported releases up to and including z/VM 6.4.</li><br />
</ul><br />
</li><br />
<br />
<li><b>IBM z/VSE versions supported:</b><br />
<ul><br />
<li>All IBM supported releases up to and including z/VSE 6.1.</li><br />
</ul><br />
</li><br />
</ul><br />
<br />
===Hardware requirements===<br />
<br />
In general, Model 204 version 7.8 requires the IBM z/890 or above processor.<br />
<p>However, the IBM z10 or above processor is required for the following features:<br />
<ul><br />
<li>large (1 MB) page support</li><br />
<li>IBM's High Performance FICON (zHPF) support</li><br />
</ul></p><br />
<br />
===Connect<sup>&#9733;</sup> compatibility with Model 204===<br />
<br />
Connect<span class="superstar">&#9733;</span> version 7.5 or 7.7 is compatible with Model 204 version 7.8.<br />
<br />
For more information on Connect<span class="superstar">&#9733;</span> installation, see the [[:Category:Connect*|Connect<span class="superstar">&#9733;</span> wiki pages]].<br />
<br />
==SOUL (User Language) enhancements==<br />
===AmIndependent method===<br />
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)<br />
<br />
The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:<br />
<table><br />
<th>Type</th><br />
<th>AmDaemon</th><br />
<th>AmIndependent</th><br />
<tr><br />
<td>$COMBG</td><br />
<td>False</td><br />
<td>False</td><br />
</tr><br />
<tr><br />
<td>Independent daemon</td><br />
<td>False</td><br />
<td>True</td></tr><br />
<tr><br />
<td>Other daemon</td><br />
<td>True</td><br />
<td>False</td><br />
</tr><br />
<tr><br />
<td>Web, etc.</td><br />
<td>False</td><br />
<td>False</td><br />
</tr></table><br />
<br />
===$ProcOpn===<br />
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:<br />
<br />
<p class="code">%result = $procOpn('0123', 'MYFILE')</p><br />
<br />
Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is enabled in V7.7 with the application of zap 77z054.<br />
<br />
===Allow parentheses to surround a boolean enumeration object===<br />
The following sample code:<br />
<p class="code"> begin <br />
variables are undefined <br />
%isValid is boolean initial (True) <br />
if (%isValid) then <br />
print 'in IF' <br />
end if <br />
end </p> <br />
<br />
will now compile and run successfully, since this syntax: <br />
<br />
<p class="syntax">if (%isValid) then </p><br />
<br />
is logically equivalent to this:<br />
<br />
<p class="syntax">if %isValid then </p><br />
<br />
Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.<br />
<br />
===Support for copying Object class objects===<br />
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:<br />
<p class="code"> begin <br />
%x is object object <br />
%y is object object <br />
%y = new <br />
%x = %y:copy <br />
end </p><br />
<br />
This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.<br />
<br />
===Assignment of enumeration values to method variables===<br />
Enumeration values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:<br />
<p class="code"> begin <br />
enumeration colour <br />
public <br />
value red <br />
value white <br />
value blue <br />
end public <br />
end enumeration <br />
%func is function getColour is enumeration colour<br />
local function getColour is enumeration colour <br />
return blue <br />
end function <br />
%func = getColour <br />
%func = (colour):red <br />
printText {~=%(Local):(%func)} <br />
end </p><br />
<br />
will produce this result:<br />
<br />
<p class="syntax"> %(Local):(%func)=red </p><br />
<br />
whereas previously this line: <br />
<br />
<p class="syntax"> %func = (colour):red </p> <br />
<br />
would have been rejected with this message:<br />
<br />
<p class="syntax">MSIR.0993: Assignment invalid: mismatch between method and method variable </p><br />
<br />
This change is enabled in V7.7 with the application of zap 77z128.<br />
<br />
===Optional output method parameters===<br />
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:<br />
<p class="code">function getRemote( -<br />
%target is string len 32, %errorReason is string len 80 optional output -<br />
) is float<br />
...<br />
</p><br />
In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string will determine truncation behavior.<br />
<br />
==External Call Facility enhancements==<br />
===Managing ECF tables more efficiently===<br />
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.<br />
<br />
The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.<br />
<br />
The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:<br />
<br />
<p class="syntax">EXTERNAL REMOVE <span class="term">modulename</span></p><br />
<br />
This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.<br />
<br />
An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).<br />
<br />
==System enhancements==<br />
<br />
===New wait types for daemon/master waits===<br />
<br />
Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:<br />
<br />
<code>57</code> - Means a daemon thread waiting for its master thread <br /> <br />
<code>58</code> - Means a master thread waiting for one of its daemon threads<br />
<br />
This change is enabled in V7.7 with the application of zap 77z410.<br />
<br />
===Snap formatting changes===<br />
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in Julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as: <br />
<br />
<p class="syntax">SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 </p><br />
<br />
whereas the same snap header under v7.8 would show as: <br />
<br />
<p class="syntax">SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 </p><br />
<br />
Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same <var>SNAPCTL</var> settings.<br />
<br />
===Call stack trace for problem diagnosis===<br />
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following: <br />
<ul><br />
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li><br />
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. <p>(<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)</p><br />
</li><br />
</ul> <br />
<br />
The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.<br />
<br />
====Variable too small for result====<br />
When the stack trace is enabled, a "variable too small" error results in the following message:<br />
<br />
<p class="syntax">M204.2966: Error at line n, procedure ''procname'' in file ''procfile''</p><br />
<br />
which identifies the line within a procedure where the error is occurring, in addition to the usual message:<br />
<br />
<p class="syntax">M204.0552: Variable too small for result</p><br />
<br />
Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:<br />
<p class="syntax"> M204.0552: Variable too small for result <br />
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC <br />
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC<br />
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC<br />
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC </p><br />
<br />
This information should help in diagnosing the problem. <br />
<br />
If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:<br />
<p class="syntax"> M204.0552: Variable too small for result <br />
M204.2967: Error at line 14 of command level program <br />
M204.2967: Called from line 5 of command level program<br />
M204.2967: Called from line 3 of command level program </p><br />
<br />
If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:<br />
<p class="syntax"> M204.0552: Variable too small for result <br />
M204.2968: Error: no debug info </p><br />
<br />
====MBSCAN exceeded====<br />
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records. <br />
<p>Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:</p><br />
<p class="syntax">M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''</p><br />
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:<br />
<p class="syntax">Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''</p><br />
<br />
where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:<br />
<p class="syntax"> b <br />
call sub1 <br />
sub1: subroutine <br />
fd1: <br />
in clients fd city = ONTARIO<br />
end find <br />
fr fd1 <br />
pai <br />
print <br />
end for <br />
end subroutine <br />
end </p><br />
<br />
then the following messages are produced, assuming any prompts are responded to with an 'N':<br />
<p class="syntax"> M204.0569: File CLIENTS, Find: Table B records to be searched = 3415<br />
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415 <br />
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC<br />
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC </p><br />
<br />
===appendJournalData===<br />
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.<br />
<br />
Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.<br />
<br />
==AUDIT204 enhancements==<br />
===FORMAT command===<br />
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.<br />
<p><b>NOTE:</b> This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.</p><br />
For example:<br />
<p class="syntax">//CCAIN DD *<br />
FORMAT YEARFORM 4<br />
TIMEHH<br />
TYPE ER MS LI</p><br />
<br />
==Recovery enhancements==<br />
===Media Recovery in a multi-user environment===<br />
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.<br />
<br />
==Security enhancements==<br />
===CA-Top Secret can disallow CCASTAT logins===<br />
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.<br />
<br />
===CUSTOM=11 and mixed cased input===<br />
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter <var>CUSTOM=11</var> setting no longer requires that a <var>*LOWER</var> command be issued prior to a <var>LOGCTL</var> command (to add or change a password) to preserve mixed case input. Prior to this release, with <var>CUSTOM=11</var> in place, *LOWER had to be issued before a <var>LOGCTL</var> command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.<br />
<br />
===DEFUSER can specify a jobname not authorized to access M204===<br />
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname (the owning id for the ONLINE job) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed (previously such a LOGON would have failed). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL. This in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.<br />
<br />
==Janus product enhancements==<br />
<br />
===Web Sockets===<br />
Web Sockets are now supported in Janus Web Server.<br />
<br />
The Web Socket protocol provides various advantages over the HTTP protocol:<br />
<ul><br />
<li>Web Sockets allow full-duplex communication.</li> <br />
<li>Efficient framing of payload data uses minimal overhead.</li> <br />
<li>The Web Socket protocol is end-user extensible.</li> <br />
<li>Most importantly, Web Sockets can be deployed completely within an existing HTTP/HTTPS framework.</li> <br />
</ul><br />
<br />
To implement Web Sockets, you must enable the Janus Web port for Web Socket upgrades with the new <var>WEBSOCKET</var> parameter. The WEBSOCKET option can be specified on either the port definition or the JANUS WEB rule for the URL. <br />
Likewise, an individual Janus Web rule can either allow or disallow Web Socket connections with the <var>WEBSOCKET</var> and <var>NOWEBSOCKET</var> parameters, respectively. <br />
<br />
For details on implementing Web Sockets, see the [[WebSocket_(Socket_function)|WebSocket]] wiki page.<br />
<br />
===Janus Web Server access rule===<br />
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed <i>for non-SSL ports</i> to the following:<br />
<p class="code">JANUS WEB <i>portname</i> DISALLOW *<br />
</p><br />
<p><br />
This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.<br />
The rule applies unless overridden by user-added rules. <br />
</p><br />
<blockquote class="note"><br />
<p><b>Note:</b> To revert from this change in the JANUS DEFINE default and make the default <br />
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: </p><br />
<p class="code">RESET WEBDFLT=1</p><br />
</blockquote><br />
<br />
===Increase in pending accepts for Janus BPX ports===<br />
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message<br />
<br />
<p class="code">MSIR.0019 Connection request rejected for port (port), MAXCON exceeded</p><br />
<br />
The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value is enabled in V7.7 with the application of zap 77z269.<br />
<br />
===TCP listen backlog increased===<br />
<br />
The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.<br />
<br />
This update tells the TCP stack to queue up a maximum of 1024 such requests before dropping any. This increased backlog reduces, or in most cases eliminates, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change is enabled in V7.7 with the application of zap 77z340.<br />
<br />
===Defer the freeing of XMLSCREEN input XML===<br />
<br />
The freeing of <var>[[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]]</var> input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis. <br />
<br />
Prior to this release the XML received from the client was freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.<br />
<br />
This change is enabled in V7.7 with the application of zap 77z368.<br />
<br />
===XMLSCREEN and Janus Web Legacy blank stripping===<br />
<br />
xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).<br />
<br />
This change is enabled in V7.7 with the application of zap 77z400.<br />
<br />
===SSL input buffer size===<br />
<br />
The default value of <var>[[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]]</var> has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use <var>[[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]]</var>. <br />
<br />
This change is enabled in V7.7 with the application of zap 77z415.<br />
<br />
===Increasing LDAP buffers===<br />
<br />
The number of LDAP buffers allocated at startup can now be changed by setting the <var>NLDAPBUF</var> parameter in CCAIN. See below for details on <var>[[#NLDAPBUF|NLDAPBUF]]</var>.<br />
<br />
===Increase URL length returned with $web_form_action===<br />
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.<br />
<br />
===Maximum RBSIZE setting increased===<br />
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.<br />
<br />
==Debugger enhancements==<br />
These enhancements apply to the Janus and TN3270 debuggers. <br />
<br />
===Access to exposed variables===<br />
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. This feature is enabled in V7.7 with the application of zap 77z363.<br />
<br />
===Subroutine or method display===<br />
When execution pauses for a break point or runtime error, the subroutine or method being executed is indicated in the status area. In addition, the source code line information available by right-clicking on a source line now also indicates the subroutine or method.<br />
<br />
==Performance enhancements==<br />
<br />
===MP/204 offload improvements===<br />
Application code issuing the following SOUL statements will now now be fully offloadable:<br />
<ul><br />
<li><var>File Records In/On</var></li><br />
<li><var>Remember</var></li> <br />
<li><var>Position</var></li><br />
<li><var>Sort Values</var></li> <br />
<li><var>Reset Header/Trailer</var></li><br />
<li><var>Find and Print Count</var></li><br />
<li><var>Find All Values</var></li><br />
<li><var>For Each Value</var></li><br />
</ul><br />
The above improvements are enabled in V7.7 with the application of zaps 77z419 and 77z420.<br />
<br />
===X3270OUT exit offloadable===<br />
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change is enabled in V7.7 with the application of zap 77z313.<br />
<br />
The X3270OUT exit must be written to be re-entrant.<br />
<br />
==New and changed commands==<br />
===DISPLAY ECF===<br />
<p class="code">DISPLAY ECF {{ M | N | U } like ?} </p><br />
<br />
This new command displays details from ECF tables, or the current status of users accessing ECF modules.<br />
<br />
<code>D ECF M</code> displays the contents of the module table. For example:<p class="code"> D ECF M <br />
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags <br />
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001 <br />
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001 <br />
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001 <br />
</p><br />
(flags may be D=deleted; S=shared; H=halted; I=Idle)<br />
<br />
<code>D ECF N</code> displays contents of the name table. For example: <p class="code"> D ECF N<br />
Module Logical-call-name <br />
QATUM13C MOD_QATUM13C <br />
QATUM13B MOD_QATUM13B <br />
QATUM13A MOD_QATUM13A </p><br />
<br />
<code>D ECF U</code> displays details of users currently accessing ECF modules. This is also the default option, and so <code>D ECF</code> will display the same output as <code>D ECF U</code>. For example:<br />
<p class="code"> D ECF U <br />
User# Userid Module Parmlen <br />
00002 ADMIN --none-- <br />
00003 ADMIN COBSAMP1 00000002<br />
00004 ADMIN COBSAMP1 00000002 </p><br />
<br />
<code>D ECF <var class="term">function</var> LIKE <var class="term">?</var> </code> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:<br />
<br />
<p class="code">D ECF U L A</p><br />
or<br />
<p class="code">D ECF U L A*</p><br />
<br />
displays details of ECF users whose names begin with A.<br />
<br />
===REGENERATE===<br />
The <var>[[REGENERATE command|REGENERATE]]</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:<br />
<p class="code"> REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]<br />
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th] <br />
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]</p><br />
<br />
The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:<br />
<p class="code"> ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2<br />
REGENERATE USING REGEN1 FILE TEST</p><br />
<br />
It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:<br />
<p class="code"> M204.1430: Failed to open file TEST<br />
M204.1436: Stopped processing file TEST </p><br />
<br />
$STATUS will now be set for <var>REGENERATE</var> with the following values:<br />
<blockquote> <br />
0 - Success <br/><br />
1 - No files were processed <br/><br />
2 - At least one file stopped processing <br/><br />
4 - A serious error occurred, REGEN failed <br />
</blockquote><br />
<br />
Similarly, <var>[[SETGRC command|SETGRC]]</var> may be used to get the return code and error message.<br />
<br />
==New and changed parameters==<br />
<br />
===ECMODS===<br />
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.<br />
<br />
===ECNAMES===<br />
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.<br />
<br />
===ECPSIZE===<br />
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.<br />
<br />
===ENQTIME===<br />
Millisecond duration of automatic record locking retry wait.<br />
<br />
Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance. <br />
<br />
The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. <var>ENQTIME</var> can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of <var>ENQTIME</var> is 3000 (3 seconds). <br />
<br />
For example, with <code>ENQTIME = 100</code> and <code>ENQRETRY = 7</code>, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request. <br />
<br />
The <var>ENQTIME</var> parameter may also be reset with $ResetN. <br />
<br />
This new parameter is enabled in V7.7 with the application of zap 77z299.<br />
<br />
===EVALOPT===<br />
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."<br />
<br />
For example, with the default of 0 in place, the following code <p class="code"> %x is string len 1 <br />
%y is string len 2 <br />
%y = 'ab' <br />
%x = %y <br />
printtext {~} = {%x} </p><br />
<br />
would cause silent truncation, and give the result<br />
<p class="code">%x = a </p><br />
<br />
If <var>EVALOPT</var> is set to 1, then the above code produces the following message:<br />
<p class="code">M204.0552: Variable too small for result </p><br />
<br />
and the request is cancelled.<br />
<br />
===LFSCB===<br />
<var>LFSCB</var>, the length of the full screen buffer, now has a new minimum value of 8 (the previous minimum was 0). This change is enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.<br />
<br />
===MAXPRE, MAXBOUT, MAXSUBT===<br />
<p>Introduced in zap 77z257.</p><br />
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set. <br />
<ul><br />
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li><br />
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li><br />
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul><br />
<br />
<p>Each new parameter defaults to unlimited. </p><br />
<p>If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:</p><br />
<p class="code">M204.0524: Maximum number (<i>num</i>) of <i>parameter</i> exceeded.</p><br />
where <i>num</i> is the value set for <i>parameter</i> (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).<br />
<br />
===NLDAPBUF===<br />
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.<br />
<br />
===PUPDTH (new minimum value)===<br />
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.<br />
<br />
===SERV4G===<br />
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is <code>X'FFFFF000'</code>, each ATB server will begin at <code>XX_FFFFF000</code>. If <var>SERV4G</var> is <code>X'FFFF0000'</code>, each ATB server will begin at <code>XX_FFFF0000</code>. <code>XX</code> is determined by the storage available on the system. The parameter is set in CCAIN.<br />
<br />
The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter.<br />
<br />
For example, if you want VTBL to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200 (6400 bytes, X'1900')</code>. This will force each server's VTBL to begin at <code>XX_FFFFF000</code> and end at <code>XX+1_00000900</code>.<br />
===SIRTERM===<br />
The <var>[[SIRTERM parameter|SIRTERM]]</var> (Sirius terminal options) parameter settings have changed. <br />
The changes to <var>SIRTERM</var> allow a user to preclude a reset to a Model that is not supported by the terminal emulator in use.<br />
<br />
The X'01' setting (MODEL 6 support) is no longer used. <br />
<br />
The X'02' setting (Write Structured Field Query Support) now supports MODEL 6 terminals by default. <br />
<br />
The new X'08' setting always issues a Write Structured Field Query for Terminal Model Resets for terminals connected to Model 204 through VTAM or TELNET. This precludes Terminal Model RESETs to Models that are not supported by the terminal emulator in use.<br />
<br />
===WEBDFLT===<br />
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. This new parameter is enabled in V7.7 with the application of zap 77z090. <br />
<br />
<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need <var>WEBDFLT=1</var>, as in the CCAIN input stream.<br />
<br />
==New and changed statistics==<br />
===MPR, MBO, MCP, and RCV===<br />
Introduced in zap 77z257.<br />
<p>These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)</p><br />
<p>They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. </p><br />
<br />
User/system statistics:<br />
<ul><br />
<li>MPR: High water mark of transaction pre-images. </li><br />
<li>MBO: High water mark of transaction backout pages. </li><br />
<li>MCP: High water mark of transaction chkpoint spans. </li><br />
</ul><br />
System statistics: <br />
<ul><br />
<li>RCV: Number of blocks needed for subtransaction recovery </li><br />
</ul> <br />
<p class="note"><b>Notes:</b> M204.0843 now displays the RCV statistic for subtransaction checkpoints.<br />
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].<br />
</p><br />
===DKWTS and DKWTMICS===<br />
Introduced in zap 77z7289.<br />
<p>The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.</p><br />
<br />
DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds. <br />
<br />
<p class="note"><b>Notes:</b> <br />
<ul><br />
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li> <br />
<br />
<li>DKWTS and DKWTMICS are not available in SirMon; use <var>[[MONITOR_command|MONITOR]] SYSTEM STATISTICS</var> to view these statistics.</li></ul> </p><br />
<br />
==Compatibility issues==<br />
===<b id="listNewInit"></b>$ListNew cannot be used in Initial clause===<br />
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a <br />
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].<br />
<p>This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.</p><br />
<br />
<blockquote class="note"><b>Note:</b> Strictly speaking, this would not be considered a compilation error, because previously although <code>..&nbsp;Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$List<i>xxx</i></var> invocation.</blockquote><br />
<br />
===Restricting the use of the CUSTOM=38 setting===<br />
The <var>[[CUSTOM parameter|CUSTOM=38]]</var> parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the <var>RESET</var> command. This <var>CUSTOM</var> setting is now restricted to the <var>RESET</var> of the <var>LAUDIT</var> parameter.<br />
<br />
===Disabling of Closure support===<br />
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.<br />
<br />
===Password delimiter enforced===<br />
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example: <br />
<br />
<p class="code">CALL IFSTRTN(RC,'logonid;password;'...)</p><br />
<br />
If a semicolon does not follow the password string, the following message will now be issued:<br />
<br />
<p class="code">M204.2964: Password missing or too long </p> <br />
<br />
Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.<br />
<br />
This change is enabled in V7.7 with the application of zap 77z231.<br />
<br />
===PAGESZ parameter validated===<br />
Previously it was possible to set the <var>PAGESZ</var> parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.<br />
<br />
===ECPRIV and the IDCAMS facility===<br />
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of <var>ECPRIV</var>, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile. <br />
<br />
The <var>ECPRIV</var> 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the <var>ECPRIV</var> 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the <var>ECFPRIV</var> 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.<br />
<br />
===TCPOPTS is view-only===<br />
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resettable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:<br />
<br />
<p class="code> M204.1123: Parameter TCPOPTS not reset</p><br />
<br />
===ZHPF command can only be issued by a system manager===<br />
In previous versions it was possible to issue the <var>ZHPF</var> command without being logged on. From this release onwards, a user must be logged on with system manager privileges in order to issue this command.<br />
<br />
Additionally, the command output will now only display results for currently open files.<br />
<br />
This change is enabled in v7.7 with the application of zap 77z264.<br />
<br />
===Terminal MODEL reset failure===<br />
If a reset of the terminal <var>MODEL</var> parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:<br />
<p class="code> M204.1875 UNABLE TO RESET MODEL TO %C <br />
M204.1123: Parameter MODEL not reset</p> <br />
<br />
the following message will now be issued:<br />
<br />
<p class="code> M204.1008: LOUTPB must be increased to at least <number> </p><br />
<br />
where <number> is the minimum value of <var>LOUTPB</var> necessary to support the terminal model.<br />
<br />
This change is enabled in V7.7 with the application of zap 77z309.<br />
<br />
==Notes for system manager and installer==<br />
===CRAM SVC installation is deprecated===<br />
The CRAM SVC installation has been deprecated as of version 7.5. <br />Installation of CRAM-XDM is described as part of the [[Model 204 installation]].<br />
===Authorization and maintenance zaps===<br />
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.<br />
<br />
==New and changed messages==<br />
<br />
See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.<br />
<br />
<br />
[[Category: Release notes]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=MediaWiki:Vector.css&diff=116991MediaWiki:Vector.css2018-09-26T01:21:48Z<p>Admin: add #ca-unwatch.icon a setting to match existing #ca-watch.icon a</p>
<hr />
<div>/* CSS placed here will affect users of the Vector skin */<br />
<br />
<br />
/* needed to keep content border top from extending too far left */<br />
div#mw-head-base { <br />
margin-left: 11.5em; /* for Vector centering project */<br />
}<br />
<br />
/* for view history items - less wrapping from Vector centering */<br />
ul#pagehistory {<br />
font-size: .8em;<br />
}<br />
<br />
/* line height of items in diff of history pg */<br />
table.diff {<br />
line-height: 1.2; /* was 1.6 */<br />
}<br />
<br />
/* needed to keep content border bottom from extending too far left */<br />
div#footer { <br />
margin-left: 11em; <br />
}<br />
<br />
/* move sidebar items to left */ <br />
div#mw-panel.collapsible-nav .portal {<br />
margin-left: 1px;<br />
}<br />
<br />
#p-logo { <br />
width: 11em; <br />
}<br />
<br />
/* next to give headings greater distinction -- slightly bolder, slightly larger */ <br />
<br />
div#mw-panel div.portal h3 { <br />
font-size: .80em;<br />
font-weight: 600;<br />
}<br />
<br />
<br />
/* ************************************************* */<br />
/* add origami bar for h1, color change for h2, and make room for new logo */<br />
.mw-body h1 {<br />
color: #050D9E;<br />
font-family: Arial, Helvetica, sans-serif;<br />
background-image: url(images/4/4c/OrigamiBar_87.png);<br />
background-repeat: no-repeat;<br />
background-position: left bottom;<br />
border-bottom: none;<br />
height: 100%;<br />
}<br />
<br />
.mw-body h2 { <br />
font-family: Arial, Helvetica, sans-serif;<br />
color: #000000;<br />
border-bottom: 2px solid #AAA;<br />
}<br />
<br />
div#content #firstHeading {<br />
padding-bottom: .75em;<br />
margin-bottom: 1em;<br />
}<br />
<br />
/* prep for new logo */<br />
div#mw-panel {<br />
top: 100px;<br />
}<br />
<br />
div#p-logo {<br />
top:-125px;<br />
left:-15px;<br />
}<br />
<br />
/* change/move logo (LocalSettings.php names logo file) */<br />
div#p-logo a {<br />
height:110px;<br />
width:11em;<br />
}<br />
<br />
/* ************************************************* */<br />
/* Web team changes */<br />
<br />
/* move, enlarge, change color & font of top row of links */<br />
div#p-personal {<br />
top:9px;<br />
font-family: 'Open Sans', sans-serif;<br />
}<br />
<br />
div#p-personal ul li {<br />
font-size:1em;<br />
margin-left:2em;<br />
}<br />
<br />
div#p-personal ul li a, <br />
div#p-personal ul li a:visited, <br />
div#p-personal ul li a.new, <br />
div#p-personal ul li a.new.visited {<br />
color:#000000;<br />
}<br />
<br />
div#mw-head {<br />
top:1em;<br />
}<br />
<br />
div#mw-head-base {<br />
height:7em;<br />
}<br />
<br />
/* space bet top links and row of tabs below */<br />
#left-navigation {<br />
margin-top:3.5em;<br />
}<br />
<br />
#right-navigation {<br />
margin-top:3.5em;<br />
}<br />
<br />
/* ************************************************* */<br />
<br />
/* changes to reduce excess height of tabs (overwrites some of above) */<br />
div#mw-head-base {<br />
height:6.5em;<br />
}<br />
<br />
div.vectorTabs {<br />
height:2em;<br />
}<br />
<br />
div.vectorTabs span a {<br />
padding-top:1em;<br />
}<br />
<br />
div.vectorTabs ul li {<br />
line-height:.7em;<br />
}<br />
<br />
div.vectorTabs li a {<br />
height:1.5em;<br />
}<br />
<br />
#ca-watch.icon a, #ca-unwatch.icon a {<br />
padding-top:2.4em;<br />
}<br />
<br />
div#mw-head div.vectorMenu h3 {<br />
height:2em;<br />
}<br />
<br />
div.vectorMenu h3 span {<br />
font-size:.8em; <br />
padding-top:1em;<br />
}<br />
<br />
div.vectorMenu h3 a {<br />
height:2.3em;<br />
}<br />
<br />
div#p-search form {<br />
margin-top:.2em;<br />
}<br />
<br />
div#simpleSearch {<br />
height:1.4em;<br />
margin-top:0;<br />
}<br />
<br />
div#simpleSearch input#searchInput {<br />
padding-top:.25em;<br />
font-size:.85em;<br />
}<br />
<br />
/* **************************************************************** */<br />
<br />
<br />
/* added to accommodate M'wiki changes between v23 and v28 */<br />
<br />
code {<br />
border:0px none; <br />
padding:0px; <br />
color:inherit;<br />
}</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=MediaWiki:Vector.css&diff=116990MediaWiki:Vector.css2018-09-25T23:39:43Z<p>Admin: test padding-left for #ca-unwatch.icon</p>
<hr />
<div>/* CSS placed here will affect users of the Vector skin */<br />
<br />
<br />
/* needed to keep content border top from extending too far left */<br />
div#mw-head-base { <br />
margin-left: 11.5em; /* for Vector centering project */<br />
}<br />
<br />
/* for view history items - less wrapping from Vector centering */<br />
ul#pagehistory {<br />
font-size: .8em;<br />
}<br />
<br />
/* line height of items in diff of history pg */<br />
table.diff {<br />
line-height: 1.2; /* was 1.6 */<br />
}<br />
<br />
/* needed to keep content border bottom from extending too far left */<br />
div#footer { <br />
margin-left: 11em; <br />
}<br />
<br />
/* move sidebar items to left */ <br />
div#mw-panel.collapsible-nav .portal {<br />
margin-left: 1px;<br />
}<br />
<br />
#p-logo { <br />
width: 11em; <br />
}<br />
<br />
/* next to give headings greater distinction -- slightly bolder, slightly larger */ <br />
<br />
div#mw-panel div.portal h3 { <br />
font-size: .80em;<br />
font-weight: 600;<br />
}<br />
<br />
<br />
/* ************************************************* */<br />
/* add origami bar for h1, color change for h2, and make room for new logo */<br />
.mw-body h1 {<br />
color: #050D9E;<br />
font-family: Arial, Helvetica, sans-serif;<br />
background-image: url(images/4/4c/OrigamiBar_87.png);<br />
background-repeat: no-repeat;<br />
background-position: left bottom;<br />
border-bottom: none;<br />
height: 100%;<br />
}<br />
<br />
.mw-body h2 { <br />
font-family: Arial, Helvetica, sans-serif;<br />
color: #000000;<br />
border-bottom: 2px solid #AAA;<br />
}<br />
<br />
div#content #firstHeading {<br />
padding-bottom: .75em;<br />
margin-bottom: 1em;<br />
}<br />
<br />
/* prep for new logo */<br />
div#mw-panel {<br />
top: 100px;<br />
}<br />
<br />
div#p-logo {<br />
top:-125px;<br />
left:-15px;<br />
}<br />
<br />
/* change/move logo (LocalSettings.php names logo file) */<br />
div#p-logo a {<br />
height:110px;<br />
width:11em;<br />
}<br />
<br />
/* ************************************************* */<br />
/* Web team changes */<br />
<br />
/* move, enlarge, change color & font of top row of links */<br />
div#p-personal {<br />
top:9px;<br />
font-family: 'Open Sans', sans-serif;<br />
}<br />
<br />
div#p-personal ul li {<br />
font-size:1em;<br />
margin-left:2em;<br />
}<br />
<br />
div#p-personal ul li a, <br />
div#p-personal ul li a:visited, <br />
div#p-personal ul li a.new, <br />
div#p-personal ul li a.new.visited {<br />
color:#000000;<br />
}<br />
<br />
div#mw-head {<br />
top:1em;<br />
}<br />
<br />
div#mw-head-base {<br />
height:7em;<br />
}<br />
<br />
/* space bet top links and row of tabs below */<br />
#left-navigation {<br />
margin-top:3.5em;<br />
}<br />
<br />
#right-navigation {<br />
margin-top:3.5em;<br />
}<br />
<br />
/* ************************************************* */<br />
<br />
/* changes to reduce excess height of tabs (overwrites some of above) */<br />
div#mw-head-base {<br />
height:6.5em;<br />
}<br />
<br />
div.vectorTabs {<br />
height:2em;<br />
}<br />
<br />
div.vectorTabs span a {<br />
padding-top:1em;<br />
}<br />
<br />
div.vectorTabs ul li {<br />
line-height:.7em;<br />
}<br />
<br />
div.vectorTabs li a {<br />
height:1.5em;<br />
}<br />
<br />
#ca-watch.icon a {<br />
padding-top:2.4em;<br />
}<br />
<br />
div#mw-head div.vectorMenu h3 {<br />
height:2em;<br />
}<br />
<br />
div.vectorMenu h3 span {<br />
font-size:.8em; <br />
padding-top:1em;<br />
}<br />
<br />
div.vectorMenu h3 a {<br />
height:2.3em;<br />
}<br />
<br />
div#p-search form {<br />
margin-top:.2em;<br />
}<br />
<br />
div#simpleSearch {<br />
height:1.4em;<br />
margin-top:0;<br />
}<br />
<br />
div#simpleSearch input#searchInput {<br />
padding-top:.25em;<br />
font-size:.85em;<br />
}<br />
<br />
/* **************************************************************** */<br />
<br />
<br />
/* added to accommodate M'wiki changes between v23 and v28 */<br />
<br />
code {<br />
border:0px none; <br />
padding:0px; <br />
color:inherit;<br />
}</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=MediaWiki:Vector.css&diff=116989MediaWiki:Vector.css2018-09-25T23:32:13Z<p>Admin: test padding-left for #ca-unwatch.icon</p>
<hr />
<div>/* CSS placed here will affect users of the Vector skin */<br />
<br />
<br />
/* needed to keep content border top from extending too far left */<br />
div#mw-head-base { <br />
margin-left: 11.5em; /* for Vector centering project */<br />
}<br />
<br />
/* for view history items - less wrapping from Vector centering */<br />
ul#pagehistory {<br />
font-size: .8em;<br />
}<br />
<br />
/* line height of items in diff of history pg */<br />
table.diff {<br />
line-height: 1.2; /* was 1.6 */<br />
}<br />
<br />
/* needed to keep content border bottom from extending too far left */<br />
div#footer { <br />
margin-left: 11em; <br />
}<br />
<br />
/* move sidebar items to left */ <br />
div#mw-panel.collapsible-nav .portal {<br />
margin-left: 1px;<br />
}<br />
<br />
#p-logo { <br />
width: 11em; <br />
}<br />
<br />
/* next to give headings greater distinction -- slightly bolder, slightly larger */ <br />
<br />
div#mw-panel div.portal h3 { <br />
font-size: .80em;<br />
font-weight: 600;<br />
}<br />
<br />
<br />
/* ************************************************* */<br />
/* add origami bar for h1, color change for h2, and make room for new logo */<br />
.mw-body h1 {<br />
color: #050D9E;<br />
font-family: Arial, Helvetica, sans-serif;<br />
background-image: url(images/4/4c/OrigamiBar_87.png);<br />
background-repeat: no-repeat;<br />
background-position: left bottom;<br />
border-bottom: none;<br />
height: 100%;<br />
}<br />
<br />
.mw-body h2 { <br />
font-family: Arial, Helvetica, sans-serif;<br />
color: #000000;<br />
border-bottom: 2px solid #AAA;<br />
}<br />
<br />
div#content #firstHeading {<br />
padding-bottom: .75em;<br />
margin-bottom: 1em;<br />
}<br />
<br />
/* prep for new logo */<br />
div#mw-panel {<br />
top: 100px;<br />
}<br />
<br />
div#p-logo {<br />
top:-125px;<br />
left:-15px;<br />
}<br />
<br />
/* change/move logo (LocalSettings.php names logo file) */<br />
div#p-logo a {<br />
height:110px;<br />
width:11em;<br />
}<br />
<br />
/* ************************************************* */<br />
/* Web team changes */<br />
<br />
/* move, enlarge, change color & font of top row of links */<br />
div#p-personal {<br />
top:9px;<br />
font-family: 'Open Sans', sans-serif;<br />
}<br />
<br />
div#p-personal ul li {<br />
font-size:1em;<br />
margin-left:2em;<br />
}<br />
<br />
div#p-personal ul li a, <br />
div#p-personal ul li a:visited, <br />
div#p-personal ul li a.new, <br />
div#p-personal ul li a.new.visited {<br />
color:#000000;<br />
}<br />
<br />
div#mw-head {<br />
top:1em;<br />
}<br />
<br />
div#mw-head-base {<br />
height:7em;<br />
}<br />
<br />
/* space bet top links and row of tabs below */<br />
#left-navigation {<br />
margin-top:3.5em;<br />
}<br />
<br />
#right-navigation {<br />
margin-top:3.5em;<br />
}<br />
<br />
/* ************************************************* */<br />
<br />
/* changes to reduce excess height of tabs (overwrites some of above) */<br />
div#mw-head-base {<br />
height:6.5em;<br />
}<br />
<br />
div.vectorTabs {<br />
height:2em;<br />
}<br />
<br />
div.vectorTabs span a {<br />
padding-top:1em;<br />
}<br />
<br />
div.vectorTabs ul li {<br />
line-height:.7em;<br />
}<br />
<br />
div.vectorTabs li a {<br />
height:1.5em;<br />
}<br />
<br />
#ca-watch.icon a {<br />
padding-top:2.4em;<br />
}<br />
<br />
#ca-unwatch.icon a {<br />
padding-left:1em;<br />
}<br />
<br />
div#mw-head div.vectorMenu h3 {<br />
height:2em;<br />
}<br />
<br />
div.vectorMenu h3 span {<br />
font-size:.8em; <br />
padding-top:1em;<br />
}<br />
<br />
div.vectorMenu h3 a {<br />
height:2.3em;<br />
}<br />
<br />
div#p-search form {<br />
margin-top:.2em;<br />
}<br />
<br />
div#simpleSearch {<br />
height:1.4em;<br />
margin-top:0;<br />
}<br />
<br />
div#simpleSearch input#searchInput {<br />
padding-top:.25em;<br />
font-size:.85em;<br />
}<br />
<br />
/* **************************************************************** */<br />
<br />
<br />
/* added to accommodate M'wiki changes between v23 and v28 */<br />
<br />
code {<br />
border:0px none; <br />
padding:0px; <br />
color:inherit;<br />
}</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=MediaWiki:Common.css&diff=116786MediaWiki:Common.css2018-09-06T23:15:13Z<p>Admin: add divider</p>
<hr />
<div>/* CSS placed here will be applied to all skins */<br />
/* See also MediaWiki:Vector.css, MediaWiki:MonoBook.css, <br />
/* MediaWiki:Modern.css */<br />
<br />
/* *** NOTE: MANY SKIN TWEAKS ARE SPECIFIED IN MediaWiki:Vector.css *** /*<br />
<br />
/* following comment won't work for IE>9 */<br />
<!-[if gte IE8]<br />
<linkrel=”stylesheet” type=”text/css” href=”/stylesheets/standards.css”/><br />
<![endif]-><br />
<br />
/* current practice is to use p class="code" instead of this pre tag */<br />
pre {<br />
overflow-x: auto; /* Use horizontal scroller if needed; for FF2, not needed in FF3 */<br />
overflow-y: hidden; /* overflow-x above messes up Chrome, this is the fix. Sigh */<br />
white-space: pre-wrap; /* css-3 */<br />
white-space: -moz-pre-wrap !important; /* Mozilla, since 1999 */<br />
white-space: -pre-wrap; /* Opera 4-6 */<br />
white-space: -o-pre-wrap; /* Opera 7 */ /*<br />
width: 99%; */<br />
word-wrap: break-word; /* Internet Explorer 5.5+ */<br />
}<br />
<br />
p.pre, p.code, p.codeInTable, p.output, p.syntax, p.syntaxUL, p.pre pre.syntax {<br />
color: #000;<br />
background-color: #f9f9f9;<br />
padding: 5px 5px 5px 10px;<br />
border: 1px dashed #4169E1;<br />
font-family: Consolas,"Liberation Mono",monospace;<br />
line-height: 1.2;<br />
vertical-align: baseline;<br />
white-space: pre; /* pre-wrap OK if IE>=11, but we want code not to wrap */<br />
overflow: auto; <br />
}<br />
<br />
p.codeInTable {<br />
border:0; <br />
padding:0;<br />
margin-top:0;<br />
font-family: Consolas,"Liberation Mono",monospace;<br />
}<br />
<br />
p.syntax {<br />
line-height: 1.35; <br />
}<br />
<br />
p.syntaxUL {<br />
line-height: 1.35; <br />
display: inline-block;<br />
}<br />
<br />
/* make bold in syntax larger */<br />
.syntax b {<br />
font-size: 105%;<br />
}<br />
<br />
p.syntaxUL~hr {<br />
height: 2px;<br />
margin: 2px 0;<br />
}<br />
<br />
span.squareb {<br />
font-size: 105%;<br />
font-weight: bold;<br />
color: black;<br />
}<br />
<br />
span.literal {<br />
font-style: normal;<br />
color: #501010;<br />
}<br />
<br />
span.term {<br />
font-style: italic;<br />
color: #000;<br />
}<br />
<br />
<br />
span.boldGreen {<br />
font-weight: bold;<br />
color: green;<br />
}<br />
<br />
/* for error-message page subtitle */<br />
span.msgtext {<br />
font-family: Arial, Helvetica, sans-serif; <br />
font-size:150%;<br />
line-height:1.5em;<br />
}<br />
<br />
/* the following tag is designed for the superscript star in Connect*; */<br />
/* HTML superscript tag (sup) makes star char (&#9733;) too large and lines displace */<br />
span.superstar, span.toctext span {<br />
font-size: .6em;<br />
vertical-align: baseline;<br />
position: relative;<br />
top: -0.5em;<br />
}<br />
<br />
.pageBreak { page-break-before: always; }<br />
<br />
<br />
/* table element variations *************************************************** */<br />
<br />
/* thJustBold for a table with non-heading <th>s bold but not italicized */<br />
/* also see tr.head, below */<br />
table, table.list table.thJustBold {<br />
margin: 1em 1em 1em 0;<br />
background: #f9f9f9;<br />
border: 1px #aaa solid;<br />
border-collapse: collapse;<br />
}<br />
th, td, .list th, .list td, .thJustBold th, .thJustBold td {<br />
border: 1px #aaa solid;<br />
padding: 0.5em;<br />
text-align: left;<br />
vertical-align: top;<br />
}<br />
<br />
td.bold {<br />
font-weight: bold;<br />
}<br />
<br />
/* JAL added explicit bkgrd color to preserve it in table column *headings* in a */ <br />
/* class=thJustBold table */<br />
tr.head > th {<br />
vertical-align: bottom;<br />
white-space: nowrap;<br />
font-style: normal;<br />
background: #f2f2f2;<br />
}<br />
<br />
th, .list th {<br />
font-style: italic;<br />
background: #f2f2f2;<br />
}<br />
<br />
/* if <th> in first columns in table *content* in a class thJustBold table, make sure */ <br />
/* tr class=head for column headings */<br />
.thJustBold th {<br />
font-style: normal;<br />
background: #f2f2f2;<br />
}<br />
<br />
th var, th var.term {<br />
font-weight: bold;<br />
font-size: 100%;<br />
color: black;<br />
}<br />
<br />
table.optionTable {<br />
margin: 0;<br />
border: none;<br />
border-collapse: collapse;<br />
}<br />
<br />
table.noBorder {<br />
margin: 0;<br />
border: none;<br />
border-collapse: collapse;<br />
background-color: transparent;<br />
}<br />
<br />
table.noBorder th, table.noBorder td {<br />
border: none;<br />
}<br />
<br />
table.nested {<br />
margin: 0;<br />
border: hidden;<br />
border-collapse: collapse;<br />
}<br />
<br />
table table.nested th {<br />
border: hidden;<br />
}<br />
<br />
/* following two tweaks tighten spacing for search result list items */<br />
table.gsc-table-result {<br />
margin: 0;<br />
}<br />
<br />
table.gsc-resultsHeader {<br />
display: none;<br />
}<br />
<br />
/* for the List of MSIR and M204 message tables ************* */<br />
/* more visible vertical borders & merges msg num w/ its text */<br />
table.msgList {<br />
border: 2px #aaa solid;<br />
}<br />
<br />
.msgList th {<br />
border-right-style:none;<br />
border-left:2px solid #aaa;<br />
font-style: normal;<br />
background: #f9f9f9;<br />
}<br />
<br />
.msgList td {<br />
border-left-style:none;<br />
}<br />
<br />
/* for SoftSpy message tables ****************************** */<br />
table.message {<br />
margin: 0;<br />
border: none;<br />
border-collapse: collapse;<br />
background-color: transparent;<br />
}<br />
<br />
table.message th {<br />
border: none;<br />
font-style: normal;<br />
white-space: nowrap;<br />
}<br />
<br />
table.message td {<br />
border: none;<br />
}<br />
<br />
table.message tr:first-child th {<br />
min-width: 7em;<br />
}<br />
<br />
table.message tr:first-child td {<br />
font-weight: bold;<br />
}<br />
<br />
table.message~hr {<br />
height: 2px;<br />
margin: 1em 0;<br />
}<br />
/* ******************************************************* */<br />
<br />
code, p.output {<br />
background-color: #F0F0F9;<br />
}<br />
<br />
var {<br />
font-style: normal;<br />
font-weight: bold;<br />
font-size: 95%;<br />
color: #555;<br />
}<br />
/* tentatively removed from above: text-transform: capitalize; */ <br />
<br />
/* link-within-var */<br />
var a:link {<br />
color: #5353EF;<br />
}<br />
<br />
var a:visited {<br />
color: #5353EF;<br />
}<br />
<br />
var.syntax {<br />
font-size: 100%;<br />
color: black;<br />
}<br />
<br />
var.term {<br />
text-transform: none;<br />
font-style: italic;<br />
font-weight: normal;<br />
font-size: 100%;<br />
color: black;<br />
}<br />
<br />
/* Sirius style was italic */<br />
var.product {<br />
text-transform: none;<br />
color: black;<br />
font-style: normal;<br />
font-weight: normal;<br />
font-size: 100%;<br />
}<br />
<br />
/* JAL added 04/13 */<br />
var.book {<br />
color: black;<br />
font-style: italic;<br />
font-weight: normal;<br />
font-size: 100%;<br />
}<br />
<br />
/* darker color used when font-style was italic */<br />
/* Otherwise product links are very faint */<br />
/* var.product a { color: #002bb8; } */<br />
<br />
var.camel {<br />
text-transform: none;<br />
}<br />
<br />
/* prevent break before parens for terms like %(System in IE and Chrome */<br />
var.nobr {<br />
white-space: pre;<br />
}<br />
<br />
pre var {<br />
font-weight: bold;<br />
}<br />
<br />
.pageSubtitle {<br />
font-size:120%;<br />
color:black;<br />
font-weight: bold;<br />
}<br />
<br />
a:visited {<br />
color: #002bb8;<br />
}<br />
<br />
/* The "normal" source of the #bodyContent styles is the monobook css file on lin875 */<br />
/* make links to non-wiki targets same color as non-var wiki links */<br />
#bodyContent a.external:link,<br />
#bodyContent a.external:visited {<br />
color: #002bb8;<br />
}<br />
<br />
.showVisit a:link {<br />
color: #002bb8;<br />
}<br />
.showVisit a:visited {<br />
color: #5a3696;<br />
}<br />
.showVisit a:hover {<br />
text-decoration: underline;<br />
}<br />
.showVisit a:active {<br />
color: #faa700;<br />
}<br />
.showVisit a.new, #p-personal a.new {<br />
color: #ba0000;<br />
}<br />
.showVisit a.new:visited, #p-personal a.new:visited {<br />
color: #a55858;<br />
}<br />
<br />
/* to caption a table, as child of a "table" tag */<br />
caption {<br />
font-weight: bold;<br />
font-size: 110%;<br />
padding-bottom: .6em;<br />
}<br />
<br />
/* use for fig (image) caption; as class for "p" tag; compare with "caption" above */<br />
/* use style="width:XXpx" on "p" tag to center precisely; XX is width of graphic */<br />
/* or use style="margin-right:XXem" to ctr a non-image manually; XX often around 15 */<br />
/* then "p class=figure" before the image & append image sz in its "File:" value */<br />
/* IE wraps caption if it is wider than the image */<br />
.caption, div#content p.caption {<br />
color: black;<br />
font-size: 100%;<br />
font-weight: bold;<br />
text-align: center;<br />
line-height: 100%;<br />
margin-left: 1.6em;<br />
margin-top: 2em;<br />
margin-bottom: 1.6em;<br />
}<br />
<br />
.figure, div#content p.figure {<br />
margin-left: 1.6em;<br />
margin-top: 1.6em;<br />
margin-bottom: 2em;<br />
}<br />
<br />
<br />
/* enclose non-single-paragraph Notes with blockquote class="note". */<br />
/* Otherwise, use p class="note" */<br />
/* use noteN class to automatically get a bolded "Note:" term */<br />
.note, div#content p.note, .noteN, div#content p.noteN {<br />
margin-left: 15px;<br />
margin-right: 30px;<br />
border: none;<br />
padding: 0px;<br />
}<br />
<br />
/* auto-provision of bold text "Note:" */<br />
.noteN:before {<br />
content: "Note: ";<br />
font-weight: bold;<br />
}<br />
<br />
<br />
li *.note, td *.note, th *.note, li *.noteN, td *.noteN, th *.noteN {<br />
margin-left: 10px;<br />
margin-right: 30px;<br />
border: none;<br />
padding: 0px;<br />
}<br />
<br />
/* enclose non-single-paragraph Cautions & Warnings with blockquote class="warn". */<br />
/* Otherwise, use p class="warn" */<br />
.warn, div#content p.warn {<br />
margin-left: 20px;<br />
margin-right: 60px;<br />
margin-top: 1em;<br />
margin-bottom: 1em;<br />
text-align: justify;<br />
border-top: 1px solid #000;<br />
border-bottom: 1px solid #000;<br />
padding: 5px 5px 5px 10px;<br />
}<br />
<br />
/* used by message on Sirius $function pgs; consider .warn class (above) instead */<br />
.warning {<br />
color: #990000;<br />
font-style: italic;<br />
}<br />
<br />
.smallAndTightList {<br />
line-height: 1.3;<br />
}<br />
<br />
ul.nobul li {<br />
list-style-type: none;<br />
list-style-image: none;<br />
margin-left: 0;<br />
}<br />
<br />
ul.nobulnoindent li {<br />
list-style-type: none;<br />
list-style-image: none;<br />
margin-left: 0;<br />
text-indent: -1.5em;<br />
}<br />
<br />
/* square bullets for lower-level nested lists */<br />
ul li ul {<br />
list-style-type:square;<br />
list-style-image: none;<br />
}<br />
<br />
/* HTML for types of ordered list doesn't work in wiki, hence the following CSS */<br />
ol.low-al li {<br />
list-style-type:lower-alpha;<br />
}<br />
<br />
<br />
/** * Allow limiting of which header levels are shown in a TOC;<br />
* <div class="toclimit-3">, for instance, will limit to<br />
* showing ==headings== and ===headings=== but no further.<br />
* Used in [[Template:TOCright]]; see MediaWiki's Template:TOC page<br />
*/<br />
<br />
.toclimit-2 .toclevel-1 ul,<br />
.toclimit-3 .toclevel-2 ul,<br />
.toclimit-4 .toclevel-3 ul,<br />
.toclimit-5 .toclevel-4 ul,<br />
.toclimit-6 .toclevel-5 ul,<br />
.toclimit-7 .toclevel-6 ul {<br />
display: none; <br />
}<br />
<br />
/* selectively suppress TOC numbering -- put TOC within div class=autonum */<br />
.noautonum .tocnumber { <br />
display: none; <br />
}<br />
<br />
/* add top space to TOC */<br />
div#toc.toc {<br />
margin-top:1em;<br />
}<br />
<br />
/* squeeze footer list items a bit to fit Sirius copyright claim */<br />
#footer li {<br />
margin:0 1em;<br />
}<br />
<br />
/* use same red as Sirius PDFs */<br />
h1 {<br />
color: #660000;<br />
font-family: Arial, Helvetica, sans-serif;<br />
}<br />
<br />
h2 { <br />
font-family: Arial, Helvetica, sans-serif;<br />
color: #660000;<br />
}<br />
<br />
div#content h3 {<br />
font-size: 1.25em; <br />
}<br />
<br />
h5, h6, div#content h5, div#content h6 {<br />
font-style: italic;<br />
font-size: 92%; <br />
}<br />
<br />
tt {<br />
font-family: Consolas, "Liberation Mono", monospace;<br />
font-size:105%;<br />
}<br />
<br />
/* two cosmetic tweaks for Category page sections to remove some extra space */<br />
div#mw-subcategories h3 {<br />
padding-top:0px;<br />
margin-top:0px;<br />
}<br />
<br />
div#mw-pages h3 {<br />
padding-top:0px;<br />
}<br />
<br />
/* redirect pgs that have Category tag won't have italicized names on cat pg: */<br />
.redirect-in-category {<br />
font-style: normal;<br />
}<br />
<br />
code {<br />
font-family: Consolas,"Liberation Mono",monospace;<br />
}<br />
<br />
/** <br />
* make toggle text/icon display to the left of toggled content; <br />
* but elements after this floated element will try to flow around it,<br />
* so after the collapsible element's closing tag, specify <br close="all"><br />
*/<br />
.mw-collapsible span.mw-collapsible-toggle { float: left; }<br />
<br />
/* indent collapsed text to line-up with h2 title text */<br />
div.mw-collapsible-content {<br />
margin-left:2.32em;<br />
}<br />
<br />
<br />
/* ************************changes for Vector default ***************************** */<br />
/* hides sidebar Toolbox (so we can substitute our own set of items) */<br />
#p-tb { display:none; <br />
}<br />
<br />
/* for Monobook, widens sidebar boxes a tiny bit */<br />
.portlet {<br />
width: 11.75em;<br />
}<br />
<br />
/* for Monobook, reduces (moves right) page content area a tiny bit */<br />
/* b/c IE doesn't respond, need to snug box padding (see 'portlet pBody', below) */<br />
div#content { <br />
margin-left: 12.4em; /* not needed for Vector */<br />
}<br />
<br />
/* four tweaks to increase Vector sidebar width and make associated adjustments; */<br />
/* see also MediaWiki:Vector.css */<br />
div#mw-panel { <br />
width: 11.5em;<br />
padding-left: 0; /* was .5, which is not needed if centering vector */ <br />
left:auto; /* for Vector centering project */<br />
}<br />
<br />
#left-navigation { <br />
left: 11em;<br />
margin-left: 11.5em; /* increase of .5 for Vector centering project */<br />
}<br />
<br />
div#content.mw-body { <br />
margin-left: 11.5em; /* increase of .5 for Vector centering project */<br />
border-width: 1px; /* blue right border for Vector centering project */<br />
}<br />
<br />
div#footer ul {<br />
margin-left: 1em;<br />
}<br />
<br />
<br />
/* Monobook: for IE, lets sidebar box close on right by reducing the right padding */<br />
.portlet .pBody {<br />
padding-right: .1em;<br />
}<br />
<br />
/* Vector: used to widen sidebar boxes a tiny bit by larger padding to right */<br />
/* moving some divs undid that, so reducing it gives more room to text items */<br />
.portal .body {<br />
padding-right: .5em;<br />
} <br />
<br />
/* Monobook: rmv box from containing class of "What's New" element; tweak bot space */<br />
#p-\.C2\.A0.generated-sidebar.portlet .pBody {<br />
background-color:transparent;<br />
border:0px hidden transparent;<br />
padding-bottom: 0em; <br />
}<br />
<br />
/* for Monobook, removes bullet graphic, chngs font sz & left margin for "What's New" */<br />
#p-\.C2\.A0.generated-sidebar.portlet ul {<br />
list-style-type: none;<br />
list-style-image: none;<br />
font-style: normal;<br />
font-size: 100%;<br />
margin: .75em 0 0 .75em;<br />
} <br />
<br />
/* hides Blank list item but preserves its space so sibling list el has more cushion */ <br />
#n-Blank {<br />
visibility:hidden;<br />
} <br />
<br />
/* in Vector, tweaks "What's New" element */<br />
#mw-panel div.portal div.body ul:first-child li:only-child {<br />
line-height: 2.5em;<br />
padding-bottom: 1em;<br />
}<br />
<br />
/* tweaks list containing "What's New" element in Monobook and Vector */<br />
#p-\.C2\.A0 ul {<br />
line-height: 1em;<br />
padding-bottom: 0em;<br />
}<br />
<br />
/* makes Vector left margin for "What's New" same as list items in lower sections */<br />
/* default for this was .5; needed to precisely specify the "first" and "persistent" */<br />
#mw-panel.noprint.collapsible-nav .portal.first.persistent div.body {<br />
margin-left: 1.25em; /* this gets overridden to .5 */<br />
} <br />
<br />
<br />
/* ----------------------------------------------- */<br />
<br />
/* -- Vector centering proj (also see few commented tweaks above & in Vector.css) -- */<br />
div#center {<br />
margin: auto;<br />
max-width: 60em;<br />
}<br />
<br />
div#mw-head {<br />
right: auto;<br />
max-width: 60em;<br />
background-image: none;<br />
background-color: transparent;<br />
}<br />
<br />
div#p-logo {<br />
left: 0; /* was .5, not needed if centering vector (Vector.css overrides it) */ <br />
} /* see also mw-panel chg above */<br />
<br />
/* move top tab text up a bit to make white space above it less noticeable */<br />
div.vectorTabs ul li {<br />
line-height: .6em; <br />
}<br />
<br />
/* next 2 tweaks to snug right-nav els to content edge xcpt for 1px */<br />
div#p-personal {<br />
right: 1px;<br />
}<br />
<br />
div#p-search {<br />
margin-right: 1px;<br />
}<br />
<br />
div#mw-page-base {<br />
background-image: none;<br />
background-color: transparent;<br />
}<br />
<br />
/* ----------------------------------------------- */<br />
<br />
/* ****************************************************************************** */</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Template:M204.1414_skeleton&diff=116554Template:M204.1414 skeleton2018-07-12T21:25:17Z<p>Admin: 1 revision imported: page for M204.1414</p>
<hr />
<div><!--This page was automatically generated and will be automatically replaced, so any manual edits will be lost. You've been warned.--><br />
<span class="msgtext">M204.1414&nbsp; Error: sort record &#x200b;>&#x200b; 16meg </span></div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Template:M204.1414_footer&diff=116552Template:M204.1414 footer2018-07-12T21:25:16Z<p>Admin: 3 revisions imported: page for M204.1414</p>
<hr />
<div><!--This page was automatically generated and will be automatically replaced, so any manual edits will be lost. You've been warned.--><br />
<b>Message attributes:</b><br />
<table class="thJustBold"><br />
<tr><th>RETCODEO=0</th><td>Sets online return code</td></tr><br />
<tr><th>RETCODEB=4</th><td>Sets batch (single user) return code</td></tr><br />
<tr><th>CLASS=E</th><td>Error class; the message can be suppressed with the X'04' bit setting of the <var>[[MSGCTL parameter|MSGCTL]]</var> parameter</td></tr><br />
<tr><th>AUDITER</th><td>Writes the message with line type ER to the audit trail</td></tr><br />
<tr><th>CANCEL</th><td>Cancels the user's request</td></tr><br />
<tr><th>COUNT</th><td>Increments the error count (<var>[[ERCNT parameter|ERCNT]]</var>) parameter</td></tr><br />
</table><br />
[[List of Model 204 messages#M204.1414|Back to list of messages]]<br />
<includeonly>[[Category:M204.nnnn messages]]</includeonly><br />
<includeonly>[[Category:M204.1400 - M204.1599]]</includeonly></div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=M204.1414&diff=116548M204.14142018-07-12T21:25:16Z<p>Admin: 4 revisions imported: page for M204.1414</p>
<hr />
<div>{{Template:M204.1414 skeleton}}<br />
__NOTOC__<br />
<p><br />
A sort statement encountered a record length greater than 16 megabytes. The request is cancelled.<br />
</p><br />
<p><br />
<b>Response:</b><br />
Review the records being sorted and ensure that no individual record to be sorted has a record length exceeding 16 megabytes.<br />
</p><br />
<p><b>Version introduced:</b><br />
<br />
7.5<br />
<br />
</p><br />
{{Template:M204.1414 footer}}<br />
[[Category: Pending messages]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Template:Screen_statement_syntax&diff=116322Template:Screen statement syntax2018-06-14T22:44:55Z<p>Admin: add link</p>
<hr />
<div><var>Screen</var> block:<br />
<p class="syntax"><span class="squareb">[</span>[[Using variables and values in computation#Declaring|Declare]]<span class="squareb">]</span> [[Screen statement or block|Screen]] <span class="term">screenName</span><br />
<span class="squareb">[</span>Global <span class="squareb">[</span>Permanent <span class="squareb">|</span> Temporary<span class="squareb">]</span><br />
<span class="squareb">|</span> Common<span class="squareb">]</span><br />
<span class="term">screenLine</span><br />
<span class="term">screenLine</span><br />
...<br />
End Screen<br />
</p><br />
<br />
<var>Screen</var> statement, referring to a screen defined earlier in a <var>Screen</var> block:<br />
<p class="syntaxUL"><span class="squareb">[</span>Declare<span class="squareb">]</span> Screen <span class="term">screenName</span> Common<br />
</p></div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Image_statement_or_block&diff=116321Image statement or block2018-06-14T22:39:39Z<p>Admin: Admin moved page Image statement to Image statement or block without leaving a redirect: consistency with menu and screen</p>
<hr />
<div>#REDIRECT [[Images#Image and End Image statements]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Declare_statement&diff=115347Declare statement2018-05-29T17:50:54Z<p>Admin: Admin moved page "Declare statement" to Declare statement without leaving a redirect: typo</p>
<hr />
<div>#REDIRECT [[Statement syntax#Declare]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Template:Remember_statement_syntax&diff=115295Template:Remember statement syntax2018-05-22T19:25:25Z<p>Admin: Admin moved page Template:Remember statement to Template:Remember statement syntax without leaving a redirect: omitted suffix</p>
<hr />
<div><p class="syntax">Remember [Global] <span class="term">position_name</span> [In <span class="term">foundsortset_name</span> | On <span class="term">list_name</span>]<br />
</p></div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Remember_statement&diff=115283Remember statement2018-05-22T18:54:45Z<p>Admin: Admin moved page "Remember statement" to Remember statement without leaving a redirect: typo</p>
<hr />
<div>#REDIRECT [[Global features#Remember statement]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Images&diff=115246Images2018-05-18T16:03:54Z<p>Admin: /* SKIP statement */ substitute template for syntax lines</p>
<hr />
<div><div class="toclimit-3"><br />
<br />
==Overview==<br />
<p><br />
This article describes <b>images</b>, a feature of SOUL that allows:</p><br />
<ul><br />
<li>A request to read and process non-<var class="product">Model&nbsp;204</var> files, that is, sequential and VSAM files, and terminal input, such as a Host Language IFDIAL thread</li><br />
<br />
<li>A request to write to sequential files and terminals </li><br />
<br />
<li>The creation of formatted blocks of storage that can be used to build records or to process data that is not in a format automatically recognized by <var class="product">Model&nbsp;204</var> </li><br />
</ul><br />
<br />
===Terminology===<br />
<p><br />
Before reviewing the capabilities and requirements of images, you should be familiar with the following terms that are used throughout this discussion:</p><br />
<table><br />
<tr class="head"><br />
<th>Term </th><br />
<th>Definition</th><br />
</tr><br />
<br />
<tr><br />
<td>Array</td><br />
<td>Ordered arrangement of data elements. Multiple occurrences of an item or a group of items. </td><br />
</tr><br />
<br />
<tr><br />
<td>Block </td><br />
<td>A contiguous storage area into which a record is read or from which a record is written. Also, block can be a contiguous storage area in which data can be manipulated.</td><br />
</tr><br />
<br />
<tr><br />
<td>Image</td><br />
<td>A description of the format of data in a block.</td><br />
</tr><br />
<br />
<tr><br />
<td>Item</td><br />
<td>An individual string or number in an image. </td><br />
</tr><br />
</table><br />
<br />
===Global images===<br />
<p><br />
Global images provide a means for passing image data from one request to another, and for efficiently managing more than one image in one request.</p><br />
<p><br />
Although there are some differences in the way you use the DECLARE IMAGE statement, you generally define and use global images the same as you do non-global images. See [[Global features#Global images and screens|Global images and screens]] where a discussion of global screens, menus, and images begins.</p><br />
<br />
==Using images==<br />
<p><br />
See [[Global features#Global images and screens|Global images and screens]] for a discussion of global images.</p><br />
<br />
===Reading external files or terminal input===<br />
<br />
====Input sources====<br />
<p><br />
The image feature lets a request read and process records from the following sources of input: </p><br />
<table><br />
<tr class="head"><br />
<th>Input sources </th><br />
<th>Description</th><br />
</tr><br />
<br />
<tr><br />
<td>Sequential or VSAM files </td><br />
<td>Any number of sequential or VSAM files can be read and processed. If VSAM files are used, the files must be keyed sequential (KSDS). KSDS files can be accessed using an alternate index path. <br />
<p><br />
For more information on the types of files and keys that can be used,<br />
see the <var>[[DEFINE DATASET command|DEFINE DATASET]]</var> command. </p><br />
</td></tr><br />
<br />
<tr><br />
<td>Terminal </td><br />
<td>Terminal input can be read and processed. A terminal can consist of the physical device on which the request is run, or a User Language connection that has been made from a Host Language application program by using the <var>[[IFDIAL (HLI function)|IFDIAL]]</var> function. </td></tr><br />
</table><br />
<br />
====External records====<br />
<p><br />
Records read from sequential or VSAM files and data passed from the terminal are referred to as external records in this discussion to distinguish them from <var class="product">Model&nbsp;204</var> records. </p><br />
<p><br />
The format of the external record is described by a structure called an image. Multiple descriptions of a record are allowed, as discussed later in this article. User Language statements can refer to each item described in the image definition.</p><br />
<br />
====Reading records into an image====<br />
<p><br />
User Language statements, which are documented beginning with [[#Processing images|Processing images]], let the request open the file, read records into the image, and close the file. </p><br />
<p><br />
For keyed VSAM files, the request can position the file to read sequentially starting with any record in the file.</p><br />
<br />
===Writing to sequential files or a terminal===<br />
<p><br />
The image feature lets a request write records to any number of sequential files or to a terminal. This capability allows multiple output files and reports to be written by a single pass of the database. </p><br />
<p class="note"><b>Note:</b> Only printable characters of a record are displayed on a physical terminal device. Therefore, images used to write to a physical terminal device should be defined with string items only.</p><br />
<br />
===Defining storage blocks===<br />
<p><br />
You can define the data in a block of storage as an image. </p><br />
<p><br />
The image definition can consist of item definitions as well as definitions of areas in the block that do not need to be accessed. Items in the image can be filled with constants, %variables, fields from a <var class="product">Model&nbsp;204</var> record, screen items, items from the current block or another block, and expressions. </p><br />
<p><br />
Each item defined in the image can be referred to by User Language statements.</p><br />
<br />
====Possible uses====<br />
<p><br />
In addition to sequential file, VSAM file, or terminal I/O processing, the ability to manipulate a block of storage has several other uses. For example, you can:</p><br />
<ul><br />
<li>Construct print lines by filling in items in one or more images at various points in a request. Once the print lines are complete, you can print the lines.</li><br />
<br />
<li>Copy into an image fields in <var class="product">Model&nbsp;204</var> records that have formats not directly recognized by User Language; the individual parts of the field then can be accessed as image items. For example, if the user wants to use packed decimal data that is stored in a <var class="product">Model&nbsp;204</var> field, the data can be moved into an image item and used directly. This eliminates the need to use the $PACK function to convert the data prior to its use.</li><br />
<br />
<li>Store blocks of data of up to 255 bytes as a single field, copied to an image, and the parts of the block can be referred to separately. Data that is stored as a single, large field, for example, a line of text, can be moved into an image that defines the data as one or more items. The items then can be referred to separately. </li><br />
<br />
<li>Pass data from one request to another.</li><br />
<br />
<li>You can manipulate more than one image at a time in an application, for example, in an HORIZON application involving simultaneous conversations.</li><br />
<br />
<li>You can use images to structure the local working storage of a request in a more disciplined manner than is possible with %variables.</li><br />
</ul><br />
<br />
==Defining an image==<br />
<br />
===Managing blocks===<br />
<p><br />
You must define the layout of the block before it can be used by the request. </p><br />
<p><br />
A block is defined by one or more images that describe the data in the block. </p><br />
<p><br />
Images describe blocks of data up to 32,767 bytes in length. </p><br />
<br />
===Define an image before referring to it===<br />
<p><br />
In a request, an image definition must precede any references to the image. </p><br />
<br />
===Understanding how data is described by images===<br />
<p><br />
To design applications using images, you can review the following summary of how images are used to describe different views of the data is provided below:</p><br />
<ul><br />
<li>Using images, the application can access any piece of data in the block. As many as 255 images can describe the same block.</li><br />
<br />
<li>Although a single request can contain more than one block of images, the total number of images for all blocks within each request cannot exceed 256 images (version 7.6 and earlier) or 4095 images (version 7.7 and later).</li><br />
<br />
<li>You can define multiple images to provide different views of the same data. This is similar to the COBOL capability to REDEFINE a piece of storage. The multiple image capability enables the request to read in a record, determine the format of the data in the record, and access different data items in the record according to format.</li><br />
<br />
<li>You can define the image items as strings or numbers. Numbers can have binary, floating point, packed decimal, zoned decimal, and exponential formats. <var class="product">Model&nbsp;204</var> automatically handles all data type conversions when referring to image items.</li><br />
<br />
<li>You can define fixed and variable length arrays within an image. Each array element can contain one or more items. Arrays can be nested up to 255 levels deep.</li><br />
<br />
<li>You can define image items precisely or their length can be determined during evaluation. Similarly, the number of array occurrences can be determined during evaluation. This capability allows the request to handle all types of data structures. </li><br />
</ul><br />
<br />
===Image components===<br />
<p><br />
Each block definition must begin with an IMAGE statement and end with an END IMAGE statement. Between these statements, the following components are used to describe the contents of the block:</p><br />
<ul><br />
<li>Image definitions</li><br />
<br />
<li>Item definitions</li><br />
<br />
<li>Array definitions</li><br />
<br />
<li>Reserved area definitions </li><br />
</ul><br />
<p><br />
Comments, blank lines, and INCLUDE statements can also be part of a block definition. </p><br />
<br />
===Concurrent access to multiple records of the same format===<br />
<p><br />
One image definition is required for each record to be accessed concurrently. </p><br />
<p><br />
If you need concurrent access to multiple records of the same format, the image definition must be duplicated with a different name. This can be done easily by using an INCLUDE statement inside the image definition.</p><br />
<br />
==Image naming and reference conventions==<br />
<br />
===Rules for image names===<br />
<ul><br />
<li>An image name is a character string that consists of any number of letters, numbers, and some special characters. The name can have no embedded blanks, colons, or <var class="product">Model&nbsp;204</var> reserved characters. Refer to [[Reserved words and characters]] for a complete list of reserved characters.</li><br />
<br />
<li>An image cannot have the same name as a screen or menu.</li><br />
<br />
<li>If <var>Image</var>, <var>Menu</var>, or <var>Screen</var> is an image name, it must be preceded by the keyword <var>Image</var> in <var>Read Image</var> and <var>Prepare</var> statements. </li><br />
</ul><br />
<br />
===Rules for item names and array names===<br />
<ul><br />
<li>Item and array names follow the same naming conventions as image names.</li><br />
<br />
<li>Every image item name and array name must be unique within the block definition. An item name or array name can be reused in different blocks, screens, and menus. </li><br />
<br />
<li>An item (or array) name and its image name cannot have a combined length exceeding 253. </li><br />
</ul><br />
<br />
===Rule for reserved item names===<br />
<p><br />
The item name READLEN is reserved by <var class="product">Model&nbsp;204</var> to contain the length of the last record read into the block. This value can be obtained from the variable %imagename:READLEN. </p><br />
<br />
===Do not duplicate names in the same block===<br />
<p><br />
Do not duplicate item, array, and image names within the same block. </p><br />
<br />
===References===<br />
<p><br />
To identify the item uniquely, all references outside the image definition must include the image name and item name and must be specified in this format:</p><br />
<p class="syntax"><span class="term">%imagename</span>:<span class="term">itemname</span><br />
</p><br />
<p><br />
For example:</p><br />
<p class="code">%INVENTORY:PART.NO<br />
</p><br />
<p><br />
identifies the item PART.NO in the image INVENTORY. </p><br />
<br />
==Image and End Image statements==<br />
<p><br />
The <var>Image</var> statement starts the definition of the image. Each image can contain a description of the complete block or can redefine a portion of another image. </p><br />
<br />
====Syntax====<br />
<p><br />
The format of the <var>Image</var> statement is:<br />
</p><br />
{{Template:Image statement syntax}}<br />
Where:<br />
<ul><br />
<li><var class="term">imagename</var> is the name of the image. Every image name defined in a request must be unique. The image name specified in the <var>Image</var> statement is assigned to the image being defined; other SOUL statements in the request can subsequently refer to this name.</li><br />
<br />
<li><var>Namesave</var> is meaningful only for images used by certain $functions and OO methods: <var>$Field_Image</var>, <var>$Field_ListI</var>, and <var>AppendFieldImages</var>. </li><br />
<br />
<li>The <var>At</var> clause is optional and specifies the starting location of a redefinition. If the <var>At</var> clause is omitted, the image definition starts at the beginning of the block. The location can be defined by one of the following options:<br />
<ul><br />
<li><var class="term">itemname</var> is the name of an item in a previously defined image in this block.</li><br />
<br />
<li><var class="term">imagename1</var> is the name of an image previously defined in this block.</li><br />
<br />
<li><var class="term">arrayname</var> is the name of an array in a previously defined image in this block. </li><br />
</ul><br />
<br />
<blockquote class="note"><p><b>Note:</b><br />
You cannot use the <var>At</var> clause with a <var>Global</var> image, since you can only define the first image in a multi-image block as a global image. </p><br />
<ul><br />
<li>Specifying <var>Common</var>, or specifying neither <var>Common</var> nor <var>Global</var>, results in the image being stored in FSCB. Common elements, as well as <var>Declare</var> and <var>Common</var>, are discussed in detail in [[Subroutines#Subroutines|Subroutines]]. </li><br />
<br />
<li><var>Global</var> specifies to store the image in GTBL. Global images have an implied scope of <var>Common</var> (see above). </li><br />
</ul><br />
</blockquote><br />
</li></ul><br />
<br />
====Restrictions to the GLOBAL option====<br />
<p><br />
You must not specify the <var>Global</var> attribute for an image that has an image item defined with either of the following attributes: </p><br />
<ul><br />
<li><var>Occurs Unknown</var> </li><br />
<br />
<li><var>Len Unknown</var> </li><br />
</ul><br />
<p><br />
For multi-image blocks, you can specify only the first image as <var>Global</var>; you must not specify subsequent images in a multi-image block as <var>Global</var>.</p><br />
<ul><br />
<li><var>Permanent</var> can be used only with global images. Permanent global images persist across request boundaries; that is, they are maintained in GTBL even after a request has been terminated. </li><br />
<br />
<li><var>Temporary</var> can be used with only global images. <var>Temporary</var> global images are allocated in GTBL, but are deleted at request termination. For example, use a <var>Temporary</var> global image when you do not need to pass the image to another request; using <var>Temporary</var> global images eliminates the need to explicitly delete globals that do not need to persist. </li><br />
</ul><br />
<br />
===End Image statement===<br />
<p><br />
The <var>End Image</var> statement must be the last statement in an image definition. <var>End Image</var> terminates the definition of all images that describe the same block. </p><br />
<p><br />
The format of this statement is: <br />
</p><br />
<p class="code">End Image<br />
</p><br />
<br />
===Examples of image definitions===<br />
<br />
====Single image definition====<br />
<p><br />
An example of the definition of a single image follows:</p><br />
<p class="code">IMAGE GENERAL.LEDGER.RECORD<br />
GL.RECORD.TYPE IS STRING LEN 1<br />
GL.NUMBER IS STRING LEN 10 DP 3<br />
GL.INV.TYPE IS STRING LEN 2<br />
END IMAGE<br />
</p><br />
<br />
====Multiple image definition for the same block====<br />
<p><br />
The following example illustrates two images that define the same block. Each image completely defines the block, with the items named <code>GL.RECORD.TYPE</code> and <code>AR.RECORD.TYPE</code> both located at the first byte in the block.<br />
</p><br />
<p class="code">IMAGE GENERAL.LEDGER.RECORD<br />
GL.RECORD.TYPE IS STRING LEN 1<br />
GL.NUMBER IS STRING LEN 10 DP 3<br />
GL.INV.TYPE IS STRING LEN 2<br />
IMAGE ACCOUNTS.REC.RECORD<br />
AR.RECORD.TYPE IS STRING LEN 1<br />
AR.ACCT.NO IS STRING LEN 6<br />
AR.BALANCE IS PACKED DIGITS 9 DP 2<br />
END IMAGE<br />
</p><br />
<br />
====Multiple image definition with shared items====<br />
<p><br />
When an image redefines part of another image, the <var>At</var> clause names an item or array in an image already defined in the record. Items preceding the named item or array in the block are combined with items defined following the <var>Image</var> statement to create the complete image description.</p><br />
<p><br />
Therefore, the preceding example also could be defined in the following manner. The example illustrates two images that define the same block but share at least one item in common. In this example, the item <code>RECORD.TYPE</code> is shared by both images, and it can be referred to by prefixing the item name by either image name. The items <code>GL.NUMBER</code> and <code>AR.ACCT.NO</code> both begin at position 2 in the block. <br />
</p><br />
<p class="code">IMAGE GENERAL.LEDGER.RECORD<br />
GL.RECORD.TYPE IS STRING LEN 1<br />
GL.NUMBER IS STRING LEN 10 DP 3<br />
GL.INV.TYPE IS STRING LEN 2<br />
IMAGE ACCOUNTS.REC.RECORD AT GL.NUMBER<br />
AR.ACCT.NO IS STRING LEN 6<br />
AR.BALANCE IS PACKED DIGITS 9 DP 2<br />
END IMAGE<br />
</p><br />
<br />
===Special considerations for multiple-image blocks===<br />
<p><br />
When you define multiple-image blocks, take note whether the sum of the individual image items completely defines the block. Is there undefined space between the image items? If there are, you must initialize the space, otherwise you might get unexpected results, as illustrated in the following code. </p><br />
<br />
====Using uninitialized disk space====<br />
<p><br />
In the following multiple-image block, <code>PART1</code>, <code>PART2</code>, and <code>PART3</code> define parts of the block without defining or initializing the space between them. When <code>LINE</code> is defined, which encompasses the entire block, the system assumes that the entire block has already been defined, because <code>LINE</code> begins at the same place as <code>PART1</code>. </p><br />
<p class="code">R HDRCTL 0<br />
BEGIN<br />
<br />
IMAGE A<br />
PART1 IS STRING LEN 10<br />
PART2 IS STRING LEN 5 AT 16<br />
PART3 IS STRING LEN 5 AT 26<br />
LINE IS STRING LEN 30 AT PART1<br />
END IMAGE<br />
<br />
PREPARE IMAGE A<br />
<br />
%A:PART1 = 'XXXXXXXXXX'<br />
%A:PART2 = 'YYYYY'<br />
%A:PART3 = 'ZZZZZ'<br />
<br />
SET HEADER 1 %A:LINE<br />
NP<br />
PRINT '%A:LINE = ' WITH %A:LINE<br />
PRINT '$C2X(%A:LINE) = ' WITH $C2X(%A:LINE)<br />
END<br />
</p><br />
<p><br />
However, when output from the previous procedure is displayed, a stray numeral two appears twice in the header. This system read the string of zeros for the uninitialized space in the header (shown in the line that begins with <code>$C2X</code>) and automatically substituted the page number. </p><br />
<p class="output">02.142 MAY 22 10.11.11 PAGE 2<br />
XXXXXXXXXX 2YYYYY 2ZZZZZ<br />
%A:LINE = XXXXXXXXXX YYYYY ZZZZZ<br />
$C2X(%A:LINE) = E7E7E7E7E7E7E70000000000E8E8E8E8E80000000000E9E9E9E9E9<br />
</p><br />
<br />
====Using initialized disk space====<br />
<p><br />
Refining the previous code, the spaces between PART 1 and PART2 and PART3 are initialized by the intervening SKIP statements.</p><br />
<p class="code">R HDRCTL 0<br />
BEGIN<br />
<br />
IMAGE A<br />
PART1 IS STRING LEN 10<br />
SKIP 5 POSITIONS INITIAL BLANK<br />
PART2 IS STRING LEN 5 AT 16<br />
SKIP 5 POSITIONS INITIAL BLANK<br />
PART3 IS STRING LEN 5 AT 26<br />
LINE IS STRING LEN 30 AT PART1<br />
END IMAGE<br />
<br />
PREPARE IMAGE A<br />
<br />
%A:PART1 = 'XXXXXXXXXX'<br />
%A:PART2 = 'YYYYY'<br />
%A:PART3 = 'ZZZZZ'<br />
<br />
SET HEADER 1 %A:LINE<br />
NP<br />
PRINT '%A:LINE = ' WITH %A:LINE<br />
PRINT '$C2X(%A:LINE) = ' WITH $C2X(%A:LINE)<br />
END<br />
</p><br />
<p><br />
Now the output displays the expected results. The line that begins with <code>$C2X</code> has the hexadecimal representation of white space between the defined areas meaning that the space is initialized. The system prints only the white spaces. </p><br />
<p class="output">02.142 MAY 22 10.12.26 PAGE 2<br />
XXXXXXXXXX YYYYY ZZZZZ<br />
%A:LINE = XXXXXXXXXX YYYYY ZZZZZ<br />
$C2X(%A:LINE) = E7E7E7E7E7E7E74040404040E8E8E8E8E84040404040E9E9E9E9E9<br />
</p><br />
<br />
==Defining image items==<br />
<p><br />
You must define each item in an image that is referred to by the request. Use an item definition to describe the following attributes for an item:</p><br />
<ul><br />
<li>Data type </li><br />
<li>Length </li><br />
<li>Position </li><br />
<li>Number of occurrences</li><br />
<li>Editing options</li><br />
</ul><br />
<br />
====Syntax====<br />
<p><br />
The general format of an item definition is:<br />
</p><br />
<p class="syntax"><span class="term">itemname</span> [Is [Type] <span class="term">type</span> <span class="term">description</span>]<br />
</p><br />
Where:<br />
<ul><br />
<li><var class="term">itemname</var> is the name by which the item is referred to.</li><br />
<br />
<li><var>Type</var> is an optional keyword.</li><br />
<br />
<li><var class="term">type</var> specifies the data type of the item. Data type options are:<br />
<ul><br />
<li>String</li><br />
<li>Binary</li><br />
<li>Large Object data</li><br />
<li>Packed decimal</li><br />
<li>Zoned decimal</li><br />
<li>Floating point</li><br />
<li>Exponential notation </li><br />
</ul></li><br />
<br />
<li><var class="term">description</var> is the length, position, number of occurrences, and editing options specified for the item based on the data type. <br />
</li><br />
</ul><br />
<p><br />
The format used when defining an item for each data type is provided in the following table. In addition, an example of an image item definition appears in [[#Item definition examples|Item definition examples]]: </p><br />
<table><br />
<tr class="head"><br />
<th>Term</th><br />
<th>Description</th><br />
</tr><br />
<br />
<tr><br />
<td>Numeric</td><br />
<td>All types except String are considered numeric.</td><br />
</tr><br />
<br />
<tr><br />
<td>Null</td><br />
<td>Binary zeros.</td><br />
</tr><br />
<br />
<tr><br />
<td>Omitted</td><br />
<td>The option is omitted from the item description and no default is specified.</td><br />
</tr><br />
<br />
<tr><br />
<td>String</td><br />
<td>A string of characters. A string must be enclosed in single quotes if it contains any of the following characters: blank, =, (, ), <, >, or ^.</td><br />
</tr><br />
<br />
<tr><br />
<td>Zero</td><br />
<td>Numeric zero of the correct format for numeric items. String and EFORMAT items are set to a single character zero. </td><br />
</tr><br />
</table><br />
<br />
===Defining a string item===<br />
<br />
====Syntax====<br />
<p><br />
Define string items with this syntax: </p><br />
<p class="syntax">String {Len {<span class="term">n</span> | Unknown} [Dp {<span class="term">k</span> | *}] | To <span class="term">position</span>} <br />
[Pad {Blank | <span class="term">character</span> | Null}] <br />
[Strip | NoStrip] [Justify {Left | Right}] <br />
[Initial {Blank | string | Zero | Null}] <br />
[After {<span class="term">itemname</span> | <span class="term">arrayname</span>} <br />
| At {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imagname1</span> | <span class="term">arrayname</span>}] <br />
[Occurs {<span class="term">n</span> [Depending On {<span class="term">itemname</span> | <span class="term">%variable</span>}] <br />
| Unknown}]<br />
</p><br />
Where:<br />
<ul><br />
<li><var>Len</var> specifies the length either as 1-255 bytes or as <var>Unknown</var>, if the length is determined by the request and the <var>Identify</var> statement establishes the length. </li><br />
<br />
<li><var>To</var> specifies the last byte position of the item in the image as a number from 1 to 32767. The length (<var>Len</var>) or end (<var>To</var>) position of the item is required unless the length has been specified in a <var>Default</var> statement. </li><br />
<br />
<li><var>Dp</var> (optional) specifies either that the item has from 0 to 15 decimal places as specified by <var class="term">k</var>, or that the number of decimal places is variable. <br />
<ul><br />
<li><var>Dp <i>k</i></var> represents the number of places retained when a number is stored into an item and the number of places assumed to be present in data read from an external record. </li><br />
<br />
<li>If <code>Dp *</code> is specified, all decimal places in the item are retained. If this option is omitted, the default is zero. Do not use <var>Dp</var>, if the value to be moved to the item contains a decimal point. </li> <br />
</ul></li><br />
<br />
<li><var>Pad</var> (optional) defines the fill character. If a value is shorter than an item to which it is being moved, the pad character fills the remainder of the item. If PAD is omitted, a blank is assumed. Padding is done on the right end of left-justified items and on the left end of right-justified items. <br />
<p><br />
The pad character can be a single quoted character, a hexadecimal value expressed as <code>X'hh'</code>, or a decimal number. The hexadecimal or decimal value can be from 0 to 255. </p></li><br />
<br />
<li><var>Strip</var>, the default, specifies to remove the pad characters, if an item value is extracted from an image. <var>NoStrip</var> specifies to keep the pad characters. </li><br />
<br />
<li><var>Justify</var> (optional) specifies whether a value is to be left- or right-justified when moved into an item by an assignment statement or when stripping on extraction. If <var>Justify</var> is omitted, the default is left-justified. </li><br />
<br />
<li><var>Initial</var> (optional) defines the value placed in the item by a <var>Prepare</var> statement and in unused occurrences when a record is read from a sequential file, VSAM file, or terminal into an image. If an <var>Initial</var> clause is omitted, <var>Blank</var> is the default initial value. </li><br />
</ul><br />
<br />
====AFTER and AT clauses====<br />
<ul><br />
<li>The <var>After</var> and <var>At</var> clauses are optional and mutually exclusive. Their function is as follows:<br />
<p><br />
An <var>After</var> clause defines the location of an item as immediately following the end of the specified item or array. This option is particularly useful when an item is redefined and the total length of the items in a redefinition is less than the length of the item. </p><br />
<p><br />
An <var>At</var> clause defines the location of the item in the image as adjacent to an item or array or redefines the space defined by a previously defined item. If the location is not adjacent in a forward direction to the previous item definition, a <var>Skip</var> is implied (see [[#DEFAULT SKIP statement|DEFAULT SKIP statement]]). If position is used, the location is relative to the beginning of the image. </p><br />
<p><br />
The position option can have a value from 1 through 32767. The item or array named in the <var>At</var> clause cannot have a <var>Depending On</var> option. </p><br />
<p><br />
Consider the following restrictions when using an <var>After</var> or <var>At</var> clause:</p><br />
<ul><br />
<li>Outside of an array definition, the <var>After</var> or <var>At</var> clause cannot name an item inside the array. </li><br />
<br />
<li>Within an array definition, the <var>After</var> or <var>At</var> clause cannot name an item outside of the array. </li><br />
<br />
<li>If neither <var>After</var> nor <var>At</var> are specified, the item abuts the end of the preceding item or the start of the image. </li><br />
</ul></li><br />
</ul><br />
<br />
====OCCURS clause====<br />
<ul><br />
<li>The <var>Occurs</var> clause (optional) specifies that there are multiple occurrences of the item. The <var>Occurs</var> clause options are as follows: <br />
<ul><br />
<li><var class="term">n</var> specifies the maximum number of occurrences of the item for a depending array and the exact number of occurrences of the item for a fixed array. The value of <var class="term">n</var> can be from 1 to 32767. Space for the maximum number of occurrences is reserved in a block created by a <var>Prepare</var> statement or when a block is read from a sequential file, VSAM file, or terminal.</li><br />
<br />
<li>The <var>Depending On</var> clause identifies the item or %variable that contains the current number of occurrences of this item. An item specified in this clause must be part of this image, cannot have length specified as <var>Unknown</var>, cannot be an array element, and cannot be positioned in the image following an item defined with <var>Len Unknown</var> or an array defined with <var>Occurs Unknown</var>. </li><br />
<br />
<li><var>Unknown</var> specifies that the number of occurrences of the item is determined by the SOUL request and that the <var>Identify</var> statement establishes the number of occurrences. </li><br />
</ul><br />
</li></ul><br />
<br />
===Defining a binary item===<br />
<br />
====Syntax====<br />
<p><br />
Define binary items with this syntax: <br />
</p><br />
<p class="syntax">BINARY {LEN {<span class="term">n</span> | UNKNOWN} | BITS <span class="term">n</span> | TO <span class="term">position</span>} <br />
[BP <span class="term">n</span>] <br />
[SIGNED | UNSIGNED] [ALIGN] <br />
[INITIAL {NULL | <span class="term">number</span> | BLANK | ZERO}] <br />
[AFTER {<span class="term">itemname</span> | <span class="term">arrayname</span>} <br />
| AT {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imagname1</span> | <span class="term">arrayname</span>}] <br />
[OCCURS {<span class="term">n</span> [DEPENDING ON {<span class="term">itemname</span> | <span class="term">%variable</span>}] <br />
| UNKNOWN}]<br />
</p><br />
Where:<br />
<ul><br />
<li>LEN specifies the length as 1-4 bytes or as UNKNOWN if the length is determined by the request and the <var>Identify</var> statement establishes the length. </li><br />
<br />
<li>BITS specifies the length as 8, 16, 24, or 32 bits. </li><br />
<br />
<li>TO specifies the last byte position of the item in the image as a number from 1 to 32767. The length or end (TO) position of the item is required unless provided in a DEFAULT statement. </li><br />
<br />
<li>BP (optional) specifies the number of binary places retained when a number is stored in the item and the number of places assumed present in data read from an external record. The number of places can range from zero to the number of bits defined by the length option, the maximum is 31 bits. IF BP is omitted, the default value is zero.</li><br />
<br />
<li>SIGNED, optional and the default, specifies that a negative number can be stored in the item in two's complement form. UNSIGNED, optional, specifies that the item is always positive and that the leftmost bit is part of the number. <br />
<p class="note"><b>Note:</b><br />
If a negative number is read into an UNSIGNED BINARY item, <var class="product">Model&nbsp;204</var> uses the absolute value of that number. </p></li><br />
<br />
<li>ALIGN, optional, specifies that the item is aligned as follows: <br />
<ul><br />
<li>BINARY LEN 2 on a halfword boundary</li><br />
<li>BINARY LEN 4 on a fullword boundary </li><br />
<li>The ALIGN option is ignored for 1- and 3-byte BINARY items.</li><br />
</ul><br />
<p><br />
The item is aligned by inserting a SKIP statement preceding the item so that the item's location is on the correct boundary. In arrays, a SKIP is inserted at the end of each occurrence of the array and any parent array to make the length of each occurrence a multiple of the largest aligned item in the array. </p><br />
<p><br />
The ALIGN option cannot be specified for an item:</p><br />
<ul><br />
<li>When length is defined as UNKNOWN. </li><br />
<li>When location is unknown during compilation because a previously defined item specified LEN UNKNOWN or OCCURS UNKNOWN. </li><br />
<li>Containing an AT clause that specifies a location that is not already aligned on the proper storage boundary.</li><br />
</ul></li><br />
<br />
<li>INITIAL (optional) defines the value placed in the item by a <var>Prepare</var> statement and in unused occurrences when a record is read from a sequential file, VSAM file, or terminal into an image. If this option is omitted, NULL is the default initial value. </li><br />
<br />
<li>The AFTER and AT clauses are mutually exclusive and optionally define the location of the item in the image. For a complete discussion, see [[#Defining a string item|Defining a string item]]. </li><br />
<br />
<li>The optional OCCURS clause specifies that there are multiple occurrences of the item. For a complete discussion, see [[#Defining a string item|Defining a string item]]. <br />
</li><br />
</ul><br />
<br />
===Defining a packed decimal item===<br />
<br />
====Syntax====<br />
<p><br />
Define packed decimal items with this syntax: </p><br />
<p class="syntax">PACKED {LEN {<span class="term">n</span> | UNKNOWN} | DIGITS <span class="term">n</span> | TO <span class="term">position</span>} <br />
[DP <span class="term">n</span>] <br />
[SIGNED | UNSIGNED] <br />
[INITIAL {ZERO | <span class="term">number</span> | BLANK | NULL}] <br />
[AFTER {<span class="term">itemname</span> | <span class="term">arrayname</span>} <br />
| AT {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imagname1</span> | <span class="term">arrayname</span>}] <br />
[OCCURS {<span class="term">n</span> [DEPENDING ON {<span class="term">itemname</span> | <span class="term">%variable</span>}]<br />
| UNKNOWN}]<br />
</p><br />
Where:<br />
<ul><br />
<li>LEN specifies the length as 1-8 bytes or as UNKNOWN if the length is determined by the request and the <var>Identify</var> statement establishes the length. </li><br />
<br />
<li>DIGITS specifies the length as 1-15 decimal digits. </li><br />
<br />
<li>TO specifies the last byte position of the item in the image as a number from 1 to 32767. The length or end (TO) position of the item is required unless provided in a DEFAULT statement. </li><br />
<br />
<li>DP (optional) and specifies the number of decimal places to be retained when a number is stored in this item, that is, the number of places assumed present in data read from an external record. The value of n can range from 0 to 15. If this option is omitted, the default is zero. </li><br />
<br />
<li>SIGNED, optional and the default, specifies that the item can contain a positive or negative number. The sign stored with the number is a hexadecimal C for a positive number and D for a negative number.</li><br />
<br />
<li>UNSIGNED (optional) specifies that the item is always a positive number and that the sign stored with the number is a hexadecimal F. </li><br />
<br />
<li>INITIAL (optional) defines the value placed in the item by a <var>Prepare</var> statement and in unused occurrences when a record is read from a sequential file, VSAM file, or terminal into an image. If this option is omitted, the default initial value is a packed zero. </li><br />
<br />
<li>The mutually exclusive and optional AFTER and AT clauses define the location of the item in the image. For a complete discussion, see [[#Defining a string item|Defining a string item]]. </li><br />
<br />
<li>The optional OCCURS clause specifies that there are multiple occurrences of the item. For a complete discussion, see [[#Defining a string item|Defining a string item]]. <br />
</li><br />
</ul><br />
<br />
===Defining a zoned decimal item===<br />
<br />
====Syntax====<br />
<p><br />
Define zoned decimal items with this syntax: </p><br />
<p class="syntax">ZONED {LEN {<span class="term">n</span> | UNKNOWN} | DIGITS <span class="term">n</span> | TO <span class="term">position</span>} <br />
[DP <span class="term">n</span>] <br />
[SIGNED | UNSIGNED] <br />
[INITIAL {ZERO | <span class="term">number</span> | BLANK | NULL}] <br />
[AFTER {<span class="term">itemname</span> | <span class="term">arrayname</span>} <br />
| AT {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imagname1</span> | <span class="term">arrayname</span>}] <br />
[OCCURS {<span class="term">n</span> [DEPENDING ON {<span class="term">itemname</span> | <span class="term">%variable</span>}] | UNKNOWN}]<br />
</p><br />
Where:<br />
<ul><br />
<li>LEN specifies the length as 1-15 bytes or as UNKNOWN if the length is determined by the request and the <var>Identify</var> statement establishes the length. </li><br />
<br />
<li>DIGITS specifies the length as 1-15 decimal digits. </li><br />
<br />
<li>TO specifies the last byte position of the item in the image as a number from 1 to 32767. The length or end (TO) position of the item is required unless provided in a DEFAULT statement. </li><br />
<br />
<li>DP, optional, specifies the number of decimal places to be retained when a number is stored in this item, that is, the number of places assumed present in data read from an external record. The value of n can range from 0 to 15. If this option is omitted, the default is zero. </li><br />
<br />
<li>SIGNED, optional and the default, specifies that the item can contain a positive or negative number. The sign stored with the number is a hexadecimal C for a positive number and D for a negative number. </li><br />
<br />
<li>UNSIGNED, optional, specifies that the item is always a positive number and that the sign stored with the number is a hexadecimal F. </li><br />
<br />
<li>INITIAL is optional and defines the value placed in the item by a <var>Prepare</var> statement and in unused occurrences when a record is read from a sequential file, VSAM file, or terminal into an image. If this option is omitted, the default initial value is zoned decimal zeros. </li><br />
<br />
<li>The mutually exclusive and optional AFTER and AT clauses define the location of the item in the image. For a complete discussion, see [[#Defining a string item|Defining a string item]]. </li><br />
<br />
<li>The optional OCCURS clause specifies that there are multiple occurrences of the item. For a complete discussion, see [[#Defining a string item|Defining a string item]]. <br />
</li><br />
</ul><br />
<br />
===Defining a floating point item===<br />
<br />
====Syntax====<br />
<p class="syntax">FLOAT {LEN {<span class="term">n</span> | UNKNOWN} TO <span class="term">position</span> <br />
[INITIAL {ZERO | <span class="term">number</span> | BLANK | NULL}] [ALIGN]<br />
[AFTER {<span class="term">itemname</span> | <span class="term">arrayname</span>} <br />
| AT {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imagname1</span> | <span class="term">arrayname</span>}] <br />
[OCCURS {<span class="term">n</span> [DEPENDING ON {<span class="term">itemname</span> | <span class="term">%variable</span>}] | UNKNOWN}]<br />
</p><br />
Where:<br />
<ul><br />
<li>LEN specifies the length as either 4, 8, or 16 bytes or as UNKNOWN if the length is determined by the request and the <var>Identify</var> statement establishes the length. <br />
<p><br />
Although you can move 16-byte floating-point values between data sets and files, intermediate results and %variables inside User Language are 8 bytes long. </p><br />
<p><br />
Arithmetic manipulations and data conversions retain only 15 significant decimal digits in 8 bytes.</p><br />
</li><br />
<br />
<li>TO specifies the last byte position of the item in the image as a number from 1 to 32767. The length or end (TO) position of the item is required unless provided in a DEFAULT statement. </li><br />
<br />
<li>INITIAL, optional, defines the value placed in the item by a <var>Prepare</var> statement and in unused occurrences when a record is read from a sequential file, VSAM file, or terminal into an image. If this option is omitted, the default initial value is a floating point zero. </li><br />
<br />
<li>ALIGN, optional, specifies that the item is aligned as follows: <br />
<ul><br />
<li>FLOAT LEN 4 on a fullword boundary</li><br />
<li>FLOAT LEN 8 on a doubleword boundary</li><br />
<li>FLOAT LEN 16 on a doubleword boundary </li><br />
<li>The item is aligned by inserting a SKIP statement preceding the item so that the item's location is on the correct boundary. In arrays, a SKIP statement is inserted at the end of each occurrence of the array and any parent array to make the length of each occurrence a multiple of the largest aligned item in the array. </li><br />
</ul><br />
<p><br />
The ALIGN option cannot be specified for an item: </p><br />
<ul><br />
<li>When length is defined a UNKNOWN.</li><br />
<li>When location is unknown during compilation because a previously defined item specified LEN UNKNOWN or OCCURS UNKNOWN. </li><br />
<li>Containing an AT clause that specifies a location that is not already aligned on the proper storage boundary. </li><br />
</ul></li><br />
<br />
<li>The AFTER and AT clauses are mutually exclusive and optionally define the location of the item in the image. For a complete discussion, see [[#Defining a string item|Defining a string item]]. </li><br />
<br />
<li>The OCCURS clause is optional and specifies that there are multiple occurrences of the item. For a complete discussion, see [[#Defining a string item|Defining a string item]]. <br />
</li><br />
</ul><br />
<br />
===Defining an exponential notation item===<br />
<br />
====Syntax====<br />
<p><br />
Define exponential notation items with this syntax: </p><br />
<p class="syntax">EFORMAT {LEN {<span class="term">n</span> | UNKNOWN} | TO <span class="term">position</span>} <br />
[PAD {BLANK | <span class="term">character</span> | NULL}] <br />
[STRIP | NOSTRIP] [JUSTIFY {LEFT | RIGHT}] <br />
[INITIAL {BLANK | <span class="term">string</span> | ZERO | NULL}] [DIGITS <span class="term">n</span>] <br />
[DP <span class="term">n</span>] [AFTER {<span class="term">itemname</span> | <span class="term">arrayname</span>}<br />
| AT {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imagname1</span> | <span class="term">arrayname</span>}]<br />
[OCCURS {<span class="term">n</span> [DEPENDING ON {<span class="term">itemname</span> | <span class="term">%variable</span>}] | UNKNOWN}]<br />
</p><br />
Where:<br />
<ul><br />
<li>LEN specifies the length either as 1-255 bytes or as UNKNOWN if the length is determined by the request and the <var>Identify</var> statement establishes the length. </li><br />
<br />
<li>TO specifies the last byte position of the item in the image as a number from 1 to 32767. The length or end (TO) position of the item is required unless provided in a DEFAULT statement. </li><br />
<br />
<li>PAD, optional, defines the fill character. If a value is shorter than an item to which it is being moved, the pad character fills the remainder of the item. Padding is done on the right end of items that are left-justified and on the left end for items that are right-justified. The pad character can be a single quoted character, a hexadecimal value expressed as X'hh', or a decimal number from 1 to 255. </li><br />
<br />
<li>STRIP, the default, specifies that the pad character is removed if an item value is extracted from an image. NOSTRIP specifies to keep the pad characters. </li><br />
<br />
<li>JUSTIFY, optional, specifies whether a value is to be left- or right-justified when moved into an item by an assignment statement. The default behavior is left-justified. </li><br />
<br />
<li>INITIAL is optional and defines the value placed in the item by a <var>Prepare</var> statement and in unused occurrences when a record is read from a sequential file, VSAM file, or terminal into an image. A single character zero is the default value. </li><br />
<br />
<li>DIGITS specifies the maximum number of significant digits &mdash; the total number of digits to the left and right of the decimal point. The value of n can be a number from 1 to 15. </li><br />
<br />
<li>DP specifies the number of digits to be placed to the right of the decimal point when a value is moved into the item. </li><br />
<br />
<li>The mutually exclusive and optional AFTER and AT clauses define the location of the item in the image. See [[#Defining a string item|Defining a string item]], for a complete discussion. </li><br />
<br />
<li>The optional OCCURS clause specifies that there are multiple occurrences of the item. See [[#Defining a string item|Defining a string item]] for a complete discussion. <br />
</li><br />
</ul><br />
<br />
===Item definition examples===<br />
<br />
====An image containing various item types====<br />
<p class="code">IMAGE GENERAL.LEDGER.RECORD<br />
GL.RECORD.TYPE IS STRING LEN 1<br />
GL.NUMBER IS ZONED LEN 10 DP 0<br />
GL.INV.TYPE IS STRING LEN 2<br />
GL.DEPRECIATION.CODE IS STRING LEN 2<br />
GL.BOOK.VALUE IS PACKED DIGITS 9 DP 2<br />
GL.YEARS.REMAINING IS BINARY LEN 4<br />
GL.QUANTITY.ON.HAND IS BINARY LEN 4<br />
GL.ITEM.SIZE IS FLOAT LEN 4<br />
END IMAGE<br />
</p><br />
<br />
====Using the AT and AFTER clauses====<br />
<p class="code">IMAGE PRINT.DATA<br />
PRINT.LINE1 IS STRING LEN 133 DP *<br />
PRINT.CC IS STRING LEN 1 AT PRINT.LINE1<br />
PRINT.ITEM1 IS STRING LEN 8<br />
SKIP 2 POSITIONS<br />
PRINT.ITEM2 IS STRING LEN 7<br />
SKIP 2 POSITIONS<br />
PRINT.ITEM3 IS STRING LEN 8<br />
SKIP 2 POSITIONS<br />
PRINT.ITEM4 IS STRING LEN 6<br />
PRINT.LINE2 IS STRING LEN 133 DP * AFTER PRINT.LINE1<br />
END IMAGE<br />
</p><br />
<p><br />
In the preceding example, <code>PRINT.LINE2</code> is placed adjacent to the end of <code>PRINT.LINE1</code>. Without the <var>After</var> clause, an <var>At</var> clause would be required to specify the numeric position of <code>PRINT.LINE2</code> in the image. </p><br />
<br />
==Defining arrays==<br />
<p><br />
An <b>array</b> contains multiple occurrences of a single item or a group of items. </p><br />
<br />
===Array definition statements===<br />
<p><br />
When an array is composed of a single item, the array can be defined by using the <var>Occurs</var> clause on the item definition or an <var>Array</var> statement. </p><br />
<p><br />
When an array is composed of more than one item, the array is defined by using an <var>Array</var> statement and is followed by definitions of the items that compose each element of the array. </p><br />
<p><br />
None of the items in an array or subordinate array can specify <var>Len Unknown</var> or <var>Occurs Unknown</var>.</p><br />
<br />
===Types of arrays===<br />
<p><br />
The format of the <var>Array</var> statement depends on which of the following types of arrays is being defined:</p><br />
<table><br />
<tr class="head"><br />
<th>For type of array... </th><br />
<th>The number of occurrences in the array is...</th><br />
</tr><br />
<tr><br />
<td>Fixed occurrence </td><br />
<td>Constant.</td><br />
</tr><br />
<tr><br />
<td>Depending </td><br />
<td>Constant as defined in the image, but a record that is read from a sequential file, VSAM file, or terminal or is written to a sequential file or terminal can contain a smaller number of occurrences.</td><br />
</tr><br />
<tr><br />
<td>Unknown </td><br />
<td>Not known. The maximum number of occurrences must be specified during evaluation by using the [[#Identify statement|Identify statement]]. </td><br />
</tr><br />
</table><br />
<br />
===ARRAY and END ARRAY statements===<br />
<p><br />
You define an array with an <var>Array</var> statement. The definitions of items and subordinate arrays follow the <var>Array</var> statement. </p><br />
<p><br />
You specify the end of the array with an <var>End Array</var> statement. <var>End Array</var> ends the definition of the array defined by the preceding <var>Array</var> statement. In addition, an <var>Image</var> or <var>End Image</var> statement ends all preceding <var>Array</var> definitions. </p><br />
<br />
===Defining a fixed occurrence array===<br />
<p><br />
A <b>fixed occurrence array</b> has a specified number of occurrences. Each external record read from a sequential file, VSAM file, or terminal or written to a sequential file or terminal is assumed to contain that number of occurrences. </p><br />
<br />
====Syntax====<br />
<p><br />
The format of the <var>Array</var> statement used to define a fixed occurrence array is:<br />
</p><br />
<p class="syntax">Array [<span class="term">arrayname</span>] Occurs <span class="term">n</span> <br />
[After {<span class="term">itemname</span> | <span class="term">arrayname</span>} <br />
| At {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imagname1</span> | <span class="term">arrayname</span>}<br />
</p><br />
Where:<br />
<ul><br />
<li><var class="term">arrayname</var> (optional) names the array. An array must be named if it is specified in the <var>At</var> clause of an image definition or in the <var>After</var> or <var>At</var> clauses in an item definition. </li><br />
<br />
<li><var class="term">n</var> is the number of occurrences of the items in the array, which can range from 1 to 32767.</li><br />
<br />
<li><var>After</var> and <var>At</var> clauses are mutually exclusive and optionally specify the location of the array in the image. See [[#Defining a string item|Defining a string item]] for detailed information. </li><br />
</ul><br />
<br />
====Example====<br />
<p><br />
The following example of an image contains a fixed occurrence array. In this example, each element of the <code>SALES.MONTHLY</code> array contains the item <code>SALES.TOTAL</code> and five occurrences of the item <code>SALES.BY.MODEL</code>.<br />
</p><br />
<p class="code">IMAGE SALES<br />
ARRAY SALES.MONTHLY OCCURS 12<br />
SALES.TOTAL IS PACKED DIGITS 9 DP 2<br />
SALES.BY.MODEL IS PACKED DIGITS 9 DP 2 -<br />
OCCURS 5<br />
END ARRAY<br />
END IMAGE<br />
</p><br />
<p><br />
The same image could be written as:</p><br />
<p class="code">IMAGE SALES<br />
ARRAY SALES.MONTHLY OCCURS 12<br />
SALES.TOTAL IS PACKED DIGITS 9 DP 2<br />
ARRAY OCCURS 5<br />
SALES.BY.MODEL IS PACKED DIGITS 9 DP 2<br />
END ARRAY<br />
END ARRAY<br />
END IMAGE<br />
</p><br />
<br />
===Defining a depending array===<br />
<p><br />
A <b>depending array</b> has a fixed number of occurrences in the image, but a smaller number of occurrences can be found in records read from a sequential file, VSAM file, or terminal or records written to a sequential file or terminal. </p><br />
<br />
====Depending variable====<br />
<p><br />
A depending variable is used to specify the actual number of occurrences that exist in the record. </p><br />
<p><br />
The depending variable is used in this manner:</p><br />
<ul><br />
<li>When a record is read from a sequential file, VSAM file, or terminal into an image, the record is assumed to contain only the number of occurrences specified by the value in the depending variable. The depending variable must have a value from zero to the maximum number of occurrences in the array. The occurrences specified in the variable are moved to the image and any remaining occurrences are initialized. When an image is created by a <var>Prepare Image</var> statement, space in the image is allocated for the maximum number of occurrences. </li><br />
<br />
<li>When a record is written from an image to a sequential file or terminal, the record is assumed to contain only the number of occurrences specified by the value in the depending variable. Therefore, the record is written with all unfilled occurrences removed. <br />
</li><br />
</ul><br />
<p><br />
If a subordinate array has a depending variable, the value of that variable applies to all occurrences of the outer array. </p><br />
<br />
====Restrictions====<br />
<p><br />
A depending array cannot be redefined in the current image or in any other image in the block. In addition, a depending array and the <var>After</var> or <var>At</var> clause are mutually exclusive. </p><br />
<br />
====Syntax====<br />
<p><br />
The form of the <var>Array</var> statement used for defining a depending array is:<br />
</p><br />
<p class="syntax">Array [<span class="term">arrayname</span>] Occurs <span class="term">n</span> Depending On {<span class="term">itemname</span> | <span class="term">%variable</span>}<br />
</p><br />
Where:<br />
<ul><br />
<li><var class="term">arrayname</var>, optional, names the array. An array must be named if it is specified in the AT clause of an image definition or in the <var>After</var> or <var>At</var> clauses of an item definition. </li><br />
<br />
<li><var class="term">n</var> is the number of occurrences of the items in the array, which can range from 1 to 32767.</li><br />
<br />
<li>The <var>Depending On</var> clause names a previously defined %variable or item within the image that contains the actual number of occurrences in an input record. An item used as the depending variable cannot: <br />
<ul><br />
<li>Be an array element</li><br />
<li>Vary in length, that is, be defined with <var>Len Unknown</var></li><br />
<li>Follow any varying length item or array in the image. </li><br />
</ul></li><br />
</ul><br />
<br />
====Example====<br />
<p><br />
The following example of an image contains an array with a depending variable is shown below. In this example, <code>SALES.MODELS</code> contains 15 occurrences of the item <code>SALES.MODEL.NO</code>. Therefore, the external record can contain from 0 to 15 occurrences.<br />
</p><br />
<p class="code">IMAGE SALES<br />
SALES.MODELS IS BINARY LEN 2<br />
ARRAY OCCURS 15 DEPENDING ON SALES.MODELS<br />
SALES.MODEL.NO IS PACKED DIGITS 9 INITIAL 0<br />
END ARRAY<br />
END IMAGE<br />
</p><br />
<p><br />
If a record is read into the previous image, the number of items defined by the value of the item <code>SALES.MODELS</code> are moved from the record into the array. Any occurrences of <code>SALES.MODEL.NO</code> not filled in the array from the record are initialized to zero. Before a record is written from the <code>SALES</code> image to a sequential file or terminal, the number of items defined by the value of the item <code>SALES.MODELS</code> are moved from the array into the record. Any unused occurrences are not present in the record written to the sequential file or terminal. </p><br />
<br />
===Defining an unknown array===<br />
<p><br />
An array must be defined as <b>unknown</b> when you cannot determine the maximum number of occurrences until after the data moves into the image. The number of occurrences in the array is specified as <var>Unknown</var>. During evaluation, the <var>Identify</var> statement is used to specify the number of occurrences in the array before any item in the array is referred to. </p><br />
<br />
====Syntax====<br />
<p><br />
The format of the <var>Array</var> statement used for defining an unknown array is:</p><br />
<p class="syntax">Array [<span class="term">arrayname</span>] Occurs Unknown <br />
[After {<span class="term">itemname</span> | <span class="term">arrayname</span>} <br />
| At {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imaginename1</span> <br />
| <span class="term">arrayname</span>}]<br />
</p><br />
Where:<br />
<ul><br />
<li><var class="term">arrayname</var> is required and names the array. This name is used to identify the array in <var>Identify</var> statements that specify the number of occurrences during evaluation. </li><br />
<br />
<li>The <var>After</var> and <var>At</var> clauses are mutually exclusive and optionally specify the location of the array in the image. See [[#Defining a string item|Defining a string item]] for detailed information. <br />
</li><br />
</ul><br />
<br />
====Example====<br />
<p><br />
This example illustrates the use of unknown arrays. In this example, the number of occurrences of the array <code>TRANSACTION</code> is contained in the item <code>TRANS.COUNT</code>. Before the items <code>TRANS.NO</code>, <code>TRANS.AMT</code>, or <code>TRANS.CUST</code> can be referred to, the <var>Identify</var> statement is executed to set the number of occurrences.<br />
</p><br />
<p class="code">TRANS.COUNT IS BINARY LEN 4<br />
ARRAY TRANSACTION OCCURS UNKNOWN<br />
TRANS.NO IS PACKED LEN 5<br />
TRANS.AMT IS PACKED LEN 7 DP 2<br />
TRANS.CUST IS STRING LEN 10<br />
END ARRAY<br />
</p><br />
<br />
==Referring to array elements==<br />
<p><br />
Individual items within an array are identified by <b>subscripts</b>. A subscript is enclosed in parentheses and can be any expression that evaluates to a number from 1 to the maximum size of the array. </p><br />
<br />
===Nested arrays===<br />
<p><br />
If arrays are nested, subscripts are required for each nesting level and are separated by commas. The outermost array is the first subscript. </p><br />
<br />
====Example====<br />
<p><br />
In this example, the fifth student in the second course would be referred to as <code>COURSE.STUDENT(2,5)</code>.<br />
</p><br />
<p class="code">IMAGE COURSE.DATA<br />
ARRAY OCCURS 20<br />
COURSE.NUMBER IS BINARY LEN 4<br />
COURSE.NAME IS STRING LEN 25<br />
COURSE.INSTRUCTOR IS STRING LEN 20<br />
COURSE.STUDENT IS STRING LEN 20 OCCURS 30<br />
END ARRAY<br />
END IMAGE<br />
</p><br />
<br />
==Initialization of array values==<br />
<p><br />
<var class="product">Model&nbsp;204</var> lets you specify multiple value assignments into array dimensions within a single User Language assignment statement by adding an asterisk (<tt>*</tt>) as the subscript value. Using the asterisk is valid for percent variable arrays and image arrays. </p><br />
<br />
====Example 1====<br />
<p><br />
The following statement sets all elements in all dimensions to 0:</p><br />
<p class="code">%ARRAY.ITEM (*,*,*) = 0<br />
</p><br />
<br />
====Example 2====<br />
<p><br />
If an array is defined as occurs 3, occurs 4, occurs 2, <code>%ARRAY.ITEM(*,2,*) = 9</code> is equivalent to the following:</p><br />
<p class="code">%ARRAY.ITEM(1,2,1) = 9<br />
%ARRAY.ITEM(1,2,2) = 9<br />
%ARRAY.ITEM(2,2,1) = 9<br />
%ARRAY.ITEM(2,2,2) = 9<br />
%ARRAY.ITEM(3,2,1) = 9<br />
%ARRAY.ITEM(3,2,2) = 9<br />
</p><br />
<br />
====Example 3====<br />
<p><br />
The following example prints <code>AAA</code> and <code>100</code>:<br />
</p><br />
<p class="code">BEGIN<br />
IMAGE TEST<br />
ARRAY OCCURS 5<br />
PART1 IS BINARY LEN 2<br />
PART2 IS FLOAT LEN 8<br />
PART3 IS STRING LEN 3 OCCURS 4<br />
PART4 IS FLOAT LEN 8 OCCURS 2<br />
END ARRAY<br />
END IMAGE<br />
PREPARE IMAGE TEST<br />
%TEST:PART3(3,*) = 'AAA'<br />
%TEST:PART4(*,2) = 100<br />
PRINT %TEST:PART3(3,4)<br />
PRINT %TEST:PART4(2,2)<br />
END<br />
</p><br />
<br />
====Example 4====<br />
<p><br />
The asterisk is not valid on the right side of a SOUL assignment statement. The following statement is invalid and causes a compilation error:</p><br />
<p class="code">%X = %ARRAY.ITEM(*,*,*)<br />
</p><br />
<br />
==Using Large Object fields with a very large array==<br />
<p><br />
If you have a very large array that is densely populated and not a preallocated field, you may improve performance by storing this array of data in a Large Object field.</p><br />
<p><br />
When an array of data is used as a field that is not preallocated, then each field reference includes the overhead of walking through the record to find that fieldname(fieldoccurrence) value. </p><br />
<p><br />
With a Large Object field, you can directly address each item using the <var class="term">offset,length</var> syntax available for Large Object fields.</p><br />
<p><br />
There is one Table B access to retrieve the Large Object descriptor, and one Table&nbsp;E access to read the page that your data resides on, no matter how far into the object the data resides.</p><br />
<p><br />
There may be a substantial CPU reduction for applications that reference large arrays as Large Object data instead of holding each array entry in a field occurrence.</p><br />
<br />
<p class="warn"><b>Cautionary usage note:</b> Disk space utilization: Each Large Object field requires the total Large Object length rounded up to the next 6184 bytes of space.This is because Large Object data is a collection of Table E pages; you cannot allocate just part of a page.</p><br />
<br />
==Defining reserved space==<br />
<p><br />
The format of the entire block does not have to be specified in an image definition. When items are not contiguous, space must be reserved to correctly position the items. </p><br />
<p><br />
Space is reserved automatically by an <var>At</var> clause that places an item beyond the end of the last defined item. </p><br />
<br />
===Skip statement===<br />
<p><br />
Space is reserved explicitly by using the <var>Skip</var> statement. The space reserved by a <var>Skip</var> statement can be initialized by a <var>Prepare</var> statement but cannot be accessed. </p><br />
<br />
====Syntax====<br />
<p><br />
The format of the <var>Skip</var> statement for reserving space is:<br />
</p><br />
{{Template:Skip Position statement syntax}}<br />
Where:<br />
<ul><br />
<li>The <var><i>itemname</i> Is</var> clause (optional) names a reserved area that can be referred to by an <var>After</var> or <var>At</var> clause.</li><br />
<br />
<li><var class="term">n</var> is the number of bytes to be reserved. A maximum of 32767 bytes can be reserved.</li><br />
<br />
<li>The <var>Initial</var> clause indicates the character with which the area is filled by <var>Prepare</var> and <var>Identify</var> statements. Options are as follows:<br />
<ul><br />
<li>character &mdash; a single quoted character, a decimal number from 1 to 255, or a hexadecimal value expressed as <code>X'hh'</code></li><br />
<br />
<li><var>Blank</var> &mdash; white spaces</li><br />
<br />
<li><var>Null</var> &mdash; binary zeros </li><br />
</ul><br />
<p><br />
If the <var>Initial</var> clause is omitted, <var>Null</var> is the default. </p></li><br />
</ul><br />
<br />
====Example====<br />
<p><br />
This sample <var>Skip</var> statement reserves two bytes before the next image item: </p><br />
<p class="code">SKIP 2 POSITIONS<br />
</p><br />
<br />
==DEFAULT TYPE and DEFAULT SKIP statements==<br />
<p><br />
You can provide default values for image item options to eliminate repetition of these options on each item definition, using: </p><br />
<ul><br />
<li><var>Default Type</var></li><br />
<li><var>Default Skip</var> </li><br />
</ul><br />
<br />
===DEFAULT TYPE statement===<br />
<p><br />
The <var>Default Type</var> statement lets you set default option values for each item type. The options specified on a <var>Default Type</var> statement for an item type are applied to each item of that type defined between the default statement and the next default statement of the same item type. </p><br />
<br />
====Syntax====<br />
<p><br />
The format of the <var>Default Type</var> statement is:</p><br />
<p class="syntax">Default [Type] <span class="term">type</span> <span class="term">options</span><br />
</p><br />
Where:<br />
<ul><br />
<li>The optional <var>Type</var> keyword specifies a default data type for any item definition that does not explicitly define the data type. Without the <var>Type</var> keyword, the statement defines the default option values for an item type without defining the default item type. </li><br />
<br />
<li><var class="term">type</var> specifies the data type of the item. Valid values are <var>String</var>, <var>Binary</var>, <var>Float</var>, <var>Packed</var>, <var>Zoned</var>, or <var>EFormat</var>.</li><br />
<br />
<li><var class="term">options</var> specifies any of the options that are valid for the item type except for the <var>To</var>, <var>After</var>, <var>At</var>, and <var>Occurs</var> clauses. </li><br />
</ul><br />
<br />
===DEFAULT SKIP statement===<br />
<p><br />
The <var>Default Skip</var> statement specifies the default length or initial value for a <var>Skip</var> statement or an implied skip. It can appear anywhere in an image definition and remains in effect until the next <var>Default Skip</var> statement.</p><br />
<br />
====Syntax====<br />
<p><br />
The format of the <var>Default Skip</var> statement is:</p><br />
<p class="syntax">Default Skip <span class="term">n</span> Position[s] <br />
[Initial {Null | '<span class="term">character</span>' | Blank}]<br />
</p><br />
Where:<br />
<ul><br />
<li><var class="term">n</var> is a positive integer that specifies the number of bytes to be reserved. A maximum of 32767 bytes can be reserved.</li><br />
<br />
<li>The <var>Initial</var> clause indicates the fill character for <var>Prepare</var> and <var>Identify</var> statements. Options are as follows: <br />
<ul><br />
<li><var class="term">character</var> &mdash; a single quoted character, a decimal number from 1 to 255, or a hexadecimal value expressed as <code>X'hh'</code>. </li><br />
<br />
<li><var>Blank</var> &mdash; white space</li><br />
<br />
<li><var>Null</var> &mdash; binary zeros </li><br />
</ul><br />
<p><br />
If the <var>Initial</var> clause is omitted, <var>Null</var> is the default. </p></li><br />
</ul><br />
<br />
===Example of Default statements===<br />
<p><br />
The following examples show how an image can be described without and then with <var>Default</var> statements.</p><br />
<br />
====Without Default statements====<br />
<p class="code">IMAGE SALES<br />
SALES.YEAR.TOTAL IS PACKED DIGITS 7 DP 2<br />
SALES.MONTH.TOTAL IS PACKED DIGITS 7 DP 2<br />
SALES.REP.NO IS PACKED DIGITS 5<br />
SALES.REP.NAME IS STRING LEN 20<br />
SALES.REP.ADDRESS.1 IS STRING LEN 20<br />
SALES.REP.ADDRESS.2 IS STRING LEN 20<br />
END IMAGE<br />
</p><br />
<br />
====With Default statements====<br />
<p class="code">IMAGE SALES<br />
DEFAULT TYPE STRING LEN 20<br />
DEFAULT PACKED DIGITS 7 DP 2<br />
<br />
* THE FOLLOWING TWO ITEMS DEFAULT TO DIGITS 7 DP 2<br />
<br />
SALES.YEAR.TOTAL IS PACKED<br />
SALES.MONTH.TOTAL IS PACKED<br />
<br />
* DP 0 IS NECESSARY ON THE NEXT LINE IN ORDER TO AVOID<br />
* THE DEFAULT OF 2<br />
<br />
SALES.REP.NO IS PACKED DIGITS 5 DP 0<br />
<br />
* THE FOLLOWING 3 ITEMS DEFAULT TO STRING LEN 20<br />
<br />
SALES.REP.NAME<br />
SALES.REP.ADDRESS.1<br />
SALES.REP.ADDRESS.2<br />
END IMAGE<br />
</p><br />
<br />
==Processing images==<br />
<p><br />
Once a block is defined, you can use the following statements to process external records and to manipulate a block of storage. </p><br />
<table><br />
<tr class="head"><br />
<th>Statement</th><br />
<th>Action undertaken</th><br />
</tr><br />
<br />
<tr><br />
<td><var>Close</var></td><br />
<td>Closes a sequential file, VSAM file, or terminal opened by the request.</td><br />
</tr><br />
<br />
<tr><br />
<td><var>Identify</var></td><br />
<td>Defines an active image and establishes the length for items or array occurrences defined as <var>Unknown</var>.</td><br />
</tr><br />
<br />
<tr><br />
<td><var>Open</var></td><br />
<td>Opens a sequential file, VSAM file, or terminal for processing.</td><br />
</tr><br />
<br />
<tr><br />
<td><var>Position</var></td><br />
<td>Specifies the next record to be read sequentially in a VSAM KSDS file.</td><br />
</tr><br />
<br />
<tr><br />
<td><var>Prepare</var></td><br />
<td>Initializes an image.</td><br />
</tr><br />
<br />
<tr><br />
<td><var>Read Image</var></td><br />
<td>Reads a record from a sequential file, VSAM file, or terminal.</td><br />
</tr><br />
<br />
<tr><br />
<td nowrap><var>Release Position</var></td><br />
<td>Terminates the browse operation established by a <var>Position</var> statement.</td><br />
</tr><br />
<br />
<tr><br />
<td><var>Write Image</var>E</td><br />
<td>Writes a record to a sequential file or to a terminal.</td><br />
</tr><br />
</table><br />
<br />
===Key field for VSAM files===<br />
<p><br />
When the VSAM key is not in character format, special handling is required to supply the key in the format required by VSAM. If the key is supplied as a %variable or image item that has a numeric type, the <var>Read Image</var> and <var>Position</var> statements attempt to convert the numeric value to string.</p><br />
<p><br />
The suggested technique to resolve this problem is to define the image of the record with the key field defined in the format expected by VSAM and redefined as a string of the same length. The key value is moved to the key item and the string item name is provided in the <var>Read</var> or <var>Position</var> statement. </p><br />
<p><br />
An example of this technique for a VSAM file that has a 4-byte binary key is illustrated below:</p><br />
<p class="code">IMAGE VSAM.REC<br />
KEY IS BINARY LEN 4<br />
KEY.STR IS STRING LEN 4 AT KEY<br />
.<br />
(additional items)<br />
.<br />
END IMAGE<br />
OPEN DATASET VSAMFILE<br />
IF $Status NE 0 THEN<br />
PRINT $Errmsg<br />
STOP<br />
END IF<br />
%KEYVAL = $READ('KEY VALUE = ')<br />
PREPARE VSAM.REC<br />
%VSAM.REC:KEY = %KEYVAL<br />
READ IMAGE VSAM.REC FROM VSAMFILE KEY EQ %VSAM.REC:KEY.STR<br />
.<br />
.<br />
.<br />
</p><br />
<br />
==Close statement==<br />
<p><br />
The <var>Close</var> statement lets the request close a sequential file, VSAM file, or a terminal opened by the request. </p><br />
<br />
====Syntax====<br />
<p><br />
The format of the <var>Close</var> statement for external I/O is:</p><br />
<p class="syntax"><span class="literal">Close</span> {<span class="literal">Dataset</span> | <span class="literal">External</span>} {<span class="term">ext-filename</span> | <span class="term">%variable</span>}<br />
| [<span class="literal">External</span>] <span class="literal">Terminal</span><br />
</p><br />
Where:<br />
<ul><br />
<li>You must specify either the <var>Dataset</var>, <var>External</var>, or <var>Terminal</var> keyword.</li><br />
<br />
<li>The <var>Dataset</var> keyword specifies that the entity to be closed is a non-<var class="product">Model&nbsp;204</var> file, that is, a sequential or VSAM file. </li><br />
<br />
<li>The <var>External</var> keyword specifies that the entity to be closed is a non-<var class="product">Model&nbsp;204</var> file, that is, a sequential or VSAM file, or a terminal. </li><br />
<br />
<li><var class="term">ext-filename</var> specifies the name of the sequential or VSAM file to close, that is, the name used in the <var>Open</var> statement. Also, a %variable can provide the file name.</li><br />
<br />
<li><var>Terminal</var> specifies that the terminal currently opened by the <var>Open</var> statement should be closed. Also, a %variable can supply the word <var>Terminal</var>. </li><br />
</ul><br />
<br />
===Closing a Model 204 file===<br />
<p><br />
The <var>Close</var> statement can be used only for closing external files or terminals. To close a <var class="product">Model&nbsp;204</var> file, you may use the <var>[[$Close]]</var> function within a <var class="product">SOUL</var> request, or the <var>[[CLOSE command|CLOSE]]</var> command outside a request.</p><br />
<br />
==Identify statement==<br />
<p><br />
The <var>Identify</var> statement establishes: </p><br />
<ul><br />
<li>Active image, if multiple images define the same block.</li><br />
<li>Length of items that were defined as <var>Inknown</var>.</li><br />
<li>Number of occurrences for arrays that were defined as <var>Unknown</var>. </li><br />
</ul><br />
<br />
====Syntax====<br />
<p><br />
The complete syntax for the <var>Identify</var> statement follows. The form of the <var>Identify</var> statement used to perform each of these activities is then discussed in detail.<br />
</p><br />
{{Template:Identify statement syntax}}<br />
Where:<br />
<ul><br />
<li><var class="term">imagename</var> refers to an image that was previously described in an image definition.</li><br />
<br />
<li><var class="term">%imagename</var>:<var class="term">itemname</var> is an item that was defined with <var>Len Unknown</var> or <var>Occurs Unknown</var>. </li><br />
<br />
<li>The <var>Len</var> clause specifies the length in bytes of the item or a %variable that contains the length. The length cannot exceed 255 bytes. </li><br />
<br />
<li><var class="term">%imagename</var>:<var class="term">arrayname</var> is an array that was defined with <var>Occurs Unknown</var>.</li><br />
<br />
<li>The <var>Occurs</var> clause specifies the number of occurrences of the item or a %variable that contains the number. The number of occurrences cannot exceed 32767. </li><br />
</ul><br />
<br />
===Establishing an active image===<br />
<p><br />
Use the following form of the <var>Identify</var> statement to switch the active image to the named imaged, when multiple images define the same block:</p><br />
<p class="syntax">Identify [Image] <span class="term">imagename</span><br />
</p><br />
<p><br />
The <var>Identify</var> statement also initializes the items, if any, that were not initialized by a previous <var>Read Image</var> or <var>Prepare</var> statement. <br />
</p><br />
<p class="note"><b>Note:</b> Use the <var>Identify</var> statement instead of a <var>Prepare</var> statement for requests in which you want to maintain data passed in an image.</p><br />
<br />
====Use with global images====<br />
<p><br />
When used with global images, the <var>Identify Image</var> statement, can cause request termination due to either: </p><br />
<ul><br />
<li>Definition mismatches. See [[Global features#Consistency checks performed|Consistency checks performed]] for a description.</li><br />
<br />
<li>Insufficient space in [[Defining_the_runtime_environment_(CCAIN)#Understanding the global variable table (GTBL)|GTBL]].<br />
</li><br />
</ul><br />
<p><br />
The <var>Identify Image</var> statement does not refresh a global image, if a copy of that image is already in GTBL. The <var>Identify Image</var> statement simply makes the specified image active. See [[Global features#Images and screen processing|Images and screen processing]] for a diagram showing the structure of GTBL followed by a discussion of performance considerations with respect to the definition of global objects. </p><br />
<br />
===Establishing lengths for Unknown items===<br />
<p><br />
Use the following form of the <var>Identify</var> statement to set the length for items defined with <var>Len Unknown</var>:<br />
</p><br />
<p class="syntax">Identify <span class="term">%imaginename</span>:<span class="term">itemname</span> Len {<span class="term">n</span> | <span class="term">%variable</span>}<br />
</p><br />
<p><br />
The location of an item is established when the length of every preceding variable length item and array is established. The length cannot be changed after it is defined by an <var>Identify</var> statement. If you must enlarge an array after the length is established, copy the image to another image where the array is larger using assignment statements.</p><br />
<br />
===Establishing occurrences for Unknown arrays===<br />
<p><br />
Use the following form of the <var>Identify</var> statement to set the number of occurrences for arrays or items defined with <var>Occurs Unknown</var>:<br />
</p><br />
<p class="syntax">Identify {<span class="term">%imagename</span>:<span class="term">arrayname</span> <br />
| <span class="term">%imagename</span>:<span class="term">itemname</span>} Occurs {<span class="term">n</span> | <span class="term">%variable</span>}<br />
</p><br />
<p><br />
You cannot change the number of occurrences after they are defined by an <var>Identify</var> statement. If you issue an <var>Identify</var> statement for an item whose length was previously set by an <var>Identify</var> statement, the request is cancelled. </p><br />
<p><br />
You must issue a <var>Prepare</var> statement before another <var>Identify</var> statement can be issued on the same item. If you need to enlarge an array after the number of occurrences is established, you must copy the image to another image where the array is larger using assignment.</p><br />
<br />
==MODIFY BUFFER statement==<br />
<br />
====Function====<br />
<p><br />
Manages the Universal Buffer size and can also keep messages or overwrite them with a fill character.</p><br />
<br />
====Syntax====<br />
<p class="syntax">MODIFY BUFFER [SIZE=<span class="term">n</span> | <span class="term">%variable</span> [PRESERVE | NOPRESERVE]] <br />
[FILL [X'<span class="term">nn</span>' | C'<span class="term">x</span>'] | CLEAR]<br />
</p><br />
Where:<br />
<ul><br />
<li>BUFFER (formerly and still accepted as MQ_BUFFER) specifies the Universal Buffer area. </li><br />
<br />
<li>SIZE specifies the number of bytes allocated for the BUFFER area. If the value of the SIZE option enlarges or shrinks the current buffer, the buffer contents are overwritten.</li><br />
<br />
<li>PRESERVE specifies to retain the buffer contents. If a storage allocation error occurs, the value of 8 is set in the $STATUS return code (which is the standard WebSphere MQ value for this error). <br />
<p><br />
If the data was truncated when the buffer was shrunk, then the value of 14 for data truncation is set in $STATUS, although the operation succeeds.</p><br />
</li><br />
<br />
<li>CLEAR option, the default, specifies to overwrite the buffer with X'00'.</li><br />
<br />
<li>FILL option specifies a fill-character to use; for example, X'40' fills with blanks. The FILL option can also be a decimal number and/or the equals sign (=), or it can be an alpha character (C) and/or the equals sign. If a value is not specified after the keyword FILL, the default value is the CLEAR option.<br />
<p><br />
If the FILL or CLEAR option is specified, the behavior of MODIFY BUFFER statement depends on what other options are used:</p><br />
<table><br />
<tr class="head"><br />
<th>If... </th><br />
<th>Then...</th><br />
</tr><br />
<br />
<tr><br />
<td>FILL/CLEAR, SIZE, and NOPRESERVE are specified, or FILL is specified without SIZE </td><br />
<td>Entire buffer is filled with the fill character.</td><br />
</tr><br />
<br />
<tr><br />
<td>FILL/CLEAR, SIZE, and PRESERVE are specified </td><br />
<td>Fill character is used to fill the new portion of the buffer after the preserved data only if the buffer size is increased. </td><br />
</tr><br />
</table><br />
</li><br />
</ul><br />
<br />
====Usage====<br />
<p><br />
The MODIFY BUFFER statement requires that you specify at least one option. </p><br />
<p><br />
When you overwrite the contents of BUFFER area, the value of $Buffer_Used is set to zero and the value of $Buffer_Position is set to one. See [[$Buffer_Size#$Buffer_Size|$Buffer_Size]] and [[$Buffer_Used#$Buffer_Used|$Buffer_Used]].</p><br />
<p><br />
If you exceed the 2-gigabyte limit on the size of BUFFER, $STATUS returns a value of 34. A negative number or a number less than UBUFSZ is changed to UBUFSZ.</p><br />
<br />
<div id="openExt"></div><br />
==<b id="OPEN statement"></b>Open statement==<br />
<p><br />
The <var>Open</var> statement can be used to open a sequential file, VSAM file, or terminal for processing. </p><br />
<br />
====DEFINE DATASET required====<br />
<p><br />
Before a VSAM file or a DOS sequential file can be opened, it must previously have been<br />
defined using the <var>[[DEFINE DATASET command|DEFINE DATASET]]</var> command. </p><br />
<br />
====Syntax====<br />
<p><br />
The format of the <var>Open</var> statement for external I/O is:</p><br />
{{Template:Open (External I/O) statement syntax}}<br />
Where:<br />
<ul><br />
<li>Either the <var>Dataset</var> or <var>External</var> keyword must be specified to open a sequential (non-<var class="product">Model 204</var>) file. <var>Dataset</var> and <var>External</var> should not be specified for opening <var class="product">Model 204</var> files. </li><br />
<br />
<li><var class="term">ext-filename</var> specifies the name of external file (that is, the sequential or VSAM file) to be opened. The external file name is the name specified in the <var>DEFINE DATASET</var> command or, for sequential files, the OS DDNAME or CMS FILEDEF. The external file name can be provided in a %variable.</li><br />
<br />
<li><var>Terminal</var> specifies that the entity to be opened is a terminal. The word <code>Terminal</code> can be provided in a %variable. </li><br />
<br />
<li>The required <var>For</var> clause specifies the type of I/O processing that is performed on the opened external file or terminal. An external file or terminal must be opened for at least <var>Input</var> to be read into an <var>Image</var> and opened for at least <var>Output</var> to write data from an <var>Image</var>.<br />
<p><br />
The <var>Input Output</var>, <var>Output Input</var>, and <var>InOut</var> combination options are valid only for the <var>Terminal</var> keyword. </p><br />
</li><br />
<br />
<li>The <var>Password</var> clause is required for only password protected VSAM data sets. The clause generates an error when used with an <var>Open Terminal</var> statement, but is ignored in all other cases.<br />
<p><br />
With the <var>Password</var> clause, the password can be specified directly or can be provided as the value of a %variable. Password validation is performed during evaluation and is not checked during compilation. </p><br />
</li><br />
</ul><br />
<br />
===Usage notes===<br />
<br />
====Open statement in remote context====<br />
<p><br />
This form of the <var>Open</var> statement is not supported in remote context. Using the <var>At</var> keyword with any of the keywords <var>Dataset</var>, <var>External</var>, or <var>Terminal</var> generates the following error message, which is not displayed on the terminal, but can be retrieved with the <var>$Errmsg</var> function:</p><br />
<p class="code">M204.1497: Remote specification conflicts with open type<br />
</p><br />
<br />
====Multiple Opens of external data sets====<br />
<p><br />
An attempt to open an already open external data set results in request cancellation with the following error message:</p><br />
<p class="code">M204.2153 Dataset <i>name</i> is already open<br />
</p><br />
<br />
====Clearing messages====<br />
<p><br />
An <var>Open</var> statement resets<br />
the messages accessed by the <var>[[$Fsterr]]</var> and <var>[[$Errmsg]]</var> functions. You may also clear the messages<br />
using the <var>[[$ErrClr]]</var> function.</p><br />
<br />
====See also====<br />
<ul><br />
<li>An <var>[[Open statement|Open]]</var> statement without<br />
the <var>Dataset</var> or <var>External</var> keyword is used to open a <var class="product">Model&nbsp;204</var> file or group, similar to the <var>OPEN</var> command (for example, the [[OPEN FILE command]]). </li><br />
<br />
<li>The <var>[[Dataset class|Dataset]]</var> class can also be used to access external data sets. </li><br />
</ul><br />
<br />
==Position statement==<br />
<p><br />
The <var>Position</var> statement specifies the next record to be read sequentially in a VSAM KSDS file. An established position is used by the <var>Read next</var> statement to locate the next record to be returned. A new position can be established at any time by executing another <var>Position</var> statement. </p><br />
<p><br />
This <var>Position</var> statement is not to be confused with the <var>Position</var> statement used to recall a position in a found set or list which has been saved using the <var>Remember</var> option during <var>For</var> loop processing. See [[Global features#Position statement|Position statement]].</p><br />
<br />
====Syntax====<br />
<p><br />
The format of the <var>Position</var> statement is:</p><br />
<p class="syntax">Position {<span class="term">ext-filename</span> | <span class="term">%variable</span>} <br />
At Key <span class="term">operator</span> {<span class="term">value</span> | <span class="term">%variable</span>}<br />
</p><br />
Where:<br />
<ul><br />
<li><var class="term">ext-filename</var> is the name of the VSAM file specified in the <var>Open</var> statement. The name can be provided as the value of a %variable. <br />
<p><br />
If <var class="term">ext-filename</var> is provided as a literal, it cannot be the name of a found set or list.</p><br />
</li><br />
<br />
<li><var class="term">operator</var> specifies that the key of the record to be retrieved must be equal to or greater than or equal to the specified value. Valid operators are: <code>=</code>, <code>>=</code>, <code>EQ</code>, or <code>GE</code>.</li><br />
<br />
<li><var class="term">value</var> specifies the key at or beyond which the file is positioned for subsequent reads. The key can be provided as the value of a %variable.<br />
<p><br />
If <var class="term">value</var> is a null string, a key of binary zeros is substituted. The first record in the file is returned if the operator is <code>>=</code> or <code>GE</code>. If the operator is <code>=</code> or <code>EQ</code>, a record is found only if it has a key of all binary zeros. </p><br />
<p><br />
If the length of <var class="term">value</var> is less than the length of the VSAM key, the key is treated as generic. A generic key search is satisfied when the value matches the same number of characters at the beginning of the VSAM key. The portion of the VSAM key that is longer than the value is ignored in the comparison.</p><br />
<p><br />
If the VSAM key is not a character string, special handling is required. For information on how to specify the key when the key is not a string, refer to [[#Key field for VSAM files|Key field for VSAM files]]. </p></li><br />
</ul><br />
<br />
==<b id="PrepareStmtImage"></b>Prepare statement==<br />
<p><br />
The <var>Prepare</var> statement initializes an image and makes it the active image. This is required when image items are accessed prior to reading an external record into the image. <var>Prepare</var> initializes the block associated with the image with the values specified in the <var>Initial</var> clauses of the item definitions or <var>Default</var> statements. </p><br />
<p><br />
Previous identifications of lengths of items defined as length <var>Unknown</var> or number of occurrences of arrays defined with <var>Occurs Unknown</var> are lost. The <var>Identify</var> statement must be executed again to establish length or number of occurrences. </p><br />
<br />
====Syntax====<br />
<p><br />
The format of the <var>Prepare</var> statement is:</p><br />
<p class="syntax">Prepare [Image] <span class="term">imagename</span><br />
</p><br />
<p><br />
where <var class="term">imagename</var> refers to an image that was previously described in an image definition. The keyword <var>Image</var> is required if <var class="term">imagename</var> is <var>Image</var>, <var>Menu</var>, or <var>Screen</var>.</p><br />
<br />
===Use with global images===<br />
<p><br />
The <var>Prepare Image</var> statement, when used with global images, can cause request termination due to either: </p><br />
<ul><br />
<li>Definition mismatches (see [[Global features#Consistency checks performed|Consistency checks performed]] for a description for global images)</li><br />
<br />
<li>Insufficient space in [[Defining_the_runtime_environment_(CCAIN)#Understanding the global variable table (GTBL)|GTBL]].<br />
</li><br />
</ul><br />
<br />
==<b id="READ IMAGE statement"></b><b id="Read Image statement"></b><b id="Read Image statement"></b>Read Image statement==<br />
<p><br />
The <var>Read</var> <var>Image</var> statement reads a record from a sequential or VSAM file or terminal into the image and sets the image as the active image. Or, the <var>Read</var> <var>Image</var> statement reads the contents of the Universal Buffer. </p><br />
<br />
===Syntax===<br />
{{Template:Read Image statement syntax}}<br />
Where:<br />
<ul><br />
<li><var class="term">imagename</var> is an image that was previously described in an image definition. The keyword <var>Image</var> is required if imagename is <var>Image</var>, <var>Menu</var>, or <var>Screen</var>. <var class="term">imagename</var> also specifies a message to read in the Universal Buffer area.</li><br />
<br />
<li>The <var>From</var> clause determines which use of the <var>Read</var> <var>Image</var> statement to employ:<br />
<ul><br />
<li>Reading Large Object data from the Universal Buffer</li><br />
<li>Reading from a sequential file or the terminal</li><br />
</ul></li><br />
<br />
<li><var>Buffer</var> (formerly, and still accepted as <var>Mq_Buffer</var>) specifies the Universal Buffer area.</li><br />
<br />
<li><var>Position</var> must be in the range 1-16,777,216. If not, the operation returns <code>[[$Status]]=10</code> and <code>[[$StatusD]]=20</code> return codes. <var class="term">%pvariable</var> or <var class="term">n</var> specifies where in the buffer to begin reading.<br />
<p><br />
If <var>Position</var>=<var class="term">%pvariable</var> is specified and <var class="term">%pvariable</var> is greater than <var>[[$Buffer_Used]]</var>, the operation returns <code>$Status=10</code> and <code>$StatusD=20</code>.</p><br />
<p><br />
The starting position in the buffer is determined by <var>Position</var>=<var class="term">%pvar</var>, if that was specified; <var>[[$Buffer_Position]]</var>, otherwise.</p><br />
<p><br />
The ending position in the buffer is determined by the lowest of starting position, plus <var class="term">%lvariable</var>, if <var>Maxlen</var>=<var class="term">%lvariable</var> was specified as the value of <var>$Buffer_Used</var>.</p><br />
</li><br />
<br />
<li><var>Maxlen</var>=%lvariable specifies the maximum number of bytes to copy into the image. The actual number copied might be less than that, either because the number of bytes available in the Universal Buffer (from the starting position) is less, or because the size of the image is less.<br />
<p><br />
<var>Maxlen</var> must be in the range 1-32,767. If not, the operation returns <code>$Status=10</code> and <code>$StatusD=19</code>.</p><br />
</li><br />
<br />
<li><var class="term">ext-filename</var> specifies that records are read from a previously opened sequential or VSAM file. The name of the file can be provided as the value of a %variable.</li><br />
<br />
<li><var>Terminal</var> specifies that records are read from the terminal. The keyword <var>Terminal</var> can be provided as the value of a %variable. </li><br />
<br />
<li>The optional <var>Prompt</var> clause is used with only the <var>Terminal</var> option. It specifies to display a prompt sign before the read is performed. Prompting is especially useful for synchronizing communication between the SOUL request and Host Language program.<br />
<p><br />
The <var>Prompt</var> string can be as many as 255 characters. The string can be provided as a string type %variable.</p><br />
</li><br />
<br />
<li>The <var>Next</var> option reads the next record in the file. <var>Next</var> is the default, if the <var>Key</var> clause is omitted. A <var>Read</var> <var>Image</var> statement with the <var>Next</var> option can be executed only following an <var>Open</var>, <var>Position</var>, or <var>Read</var> <var>Next</var> statement. </li><br />
<br />
<li>The <var>Key</var> clause identifies the record to read. The <var>Key</var> clause is valid only for VSAM files and the value is converted to a string. A <var>Read</var> <var>Image</var> statement with the <var>Key</var> clause automatically performs a <var>Release</var> <var>Position</var>.<br />
<p><br />
Key clause options are <var class="term">operator</var> and <var class="term">value</var>:</p><br />
<ul><br />
<li><var class="term">operator</var> specifies that the key of the record to be retrieved must be equal to or greater than or equal to the specified value. Valid operators are: <code>=</code>, <code>>=</code>, <var>Eq</var>, or <var>Ge</var>.</li><br />
<br />
<li><var class="term">value</var> is the key that locates the record. It can be supplied in a %variable.<br />
<p><br />
If the value is a null string, a key of binary zeros is substituted. The first record in the file is returned, if the operator is <code>>=</code> or <var>Ge</var>. If the operator is <code>=</code> or <var>Eq</var>, a record is found only ifit has a key of all binary zeros. If the length of the value is less than the length of the VSAM key, the key is treated as generic. A generic key search is satisfied when the value matches the same number of characters at the beginning of the VSAM key. The portion of the VSAM key that is longer than the value is ignored in the comparison.</p><br />
</li><br />
</ul><br />
<p><br />
If the VSAM key is not a character string, special handling is required. For information on how to specify the key when the key is not a string, refer to [[#Key field for VSAM files|Key field for VSAM files]]. </p><br />
</li><br />
</ul><br />
<br />
===Usage===<br />
<p><br />
This statement is valid only if the file or terminal from which the record is read is currently open for <var>Input</var>, <var>Input</var> <var>Output</var>, or <var>InOut</var>. <var>Read</var> <var>Image</var> processing reads data until the Universal Buffer is exhausted, or the image is filled. </p><br />
<p><br />
The part of the message selected is copied from the Universal Buffer to the image:</p><br />
<ul><br />
<li>Contents of the Universal Buffer are unchanged.</li><br />
<br />
<li><var>$Buffer_Used</var> is unchanged.</li><br />
<br />
<li><var>$Buffer_Position</var> is set to the byte after the last byte copied.</li><br />
<br />
<li>No error indication is given, if the image is not big enough to hold the data.<br />
</li><br />
</ul><br />
<br />
===Buffer area positioning===<br />
<p><br />
If <var>Position</var> is specified:</p><br />
<ul><br />
<li>Numeric value, expressed as either a constant or variable, indicates where in the buffer to begin reading; the count starts from 1. </li><br />
<br />
<li>Beyond the end of the data, then the image is unchanged; <var>ReadLen</var> is set to 0. </li><br />
<br />
<li>If the value is nonnumeric, less than one, or beyond the end of the data, then the statement fails with a nonzero <var>$Status</var> value.<br />
</li><br />
</ul><br />
<p><br />
If the <var>Position</var> option is not specified:</p><br />
<ul><br />
<li>Data is extracted from the buffer at the point where the last READ left off, or from the beginning of the buffer if this is the first read after any other statement (including WebSphere MQ statements). </li><br />
<br />
<li>Once the buffer has been emptied, subsequent <var>Read</var> <var>Image</var><br />
statements that do not specify <var>Position</var> set <var>ReadLen</var> to 0, and leave the target image unchanged.<br />
</li><br />
</ul><br />
<p><br />
After a <var>Read</var> <var>Image</var> statement is issued, use the value of <var>ReadLen</var> to determine how many bytes were actually copied. If no bytes were copied, <var>ReadLen</var>=0.</p><br />
<p><br />
The bytes in the image at offsets higher than the <var>ReadLen</var> value are unchanged.</p><br />
<p><br />
To determine the number of bytes remaining, use the following formula: </p><br />
<p class="code">bytes remaining = ($Buffer_Used - $Buffer_Position + 1)<br />
</p><br />
<br />
===Record positioning===<br />
<p><br />
If no position has been set prior to a <var>Read</var> <var>Next</var>, the position is assumed to be at the beginning of the file.</p><br />
<p><br />
The record is positioned in the image according to the following rules:</p><br />
<ul><br />
<li>If the record is longer than the image, the record is truncated.</li><br />
<br />
<li>If the record is smaller than the image, items beyond the end of the data are filled with the <var>Initial</var> value. An item that is partially filled by the input data is filled with the pad character for <var>String</var> and <var>EFormat</var> items and with binary zeros for <var>Binary</var>, <var>Packed</var>, <var>Zoned</var>, and <var>Float</var> items.</li><br />
<br />
<li>When there are arrays with depending variables, each such array is filled with the number of elements specified in the depending variable. The remainder of the array is initialized according to the <var>Initial</var> clauses. The remaining data is move to the image following the array.</li><br />
<br />
<li>If the length of the image is unknown because items or arrays have length or number of occurrences specified as <var>Unknown</var>, the block is filled with as much of the external record as fits in the remaining physical buffer space.<br />
</li><br />
</ul><br />
<br />
===Length of the external record===<br />
<p><br />
The length of the external record is stored in the variable <code><i>%imagename</i>:ReadLen</code>. </p><br />
<p><br />
Previous identifications of lengths of items defined as length <var>Unknown</var> or number of occurrences of arrays defined with <var>Occurs</var> <var>Unknown</var> are lost. The <var>Identify</var> statement must be executed again to establish length or number of occurrences. </p><br />
<br />
===Usage notes===<br />
The <var>Read Image</var> statement with the <var>Terminal</var> option can be useful to obtain user input, and in some cases is more advantageous than <var>[[$Read]]</var> because it is independent of the argument string on an <var>INCLUDE</var> command. For example, consider this procedure:<br />
<br />
<p class="code">PROCEDURE FOO<br />
begin<br />
%file is longstring<br />
%password is string len 255<br />
%file = %(system):arguments:unspace:toUpper<br />
%password = -<br />
$read('Password?', 'TRANSPARENT') ;* TRANSPARENT in case pwd ends, say, in a hyphen <br />
openC %file password %password<br />
end<br />
END PROC FOO </p><br />
<br />
If the above procedure is invoked as:<br />
<br />
<p class="code">INCLUDE FOO MYFILE</p><br />
<br />
Then the user is not prompted, and no input is taken from the user. Instead, the string <code>MYFILE</code>, which is the first token in the <var>INCLUDE</var> command argument string, is returned as the value of <var>$Read</var>. However, in the following approach, the user <b>is</b> prompted to input the password value:<br />
<br />
<p class="code">PROCEDURE FOO<br />
begin<br />
%file is longstring<br />
%password is string len 255<br />
%file = %(system):arguments:unspace:toUpper<br />
image str<br />
s is string len 255<br />
end image<br />
open terminal for input<br />
read image str from terminal prompt 'Password?'<br />
openC %file password %str:s<br />
end<br />
END PROC FOO<br />
</p><br />
<br />
==RELEASE POSITION statement==<br />
<p><br />
The <var>Release Position</var> statement terminates a browse operation established by a <var>Position</var> statement. </p><br />
<p><br />
Execution of a <var>Release Position</var> statement releases the VSAM string that maintains the current position in the file. The number of these strings is limited, and freeing the string as soon as the browse is finished allows other users to access the file.<br />
</p><br />
<p class="note"><b>Note:</b> A <var>Position</var> statement automatically is released by another <var>Position</var> statement, a <var>Read Image</var> statement with a <var>Key</var> clause, a <var>Close</var> statement, or the end of the request. </p><br />
<br />
===Syntax===<br />
<p><br />
The format of the <var>Release Position</var> statement is:</p><br />
<p class="syntax">Release Position {<span class="term">ext-filename</span> | <span class="term">%variable</span>}<br />
</p><br />
Where:<br />
<p><br />
<var class="term">ext-filename</var> is the name of the external file used in the <var>Position</var> statement. A %variable also can be used to supply the external file name. </p><br />
<br />
==WRITE IMAGE statement==<br />
<p><br />
The <var>Write Image</var> statement loads data into the Universal Buffer or writes an active image to a sequential file or to the terminal.</p><br />
<br />
===Syntax===<br />
<p><br />
The format of the <var>Write Image</var> statement is:</p><br />
<p class="syntax">Write [Image] <span class="term">imagename</span> On <br />
[Buffer [Position=<span class="term">%pvariable</span> | <span class="term">n</span>] <br />
[Maxlen={<span class="term">%lvariable</span> | <span class="term">n</span>}]]<br />
| {<span class="term">seq-filename</span> | Terminal | <span class="term">%variable</span>}<br />
</p><br />
Where:<br />
<ul><br />
<li><var class="term">imagename</var> specifies a message to place in the message buffer.</li><br />
<br />
<li>The <var>On</var> clause determines which use of the <var>Write Image</var> statement to employ: writing to a sequential file or the terminal or writing Large Object data to the Universal Buffer.</li><br />
<br />
<li><var>Buffer</var> (formerly, and still accepted as <code>Mq_Buffer</code>) specifies the Universal Buffer area.</li><br />
<br />
<li><var class="term">%pvariable</var> or <var class="term">n</var> specifies where in the buffer to start the placement.</li><br />
<br />
<li><var>Position</var> must be in the range 1-16,777,216. If not, the operation returns <code>$Status=10</code> and <code>$StatusD=20</code>. <br />
<p><br />
The starting position in the buffer is determined by:</p><br />
<ul><br />
<li><var>Position=<i>%pvariable</i></var>, if that was specified.</li><br />
<li><var>$Buffer_Position</var>, otherwise.</li><br />
</ul></li><br />
<br />
<li><var>Maxlen=<i>%lvariable</i></var> specifies the maximum number of bytes to copy from the image. The actual number copied is less than <var class="term">%lvariable</var>, if the size of the image is less. <br />
<p><br />
<var>Maxlen</var> must be in the range 1-32,767. If not, the operation returns $Status=10 and $StatusD=19. The amount of data to copy is determined by:</p><br />
<table><br />
<tr class="head"><br />
<th>If Maxlen=<i>%lvar</i> is </th><br />
<th>Then copy...</th><br />
</tr><br />
<br />
<tr><br />
<td>Not specified </td><br />
<td>Current length of the image.</td><br />
</tr><br />
<br />
<tr><br />
<td>Specified </td><br />
<td>Lesser of %lvariable and the current length of the image.</td><br />
</tr><br />
</table><br />
</li><br />
<br />
<li><var class="term">seq-filename</var> specifies the name of the sequential file to which the image should be written. A %variable also can be used to supply the name of the sequential file.</li><br />
<br />
<li><var>Terminal</var> specifies that the image should be written to the terminal. A %variable also can be used to supply the word <code>Terminal</code>. <br />
<p><br />
If you specify the <var>Position</var> option on the <var>Write Image</var> statement, data type translation is not performed for the terminal output. </p></li><br />
</ul><br />
<br />
===Usage===<br />
<p><br />
The <var>Write Image</var> statement is valid only if the file or terminal from which the record is read currently is open for OUTPUT, OUTPUT INPUT, or INOUT values. <br />
</p><br />
<p class="note"><b>Note:</b> When the <var>Write Image</var> statement is used for a depending array, unused occurrences of the array are eliminated from the output.</p><br />
<p><br />
If an <var>MqPut</var> or <var>MqPut1</var> statement is issued with the <var>Buffer</var> option, the buffer must contain a message, otherwise the operation fails with a nonzero <var>$Status</var> value.</p><br />
<p><br />
If the last WebSphere MQ operation was a successful put or get, then an <var>MqPut</var> or <var>MqPut1</var> statement with the BUFFER options puts the message most recently processed. In all other cases, at least one <var>Write Image <i>imagename</i> On Buffer</var> statement must have been issued.<br />
</p><br />
<p class="note"><b>Note:</b> Issue an <var>MqPut</var> statement with the <var>Buffer</var> option after a <var>Write Image <i>imagename</i> On Buffer</var> statement, otherwise <var>$Status</var> indicates there is no data in the buffer.</p><br />
<br />
===Image positioning===<br />
<p><br />
The data in the image is loaded into the buffer. Where the data is placed in the buffer depends on whether the <var>Position</var> option was specified. </p><br />
<p><br />
If <var>Position</var> was not specified:</p><br />
<ul><br />
<li>On the first such <var>Write Image</var> after any other SOUL statement or WebSphere MQ statement, the data is loaded starting in the first-byte position in the buffer.</li><br />
<br />
<li>On subsequent <var>Write Image</var> statements, data is loaded immediately following the data from the most recent WRITE. </li><br />
</ul><br />
<p><br />
If <var>Position</var> is specified as:</p><br />
<ul><br />
<li>Numeric value, expressed as either a constant or variable that indicates where in the buffer to begin to place the data, then the count starts from 1. </li><br />
<br />
<li>Nonnumeric, less than one, or larger than the current size of the buffer, then the statement fails with a nonzero <var>$Status</var> value. <br />
</li><br />
</ul><br />
<p><br />
The ending position in the buffer is determined by the starting position, plus the amount of data to copy.</p><br />
<p><br />
If the size of the user's BUFFER area is less than the ending position, the existing BUFFER area is expanded to a size equal to the ending position (data within the BUFFER area is preserved).</p><br />
<p><br />
The data is copied from the image to the BUFFER area:</p><br />
<ul><br />
<li><var>$Buffer_Position</var> is set to the byte after the last byte copied.</li><br />
<br />
<li><var>$Buffer_Used</var> is set according to the following rule: if data was written past the previous <var>$Buffer_Used</var> point, then <var>$Buffer_Used</var> is the point written to by the <var>Write Image</var>; otherwise, it is unchanged. </li><br />
</ul><br />
<br />
==Error handling==<br />
<p><br />
Error conditions encountered during the processing of image I/O statements &mdash; <var>Close</var>, <var>Open</var>, <var>Position</var>, <var>Read Image</var>, <var>Release Position</var>, and <var>Write Image</var> &mdash; generate <var class="product">Model&nbsp;204</var> error messages that are not displayed on the terminal. </p><br />
<p><br />
The request should check for errors after the execution of each I/O statement by using the <var>$Status</var> function. The text of the most recently issued error message then can be retrieved by using the <var>[[$Errmsg]]</var> function. Refer to <var>[[$ErrClr]]</var> and <var>[[$Status]]</var> for more information. </p><br />
<br />
===$Status return codes===<br />
<p><br />
The values that can be returned by <var>$Status</var> are listed below:</p><br />
<table><br />
<tr class="head"><br />
<th>Code </th><br />
<th>Description</th><br />
</tr><br />
<br />
<tr><br />
<td>0</td><br />
<td>The operation was successful. A return code of 0 also clears the message buffer. Therefore, the <var>$Errmsg</var> function, if called, returns a null string.</td><br />
</tr><br />
<br />
<tr><br />
<td>1</td><br />
<td>Either an end of file was detected by a <var>Read Next</var> statement or a matching key was not found for the criteria specified in a <var>Read Key</var> or <var>Position</var> statement. <br />
<p><br />
This code is only a warning; the request continues but cannot refer to the image before the next <var>Read Key</var> or <var>Position</var> statement.</p><br />
</td></tr><br />
<br />
<tr><br />
<td>2</td><br />
<td>A serious error has occurred such as an <var>Open</var> statement failure or an attempt to access an unopened file. The request continues, but the statement that generated the status code has not completed successfully. <br />
<p><br />
The failed statement cannot set an image active, resulting in the cancellation of the request if the image is referred to before being set active. </p><br />
<p><br />
The error that occurred can be retrieved by using <var>$Errmsg</var> to obtain the last counting or cancellation error message produced by <var class="product">Model&nbsp;204</var>. </p><br />
</td></tr><br />
</table><br />
<br />
===Detecting ABEND codes in SOUL===<br />
<p><br />
When <var class="product">Model&nbsp;204</var> intercepts an ABEND, the ABEND code and reason code are saved in the user's KOMM and can be accessed by the <var>$Status</var> and <var>[[$StatusD]]</var> $functions. The values of <var>$Status</var> and <var>$StatusD</var> are set as follows:</p><br />
<table><br />
<tr class="head"><br />
<th>$function</th><br />
<th>Value</th><br />
<th>Where</th><br />
</tr><br />
<br />
<tr><br />
<td>$Status</td><br />
<td>System ABEND code</td><br />
<td>System code is not zero</td><br />
</tr><br />
<br />
<tr><br />
<td>$Status</td><br />
<td>User ABEND code</td><br />
<td>User code is not zero</td><br />
</tr><br />
<br />
<tr><br />
<td>$Status</td><br />
<td>255 (X'FF')</td><br />
<td>ABEND code => X'F00'</td><br />
</tr><br />
<br />
<tr><br />
<td>$StatusD</td><br />
<td>Concatenated values of the $Status values:</td><br />
<td><var class="term">sss</var> is the system ABEND code<br />
<p><br />
<var class="term">uuu</var> is the user ABEND code</p><br />
<p><br />
<var class="term">rr</var> is the ABEND reason code</p><br />
</td></tr><br />
</table><br />
<p><br />
If the ABEND is related to a communications I/O error, the SNA Communications Server (formerly VTAM), LU 6.2, or TCP/IP error routines set <var>$Status</var> and <var>$StatusD</var> with the result of the Terminal I/O and so override the ABEND code information.</p><br />
<p class="note"><b>Note:</b> It is possible to get an ABEND code of all zeros. Some IBM system routines terminate with an ABEND U000 when they are invoked without APF authorization.</p><br />
<p><br />
The ABEND code is not available in the z/VSE environment.</p><br />
<br />
==Sample requests==<br />
<p><br />
This section presents three examples illustrating the use of images in a request.</p><br />
<br />
===Using the READ KEY facility===<br />
<p><br />
The following request illustrates the use of the READ KEY facility. The printed record is the one with a VSAM key equal to a user-specified value.</p><br />
<p class="code">BEGIN<br />
IMAGE EMP.REC<br />
CODE IS STRING LEN 8<br />
JOB.DESC IS STRING LEN 50<br />
NUM IS STRING LEN 7 DP *<br />
END IMAGE<br />
OPEN DATASET VSAMDS1 FOR INPUT<br />
IF $STATUS NE 0 THEN<br />
PRINT $Errmsg<br />
STOP<br />
END IF<br />
PROMPT: %KEY = $READ('ENTER KEY')<br />
IF %KEY = 'END' THEN<br />
JUMP TO EXIT<br />
END IF<br />
READ IMAGE EMP.REC FROM VSAMDS1 KEY EQ %KEY<br />
IF $STATUS EQ 1 THEN<br />
PRINT 'RECORD NOT FOUND'<br />
ELSEIF $STATUS EQ 2 THEN<br />
PRINT $Errmsg<br />
JUMP TO EXIT<br />
ELSE<br />
PRINT 'CODE = ' WITH %EMP.REC:CODE<br />
PRINT 'JOB DESCRIPTION = ' WITH -<br />
%EMP.REC:JOB.DESC<br />
PRINT 'NUMBER = ' WITH %EMP.REC:NUM<br />
END IF<br />
JUMP TO PROMPT<br />
EXIT: CLOSE DATASET VSAMDS1<br />
END<br />
</p><br />
<p><br />
The preceding request could be rewritten in the manner shown in Example 2 to print information from ten successive records of the VSAM file. </p><br />
<br />
===Using a Position statement===<br />
<p><br />
The starting position in this example is established in the file through the use of the <var>Position</var> statement and a user-specified key. </p><br />
<p class="code">BEGIN<br />
IMAGE EMP.REC<br />
CODE IS STRING LEN 8<br />
JOB.DESC IS STRING LEN 50<br />
NUM IS STRING LEN 7 DP *<br />
END IMAGE<br />
OPEN DATASET VSAMDS1 FOR INPUT <br />
IF $STATUS NE 0 THEN<br />
PRINT $Errmsg<br />
STOP<br />
END IF<br />
PROMPT: %KEY = $READ('ENTER KEY')<br />
IF %KEY = 'END' THEN<br />
JUMP TO EXIT<br />
END IF<br />
POSITION VSAMDS1 AT KEY GE %KEY<br />
FOR %CT FROM 1 TO 10<br />
READ IMAGE EMP.REC FROM VSAMDS1<br />
IF $STATUS EQ 1 THEN<br />
PRINT 'END OF FILE'<br />
JUMP TO PROMPT<br />
ELSEIF $STATUS EQ 2 THEN<br />
PRINT $Errmsg<br />
JUMP TO EXIT<br />
ELSE<br />
PRINT 'CODE = ' WITH %EMP.REC:CODE<br />
PRINT 'JOB DESCRIPTION = ' WITH -<br />
%EMP.REC:JOB.DESC<br />
PRINT 'NUMBER = ' WITH %EMP.REC:NUM<br />
END IF<br />
END FOR<br />
JUMP TO PROMPT<br />
EXIT: CLOSE DATASET VSAMDS1<br />
END<br />
</p><br />
<br />
===Example===<br />
<p><br />
The following request reads a sequential file that contains output from a previously issued <var>Print All Information</var> (<var>PAI</var>) statement. The foundset data is now in a data set. The request also handles non-<var>PAI</var> lines that might be found in the sequential file as separators; see the sample output that follows. The file being processed in this request contains <var>PAI</var> data for a <code>CENSUS</code> file.</p><br />
<p class="code">BEGIN<br />
IMAGE PAI<br />
LINE IS STRING LEN 255<br />
FIELDNAME IS STRING AT LINE LEN UNKNOWN<br />
SKIP 3 POSITIONS<br />
VALUE IS STRING LEN UNKNOWN<br />
END IMAGE<br />
<br />
OPEN DATASET OUTTAPE2 FOR INPUT<br />
IF $STATUS EQ 1 THEN<br />
JUMP TO DONE<br />
ELSEIF $STATUS EQ 2 THEN<br />
PRINT 'OPEN ERROR: ' WITH $Errmsg<br />
STOP<br />
END IF<br />
READ: READ PAI FROM OUTTAPE2<br />
IF $STATUS EQ 1 THEN<br />
JUMP TO DONE<br />
ELSEIF $STATUS EQ 2 THEN<br />
PRINT 'READ ERROR: ' WITH $Errmsg<br />
STOP<br />
END IF<br />
%A = $INDEX(%PAI:LINE,' = ')-1<br />
IF %A GE 0 THEN<br />
%B = %PAI:READLEN-%A-3<br />
IDENTIFY %PAI:FIELDNAME LEN %A<br />
IDENTIFY %PAI:VALUE LEN %B<br />
PRINT 'FIELD=''' WITH %PAI:FIELDNAME WITH '''' -<br />
WITH 'VALUE=''' AT 35 WITH %PAI:VALUE WITH ''''<br />
ELSE<br />
PRINT %PAI:LINE<br />
END IF<br />
JUMP TO READ<br />
DONE: PRINT 'END OF INPUT FILE'<br />
END<br />
</p><br />
<p><br />
The preceding request generates output in the format illustrated below. (This is the recommended format for file reorganization, as discussed in [[File reorganization and table compaction]].)</p><br />
<p class="code"><b></b>*<br />
FIELD='HOUSEHOLD ID' VALUE='53690'<br />
FIELD='AGE' VALUE='21'<br />
FIELD='OCCUPATION' VALUE='CLERK'<br />
FIELD='SEX' VALUE='FEMALE'<br />
FIELD='PLACE SIZE' VALUE='50000'<br />
FIELD='RELATION' VALUE='UNRELATED'<br />
FIELD='FATHERS BIRTHPLACE' VALUE='UNITED STATES'<br />
FIELD='MOTHERS BIRTHPLACE' VALUE='UNITED STATES'<br />
FIELD='BIRTHPLACE' VALUE='NORTH CENTRAL REGION'<br />
FIELD='MOTHER TONGUE' VALUE='ENGLISH'<br />
FIELD='SCHOOL' VALUE='4 YEARS HIGH SCHOOL'<br />
FIELD='ROOMS' VALUE='GROUP QUARTERS'<br />
FIELD='FAMILY SIZE' VALUE='NOT IN A FAMILY'<br />
<b></b>*<br />
FIELD='HOUSEHOLD ID' VALUE='42860'<br />
FIELD='AGE' VALUE='36'<br />
FIELD='OCCUPATION' VALUE='SALESMAN'<br />
FIELD='SEX' VALUE='MALE'<br />
FIELD='PLACE SIZE' VALUE='50000'<br />
FIELD='RELATION' VALUE='HEAD'<br />
FIELD='FATHERS BIRTHPLACE' VALUE='UNITED STATES'<br />
FIELD='MOTHERS BIRTHPLACE' VALUE='UNITED STATES'<br />
FIELD='BIRTHPLACE' VALUE='SOUTHERN REGION'<br />
FIELD='MOTHER TONGUE' VALUE='ENGLISH'<br />
FIELD='SCHOOL' VALUE='1-3 YEARS COLLEGE'<br />
FIELD='ROOMS' VALUE='4'<br />
FIELD='FAMILY SIZE' VALUE='4'<br />
END OF INPUT FILE<br />
</p><br />
<br />
</div> <!-- end of toc limit div --><br />
<br />
[[Category:SOUL]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Template:Skip_Position_statement_syntax&diff=115245Template:Skip Position statement syntax2018-05-18T16:02:20Z<p>Admin: Admin moved page Template:Skip statement syntax to Template:Skip Position statement syntax without leaving a redirect: two forms of Skip statement so must state what to skip</p>
<hr />
<div><p class="syntax">[<span class="term">itemname</span> IS] Skip <span class="term">n</span> Position[s] <br> [Initial {Null | <span class="term">character</span> | Blank}]<br />
</p></div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Statement_syntax&diff=115244Statement syntax2018-05-18T16:01:29Z<p>Admin: /* Skip Position */ point to correct template</p>
<hr />
<div>This page summarizes SOUL syntax and conventions, which are discussed in more detail throughout this wiki. The SOUL statements are listed in alphabetical order. Many of the section titles or syntax blocks contain links to the wiki page describing the statement or syntax phrase. A [[#Other syntax|later section]] provides other SOUL syntax information, including links to [[#tokens|information about the "tokens"]] of SOUL, such as names in SOUL.<br />
<p><br />
All SOUL statements can be used between a <var>[[BEGIN command|Begin]]</var> (or <var>[[MORE command|More]]</var>) command and an <var>[[End statement|End]]</var> statement. </p><br />
<p>External Call Facility (ECF) statements are listed under <var>[[#External|External]]</var>.</p><br />
<p><br />
Various other [[List of Model 204 commands|Model 204 commands]] also have effects on the results of a SOUL request. </p><br />
<p><br />
The following notations prefix some of the statements in the presentation of the SOUL syntax: </p><br />
<p class="code"><nowiki>*<br />
**<br />
+<br />
++<br />
C<br />
</nowiki></p><br />
<p><br />
See the [[#Notation conventions|notation conventions]] section for an explanation of these usages, as well as other general comments about understanding the syntax of SOUL. <br />
</p><br />
&nbsp; <!-- Separates intro from toc --><br />
<div id="User Language statements"></div> <!-- In case there are links --><br />
<div id="SOUL statements"></div> <div id="SOUL syntax"></div><br />
<!--To make above link targets go to toc:--><br />
<!--==SOUL statements in alphabetical order==--><br />
<br />
===[[Add statement|Add]]===<br />
<table class="noBorder"><br />
<tr><br />
<td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]]</td><br />
<td>{{Template:Add fieldname statement syntax}}</td></tr><br />
</table><br />
<br />
<table class="noBorder"><br />
<tr><td style="padding:0em">{{Template:Add lob-fieldname statement syntax}} </td></tr><br />
</table><br />
<br />
===ARRAY===<br />
<br />
<p class="syntaxUL">ARRAY <span class="squareb">[</span><span class="term">arrayname</span><span class="squareb">]</span> OCCURS <span class="squareb">{</span><span class="term">n</span> <span class="squareb">|</span> UNKNOWN<span class="squareb">}</span><br />
DEPENDING ON <span class="squareb">{</span><span class="term">itemname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
<span class="squareb">[</span>AFTER <span class="squareb">{</span><span class="term">itemname</span> <span class="squareb">|</span> <span class="term">arrayname</span><span class="squareb">}</span><br />
<span class="squareb">|</span> AT <span class="squareb">{</span><span class="term">position</span> <span class="squareb">|</span> <span class="term">itemname</span> <span class="squareb">|</span> <span class="term">imagename1</span> <span class="squareb">|</span> <span class="term">arrayname</span><span class="squareb">}</span><span class="squareb">]</span><br />
</p><br />
<br />
===[[Assert statement|Assert]]===<br />
<br />
{{Template:Assert statement syntax}}<br />
<br />
===[[Report_generation#AUDIT_statement|AUDIT]]===<br />
<br />
<p class="syntaxUL">AUDIT <span class="term">[[#Print specification syntax|print-specifications]]</span><br />
</p><br />
<br />
===[[Audit All Fieldgroup Information statement|Audit All Fieldgroup Information]] (AAFGI)===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td><br />
<td>{{Template:AAFGI statement syntax}} </td></tr><br />
</table><br />
<br />
===AUDIT ALL INFORMATION===<br />
<br />
<p class="syntaxUL"><span class="squareb">{</span>[[Basic SOUL statements and commands#AUDIT ALL INFORMATION statement|AUDIT ALL INFORMATION]] <span class="squareb">|</span> AAI<span class="squareb">}</span> <span class="squareb">[</span>CTOFIELDS<span class="squareb">]</span><br />
</p><br />
<br />
===BACKOUT===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(C)]] </td><br />
<td><p class="syntaxUL">[[Data recovery#Manual backout|BACKOUT]]</p> </td></tr><br />
</table><br />
<br />
===BYPASS===<br />
<br />
<p class="syntaxUL">BYPASS <span class="squareb">[</span>PENDING STATEMENT<span class="squareb">]</span> </p><br />
<br />
===CALL===<br />
<br />
<p class="syntaxUL">CALL <span class="squareb">{</span><span class="term">label</span> <span class="squareb">|</span> <span class="term">subname</span><br />
<span class="squareb">[</span>(<span class="squareb">[</span><span class="term">expression</span> <span class="squareb">|</span> <span class="term">%variable</span> <span class="squareb">|</span> <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">]</span> <span class="squareb">[</span>,...<span class="squareb">]</span>)<span class="squareb">]</span><span class="squareb">}</span><br />
</p><br />
<br />
===[[Data maintenance#Change statement|Change]]===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td><br />
<td>{{Template:Change fieldname statement syntax (basic)}} </td></tr><br />
</table><br />
<br />
<table class="noBorder"><br />
<tr><br />
<td style="padding:0em">{{Template:Change lob-fieldname statement syntax}} </td></tr><br />
</table><br />
<br />
===[[Global_features#Using_the_CLEAR_statement|CLEAR]]===<br />
<br />
{{Template:Clear statement syntax}}<br />
<br />
===CLEAR LIST===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*)]] </td><br />
<td><p class="syntaxUL">[[Lists#Clearing a list|CLEAR LIST]] <span class="term">listname</span> </p></td></tr><br />
</table><br />
<br />
===CLEAR ON===<br />
<br />
{{Template:Clear On statement syntax}}<br />
<br />
===CLEAR TAG===<br />
<br />
<p class="syntaxUL">CLEAR TAG <span class="squareb">{</span><span class="term">screenname</span> <span class="squareb">|</span> <span class="term">%screenname</span>:<span class="term">inputname</span><span class="squareb">}</span><br />
</p><br />
<br />
===CLOSE===<br />
<br />
<p class="syntaxUL">CLOSE<br />
<span class="squareb">{</span>DATASET <span class="squareb">{</span><span class="term">ext-filename</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
<span class="squareb">|</span> <span class="squareb">[</span>EXTERNAL<span class="squareb">]</span> <span class="squareb">{</span><span class="term">ext-filename</span> <span class="squareb">|</span> TERMINAL <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><span class="squareb">}</span><br />
</p><br />
<br />
===CLOSE PROCESS===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+C)]] </td><br />
<td><p class="syntaxUL">CLOSE PROCESS <BR> <span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> <span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> <BR> <span class="squareb">[</span>SYNCLEVEL <span class="squareb">|</span> FLUSH <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">]</span> </p></td></tr><br />
</table><br />
<br />
<p class="syntaxUL">CLOSE PROCESS<br />
<span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> <span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
<span class="squareb">[</span>SYNCLEVEL <span class="squareb">|</span> CONFIRM <span class="squareb">|</span> FLUSH <span class="squareb">|</span> ERROR <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">]</span><br />
</p><br />
<br />
===[[Commit statement|Commit]]===<br />
<br />
{{Template:Commit statement syntax}}<br />
<br />
===[[Horizon SOUL interface#Confirm statement|Confirm]]===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td><br />
<td>{{Template:Confirm statement syntax}} </td></tr><br />
</table><br />
<br />
===[[Horizon SOUL interface#Confirmed statement|Confirmed]]===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td><br />
<td>{{Template:Confirmed statement syntax}} </td></tr><br />
</table><br />
<br />
===CONTINUE===<br />
<br />
<p class="syntaxUL">CONTINUE</p><br />
<br />
===COUNT OCCURRENCES OF===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td><br />
<td><p class="syntaxUL">COUNT OCCURRENCES OF <span class="term">fieldname</span></p></td></tr><br />
</table><br />
<br />
===COUNT RECORDS===<br />
<br />
<p class="syntaxUL">COUNT RECORDS <span class="squareb">{</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">}</span></p><br />
<br />
===<b id="declare"></b>DECLARE===<br />
<br />
<p class="syntaxUL"><span class="squareb">[</span>DECLARE<span class="squareb">]</span> <span class="term">declaration</span><br />
</p><br />
<br />
<p><br />
where <var class="term">declaration</var> is one of the following: </p><br />
<br />
<div style="margin-left: 20px; background-color: #fBfBfB;"><br />
<ul style="font-family: Consolas,monospace"><br />
<li>LABEL <i>labelname</i> <span class="squareb">[</span>GLOBAL <span class="squareb">|</span> COMMON<span class="squareb">]</span><br />
<br />
<li>[[Lists#DECLARE LIST syntax|LIST]] listname <span class="squareb">[</span>IN <span class="squareb">[</span>FILE <span class="squareb">|</span> <span class="squareb">[</span>PERM <span class="squareb">|</span> TEMP<span class="squareb">]</span> GROUP<span class="squareb">]</span><span class="squareb">]</span> <i>name</i><span class="squareb">]</span> <span class="squareb">[</span>GLOBAL <span class="squareb">|</span> COMMON<span class="squareb">]</span><br />
<br />
<li>IMAGE <i>imagename</i><span class="squareb">[</span>AT <span class="squareb">{</span><i>itemname</i> <span class="squareb">|</span> <i>imagename1</i> <span class="squareb">|</span> <i>arrayname</i><span class="squareb">}</span> <br><br />
<span class="squareb">|</span> GLOBAL <span class="squareb">[</span>PERMANENT <span class="squareb">|</span> TEMPORARY<span class="squareb">]</span> <br><br />
<span class="squareb">|</span> <span class="squareb">[</span>PERMANENT <span class="squareb">|</span> TEMPORARY<span class="squareb">]</span> GLOBAL <span class="squareb">|</span> COMMON<span class="squareb">]</span><br />
<br />
<li>MENU <i>menuname</i> <span class="squareb">[</span>GLOBAL <span class="squareb">[</span>PERMANENT <span class="squareb">|</span> TEMPORARY<span class="squareb">]</span> <br><br />
<span class="squareb">|</span> <span class="squareb">[</span>PERMANENT <span class="squareb">|</span> TEMPORARY<span class="squareb">]</span> GLOBAL <span class="squareb">|</span> COMMON<span class="squareb">]</span><br />
<br />
<li>SCREEN <i>screenname</i> <span class="squareb">[</span>GLOBAL <span class="squareb">[</span>PERMANENT <span class="squareb">|</span> TEMPORARY<span class="squareb">]</span> <br><br />
<span class="squareb">|</span> <span class="squareb">[</span>PERMANENT <span class="squareb">|</span> TEMPORARY<span class="squareb">]</span> GLOBAL <span class="squareb">|</span> COMMON<span class="squareb">]</span><br />
<br />
<li><i>%variable</i> <span class="squareb">[</span>IS<span class="squareb">]</span> <span class="squareb">{</span>FIXED <span class="squareb">[</span>DP <i>n</i><span class="squareb">]</span> <span class="squareb">|</span> FLOAT<span class="squareb">}</span> <span class="squareb">[</span>ARRAY (<i>d1</i> <span class="squareb">[</span>,<i>d2</i> <span class="squareb">[</span>,<i>d3</i><span class="squareb">]</span><span class="squareb">]</span>)<span class="squareb">]</span> <br><br />
<span class="squareb">[</span>[[Initial clause in %variable declaration|Initial]](<i>numeric-expression</i>)<span class="squareb">]</span> <span class="squareb">[</span>STATIC<span class="squareb">]</span> <span class="squareb">[</span>COMMON<span class="squareb">]</span><br />
<br />
<li><i>%variable</i> <span class="squareb">[</span>IS<span class="squareb">]</span> STRING <span class="squareb">[</span>LEN <i>n</i><span class="squareb">]</span> <span class="squareb">[</span>DP <span class="squareb">{</span><i>n</i> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span>ARRAY (<i>d1</i> <span class="squareb">[</span>,<i>d2</i><span class="squareb">[</span>,<i>d3</i><span class="squareb">]</span><span class="squareb">]</span>)<span class="squareb">]</span> <br><br />
<span class="squareb">[</span>NO FIELD SAVE<span class="squareb">]</span> <span class="squareb">[</span>COMMON<span class="squareb">]</span> <br><br />
<span class="squareb">[</span>[[Initial clause in %variable declaration|Initial]]('<i>EBCDIC-string</i>' <span class="squareb">|</span> <i>expression</i>)<span class="squareb">]</span> <span class="squareb">[</span>STATIC<span class="squareb">]</span><br />
<br />
<li>SUBROUTINE <i>subname</i> <span class="squareb">[</span>(<i>type</i> <span class="squareb">[</span>INPUT <span class="squareb">|</span> OUTPUT <span class="squareb">|</span> INPUT OUTPUT<span class="squareb">]</span> <span class="squareb">[</span>,...<span class="squareb">]</span>)<span class="squareb">]</span><br />
</ul><br />
</div> <!-- declare indent/background --> <br />
<br />
<div style="margin-left: 20px;><br />
<p><br />
and where <var class="term">type</var> is one of the following:</p><br />
</div><br />
<br />
<div style="margin-left: 40px; background-color: #fBfBfB;"><br />
<ul><br />
<li>Scalar %variable of the following format:<br />
<ul style="font-family: Consolas,monospace"><br />
<li><span class="squareb">{</span>STRING <span class="squareb">[</span>LEN<span class="squareb">]</span> <i>n</i> <span class="squareb">[</span>DP <span class="squareb">{</span><i>n</i> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">|</span> <span class="squareb">[</span>FIXED <span class="squareb">[</span>DP <i>n</i><span class="squareb">]</span> <span class="squareb">|</span> FLOAT<span class="squareb">]</span><span class="squareb">}</span> </li></ul><br />
</li><br />
<br />
<li>Array %variable of the following format:<br />
<ul style="font-family: Consolas,monospace"><br />
<li><span class="squareb">{</span>STRING <span class="squareb">[</span>LEN <i>n</i><span class="squareb">]</span> <span class="squareb">[</span>DP <span class="squareb">[</span><i>n</i> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span>ARRAY (* <span class="squareb">[</span>,*<span class="squareb">[</span>,*<span class="squareb">]</span><span class="squareb">]</span>) <span class="squareb">[</span>NO FIELD SAVE<span class="squareb">]</span><span class="squareb">]</span> <br><br />
<span class="squareb">|</span> <span class="squareb">[</span>FIXED <span class="squareb">[</span>DP <i>n</i><span class="squareb">]</span> <span class="squareb">|</span> FLOAT<span class="squareb">]</span> <span class="squareb">[</span>ARRAY (* <span class="squareb">[</span>,*<span class="squareb">[</span>,*<span class="squareb">]</span><span class="squareb">]</span>)<span class="squareb">]</span><span class="squareb">}</span> </li></ul><br />
</li><br />
<br />
<li>A list of records of the following format:<br />
<ul style="font-family: Consolas,monospace"><br />
<li><span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="squareb">[</span>IN <span class="squareb">{</span>FILE <span class="squareb">|</span> <span class="squareb">[</span>PERM <span class="squareb">|</span> TEMP<span class="squareb">]</span> GROUP<span class="squareb">}</span> <i>name</i><span class="squareb">]</span> </li></ul><br />
</li><br />
</ul><br />
<br />
</div> <!-- type indentation/background --><br />
<br />
====See also====<br />
<br />
<ul><br />
<li>[[Using variables and values in computation]]<br />
</ul><br />
<br />
===DEFAULT CURSOR===<br />
<br />
<p class="syntaxUL">DEFAULT CURSOR <span class="squareb">[</span>READ <span class="squareb">|</span> REREAD <span class="squareb">|</span> PRINT<span class="squareb">]</span><br />
<span class="squareb">{</span>ITEMID <span class="term">n</span> <span class="squareb">|</span> <span class="term">itemname</span> <span class="squareb">|</span> ROW <span class="term">n</span> COLUMN <span class="term">m</span><span class="squareb">}</span><br />
</p><br />
<br />
===DEFAULT===<br />
<br />
<p class="syntaxUL">DEFAULT <span class="squareb">{</span>TITLE<br />
<span class="squareb">|</span> PROMPT<br />
<span class="squareb">|</span> INPUT <span class="squareb">[</span>DEBLANK <span class="squareb">|</span> NODEBLANK<span class="squareb">]</span> <span class="squareb">[</span>PAD WITH '<span class="term">c</span>'<span class="squareb">]</span> <span class="squareb">[</span>LEN <span class="term">m</span> <span class="squareb">[</span>DP <span class="squareb">[</span><span class="term">k</span> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span><span class="squareb">]</span> <span class="squareb">[</span>UPCASE <span class="squareb">|</span> NOCASE<span class="squareb">]</span><br />
<span class="squareb">|</span> <span class="squareb">[</span>TAG <span class="squareb">[</span><span class="term">attributes</span><span class="squareb">]</span> <span class="squareb">[</span>WITH '<span class="term">c</span>'<span class="squareb">]</span><span class="squareb">}</span><br />
<span class="squareb">[</span><span class="squareb">[</span>READ<span class="squareb">]</span> <span class="term">attributes</span><span class="squareb">]</span> <span class="squareb">[</span>REREAD <span class="term">attributes</span><span class="squareb">]</span> <span class="squareb">[</span>PRINT <span class="term">attributes</span><span class="squareb">]</span><br />
<br />
DEFAULT SKIP <span class="term">n</span> POSITIONS<span class="squareb">[</span>S<span class="squareb">]</span><br />
<span class="squareb">[</span>INITIAL <span class="squareb">{</span>NULL <span class="squareb">|</span> <span class="term">character</span> <span class="squareb">|</span> BLANK<span class="squareb">}</span><span class="squareb">]</span><br />
<br />
DEFAULT <span class="squareb">[</span>TYPE<span class="squareb">]</span><br />
<span class="squareb">{</span>STRING <span class="squareb">|</span> BINARY <span class="squareb">|</span> PACKED <span class="squareb">|</span> ZONED <span class="squareb">|</span> FLOAT <span class="squareb">|</span> EFORMAT<span class="squareb">}</span><br />
<span class="squareb">{</span>LEN <span class="squareb">{</span><span class="term">n</span> <span class="squareb">|</span> UNKNOWN<span class="squareb">}</span> <span class="squareb">|</span> BITS <span class="term">n</span> <span class="squareb">|</span> DIGITS <span class="term">n</span><span class="squareb">}</span><br />
<span class="squareb">[</span>DP <span class="squareb">{</span><span class="term">k</span> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span>BP <span class="term">n</span><span class="squareb">]</span><br />
<span class="squareb">[</span>SIGNED <span class="squareb">|</span> UNSIGNED<span class="squareb">]</span> <span class="squareb">[</span>PAD <span class="squareb">{</span>BLANK <span class="squareb">|</span> <span class="term">character</span> <span class="squareb">|</span> NULL<span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">[</span>STRIP <span class="squareb">|</span> NOSTRIP<span class="squareb">]</span> <span class="squareb">[</span>JUSTIFY <span class="squareb">{</span>LEFT <span class="squareb">|</span> RIGHT<span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">[</span>INITIAL <span class="squareb">{</span>BLANK <span class="squareb">|</span> ZERO <span class="squareb">|</span> NULL <span class="squareb">|</span> <span class="term">literal</span><span class="squareb">}</span><span class="squareb">]</span><br />
</p><br />
<br />
===DELETE===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td><br />
<td><p class="syntaxUL">[[Data maintenance#DELETE statement|DELETE]] <span class="term">fieldname</span> <span class="squareb">[</span>(<span class="term">[[Processing_multiply_occurring_fields_and_field_groups#DELETE_statement_rules|subscript]]</span>)<span class="squareb">]</span> <span class="squareb">[</span><b></b>= <span class="term">value</span> <span class="squareb">|</span> (<span class="term">expression</span>)<span class="squareb">]</span><br />
</p></td></tr><br />
</table><br />
<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td><br />
<td><p class="syntaxUL">[[Data maintenance#Deleting a field group|DELETE FIELDGROUP]] <span class="squareb">[</span><span class="term">fieldgroupname</span><span class="squareb">]</span> <span class="squareb">[</span>(<span class="term">[[Processing_multiply_occurring_fields_and_field_groups#DELETE_statement_rules|subscript]]</span>)<span class="squareb">]</span> <span class="squareb">[</span><b></b>= <span class="term">value</span> <span class="squareb">|</span> (<span class="term">expression</span>)<span class="squareb">]</span><br />
</p></td></tr><br />
</table><br />
<br />
===DELETE EACH===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td><br />
<td><p class="syntaxUL">DELETE EACH <span class="term">fieldname</span></p> </td></tr><br />
</table><br />
<br />
===[[Data maintenance#DELETE RECORD statement|DELETE RECORD]]===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td><br />
<td><p class="syntaxUL">DELETE RECORD </p> </td></tr><br />
</table><br />
<br />
===DELETE RECORDS===<br />
<br />
<p class="syntaxUL">DELETE <span class="squareb">[</span>ALL<span class="squareb">]</span> RECORDS <span class="squareb">{</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">}</span><br />
</p><br />
<br />
===END BLOCK===<br />
<br />
<p class="syntaxUL">END BLOCK <span class="term">label</span> </p><br />
<br />
===End===<br />
<br />
<p class="syntaxUL">END <span class="squareb">{</span>FIND <span class="squareb">|</span> IF <span class="squareb">|</span> FOR <span class="squareb">|</span> ON <span class="squareb">|</span> REPEAT <span class="squareb">|</span> STORE <span class="squareb">|</span> SUBROUTINE<span class="squareb">}</span> [<span class="term">label</span><span class="squareb">]</span><br />
<br />
END <span class="squareb">{</span>ARRAY <span class="squareb">|</span> IMAGE <span class="squareb">|</span> MENU <span class="squareb">|</span> SCREEN<span class="squareb">}</span><br />
<br />
[[End statement|End]] <span class="squareb">[</span>MORE <span class="squareb">|</span> NORUN <span class="squareb">|</span> USE<span class="squareb">]</span>...</p><br />
<br />
===END UPDATE===<br />
<br />
<p class="syntaxUL">END UPDATE</p><br />
<br />
===[[External statement|External]]===<br />
<br />
{{Template:External statement syntax}}<br />
<br />
===FILE RECORDS===<br />
<br />
<p class="syntaxUL">FILE RECORDS <span class="squareb">{</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">}</span><br />
UNDER <span class="term">fieldname</span> = <span class="squareb">{</span><span class="term">value</span> <span class="squareb">|</span> (<span class="term">expression</span>)<span class="squareb">}</span><br />
</p><br />
<br />
===[[Find Records statement|Find Records]]===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*)]] </td><br />
<td><p class="syntaxUL"><span class="squareb">{</span>FIND <span class="squareb">[</span><span class="squareb">[</span>ALL<span class="squareb">]</span> RECORDS<span class="squareb">]</span> <span class="squareb">|</span> FD <span class="squareb">}</span> <br> <span class="squareb">[</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">]</span> <br> <span class="squareb">[</span>FOR WHICH <span class="squareb">|</span> WITH<span class="squareb">]</span> <span class="term">[[#Retrieval condition syntax|retrieval-conditions]]</span></p></td></tr><br />
</table><br />
<br />
===[[Find And Reserve statement|Find And Reserve]]===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*)]] </td><br />
<td><p class="syntaxUL"><span class="squareb">{</span>FIND AND RESERVE <span class="squareb">[</span><span class="squareb">[</span>ALL<span class="squareb">]</span> RECORDS<span class="squareb">]</span> <span class="squareb">|</span> FDR<span class="squareb">}</span> <br> <span class="squareb">[</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">]</span> <br> <span class="squareb">[</span>FOR WHICH <span class="squareb">|</span> WITH<span class="squareb">]</span> <span class="term">[[#Retrieval condition syntax|retrieval-conditions]]</span> </p></td></tr><br />
</table><br />
<br />
===[[Value loops#Find All Values statement|Find Values Of (FDV)]]===<br />
<table class="noBorder"><br />
<tr><br />
<td style="padding:0em">{{Template: Find Values Of statement syntax}} </td></tr><br />
</table><br />
<br />
===FIND AND PRINT COUNT===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*)]] </td><br />
<td><p class="syntaxUL"><span class="squareb">{</span>Find And Print Count <span class="squareb">|</span> FPC<span class="squareb">}</span> <br> <span class="squareb">[</span><span class="term">[[#Retrieval condition syntax|retrieval-conditions]]</span><span class="squareb">]</span><br />
</p></td></tr><br />
</table><br />
<br />
===[[Find Records statement|Find Without Locks]]===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*)]] </td><br />
<td><p class="syntaxUL"><span class="squareb">{</span>Find Without Locks <span class="squareb">[</span><span class="squareb">[</span>ALL<span class="squareb">]</span> Records<span class="squareb">]</span> <span class="squareb">|</span> FDWOL<span class="squareb">}</span><br> <span class="squareb">[</span>In <span class="term">label</span> <span class="squareb">|</span> On <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">]</span><br />
<span class="squareb">[</span>For Which <span class="squareb">|</span> With<span class="squareb">]</span> <span class="term">[[#Retrieval condition syntax|retrieval-conditions]]</span></p></td></tr><br />
</table><br />
<br />
===FLUSH PROCESS===<br />
<br />
<p class="syntaxUL">FLUSH PROCESS <span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> <span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span></p><br />
<br />
===FOR EACH OCCURRENCE===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td><br />
<td><p class="syntaxUL">FOR <span class="squareb">{</span>EACH <span class="squareb">|</span> <span class="term">k</span><span class="squareb">}</span> <span class="squareb">{</span>OCCURRENCE <span class="squareb">|</span> OCCURRENCES<span class="squareb">}</span> <span class="term">OF fieldname</span> </p></td></tr><br />
</table><br />
<br />
===<b id="FOR EACH RECORD"></b>[[Record loops#For Each Record statement|For Each Record]]===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*)]] </td><br />
<td>{{Template:For Each Record statement syntax}}</td></tr><br />
</table><br />
<p class="note"><b>Note:</b> For <var class="term">retrieval-conditions</var>, see [[#Retrieval condition syntax|Retrieval condition syntax]], below. </p><br />
<br />
===FOR EACH VALUE OF===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*)]] </td><br />
<td><p class="syntaxUL">FOR <span class="squareb">{</span>EACH <span class="squareb">|</span> <span class="term">k</span><span class="squareb">}</span> <span class="squareb">{</span>VALUE <span class="squareb">|</span> VALUES<span class="squareb">}</span> <span class="term">OF fieldname</span> <br> <span class="squareb">[</span>FROM <span class="squareb">{</span><span class="term">value1</span> <span class="squareb">|</span> (<span class="term">expression1</span>)<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span>TO <span class="squareb">{</span><span class="term">value2</span> <span class="squareb">|</span> (<span class="term">expression2</span>)<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span><span class="squareb">[</span>NOT<span class="squareb">]</span> LIKE <span class="term">pattern</span><span class="squareb">]</span> <br> <span class="squareb">[</span>IN <span class="squareb">[</span>ASCENDING <span class="squareb">|</span> DESCENDING<span class="squareb">]</span> <span class="squareb">[</span>CHARACTER <span class="squareb">|</span> NUMERICAL<span class="squareb">]</span> <span class="squareb">[</span>RIGHT-ADJUSTED<span class="squareb">]</span> ORDER<span class="squareb">]</span><br />
</p></td></tr><br />
</table><br />
<br />
===FOR EACH VALUE IN===<br />
<br />
<p class="syntaxUL">FOR <span class="squareb">{</span>EACH <span class="squareb">|</span> <span class="term">k</span><span class="squareb">}</span> <span class="squareb">{</span>VALUE <span class="squareb">|</span> VALUES<span class="squareb">}</span> IN <span class="term">label</span> </p><br />
<br />
===FOR RECORD NUMBER===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*)]] </td><br />
<td><p class="syntaxUL">FOR RECORD NUMBER <span class="squareb">{</span><span class="term">value</span> <span class="squareb">|</span> (<span class="term">expression</span>)<span class="squareb">}</span><br />
</p></td></tr><br />
</table><br />
<br />
===FOR RECORD NUMBER IN===<br />
<br />
<p class="syntaxUL">FOR RECORD NUMBER <span class="squareb">{</span><span class="term">value</span> <span class="squareb">|</span> IN <span class="term">label</span><span class="squareb">}</span> <span class="squareb">[</span>OPTIMIZING FNV<span class="squareb">]</span><br />
</p><br />
<br />
===[[For %i statement|For %var From %exp1 To %exp2 By %exp3]]===<br />
<table class="noBorder"><br />
<tr><br />
<td style="padding:0em">{{Template:For %i statement syntax}} </td></tr><br />
</table><br />
<br />
<p class="note"><b>Note:</b> The <var>By</var> clause, when omitted, defaults to a value of 1. </p><br />
<br />
===[[Images#Identify statement|Identify]]===<br />
<br />
<table class="noBorder" display="table-column"><br />
<tr><td>{{Template:Identify statement syntax}} </td></tr><br />
</table><br />
<br />
===<b id="IF...THEN...ELSE"></b>[[If statement|If]]...Then...ElseIf...Else===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(C)]] </td><br />
<td><p class="syntaxUL">IF <span class="term">expression</span> THEN <span class="term">statements</span> <BR> <span class="squareb">[</span>ELSE <span class="term">statements</span> <span class="squareb">|</span> ELSEIF <span class="term">expression</span> THEN <span class="term">statements</span><span class="squareb">]</span><br />
</p></td></tr><br />
</table><br />
<br />
===[[Image statement|Image]]===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">{{Template:Image statement syntax}} </td></tr><br />
</table><br />
<br />
===INCLUDE===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*)]] </td><br />
<td><p class="syntaxUL">INCLUDE <span class="term">procedurename</span> </p></td></tr><br />
</table><br />
<br />
===INPUT===<br />
<br />
<p class="syntaxUL">INPUT <span class="term">inputname</span> <span class="squareb">[</span>AT <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">n</span><span class="squareb">]</span><br />
<span class="squareb">[</span>TO <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">m</span> <span class="squareb">|</span> <span class="squareb">[</span>LEN <span class="term">m</span><span class="squareb">]</span> DP <span class="squareb">{</span><span class="term">k</span> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span><span class="squareb">]</span><br />
<span class="squareb">[</span>UPCASE <span class="squareb">|</span> NOCASE<span class="squareb">]</span> <span class="squareb">[</span>DEFAULT '<span class="term">value</span>'<span class="squareb">]</span><br />
<span class="squareb">[</span>DEBLANK <span class="squareb">|</span> NODEBLANK<span class="squareb">]</span> <span class="squareb">[</span>PAD WITH '<span class="term">c</span>'<span class="squareb">]</span><br />
<span class="squareb">[</span>REQUIRED <span class="squareb">|</span> ALPHA <span class="squareb">|</span> ALPHANUM <span class="squareb">|</span> MUSTFILL<br />
<span class="squareb">|</span> ONEOF <span class="term">literal</span> <span class="squareb">[</span>, <span class="term">literal</span><span class="squareb">]</span>...<br />
<span class="squareb">|</span> <span class="squareb">[</span>NUMERIC<span class="squareb">]</span> <span class="squareb">[</span>RANGE <span class="term">lo</span> <span class="squareb">[</span>TO<span class="squareb">]</span> <span class="term">hi</span> <span class="squareb">[</span>AND <span class="term">lo</span> <span class="squareb">[</span>TO<span class="squareb">]</span> <span class="term">hi</span><span class="squareb">]</span> ...<span class="squareb">]</span><br />
<span class="squareb">|</span> VERIFY '<span class="term">characters</span>'<span class="squareb">]</span>...<br />
<span class="squareb">[</span><span class="squareb">[</span>READ<span class="squareb">]</span> <span class="term">attributes</span><span class="squareb">]</span> <span class="squareb">[</span>REREAD <span class="term">attributes</span><span class="squareb">]</span> <span class="squareb">[</span>PRINT <span class="term">attributes</span><span class="squareb">]</span><br />
<span class="squareb">[</span>TAG <span class="squareb">[</span><span class="term">attributes</span><span class="squareb">]</span> <span class="squareb">[</span>WITH '<span class="term">c</span>'<span class="squareb">]</span><span class="squareb">]</span> <span class="squareb">[</span>ITEMID <span class="term">n</span><span class="squareb">]</span><br />
</p><br />
<br />
===INSERT===<br />
<br />
<p class="syntaxUL">INSERT <span class="term">fieldname</span> <span class="squareb">[</span>(<span class="term">subscript</span>)<span class="squareb">]</span> = <span class="squareb">{</span><span class="term">value</span> <span class="squareb">|</span> (<span class="term">expression</span>)<span class="squareb">}</span><br />
</p><br />
<br />
===[[Horizon SOUL interface#Invite statement|Invite]]===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td><br />
<td>{{Template:Invite statement syntax}} </td></tr><br />
</table><br />
<br />
===IS===<br />
<br />
<p class="syntaxUL"><span class="term">itemname</span> IS <span class="squareb">[</span>TYPE<span class="squareb">]</span><br />
<span class="squareb">{</span>STRING <span class="squareb">|</span> BINARY <span class="squareb">|</span> PACKED <span class="squareb">|</span> ZONED <span class="squareb">|</span> FLOAT <span class="squareb">|</span> EFORMAT<span class="squareb">}</span><br />
<span class="squareb">{</span>LEN <span class="squareb">{</span><span class="term">n</span> <span class="squareb">|</span> UNKNOWN<span class="squareb">}</span> <span class="squareb">|</span> BITS <span class="term">n</span> <span class="squareb">|</span> DIGITS <span class="term">n</span><br />
<span class="squareb">|</span> TO <span class="term">position</span><span class="squareb">}</span><br />
<span class="squareb">[</span>DP <span class="squareb">{</span><span class="term">k</span> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span>BP <span class="term">n</span><span class="squareb">]</span> <span class="squareb">[</span>SIGNED <span class="squareb">|</span> UNSIGNED<span class="squareb">]</span><br />
<span class="squareb">[</span>PAD <span class="squareb">{</span>BLANK <span class="squareb">|</span> <span class="term">character</span> <span class="squareb">|</span> NULL<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span>STRIP <span class="squareb">|</span> NOSTRIP<span class="squareb">]</span><br />
<span class="squareb">[</span>ALIGN<span class="squareb">]</span><br />
<span class="squareb">[</span>JUSTIFY <span class="squareb">{</span>LEFT <span class="squareb">|</span> RIGHT<span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">[</span>INITIAL <span class="squareb">{</span>BLANK <span class="squareb">|</span> ZERO <span class="squareb">|</span> NULL <span class="squareb">|</span> <span class="term">value</span><span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">[</span>AFTER <span class="squareb">{</span><span class="term">itemname</span> <span class="squareb">|</span> <span class="term">arrayname</span><span class="squareb">}</span><br />
<span class="squareb">|</span> AT <span class="squareb">{</span><span class="term">position</span> <span class="squareb">|</span> <span class="term">itemname</span> <span class="squareb">|</span> <span class="term">imagename1</span> <span class="squareb">|</span> <span class="term">arrayname</span><span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">[</span>OCCURS <span class="squareb">{</span><span class="term">n</span> <span class="squareb">[</span>DEPENDING ON <span class="squareb">{</span><span class="term">itemname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">|</span> UNKNOWN<span class="squareb">}</span><span class="squareb">]</span><br />
</p><br />
<br />
===JUMP TO===<br />
<br />
<p class="syntaxUL">JUMP TO <span class="term">label</span><br />
<br />
JUMP TO (<span class="term">label1</span> <span class="squareb">[</span>, <span class="term">label2</span><span class="squareb">]</span> ...) <span class="term">expression</span></p><br />
<br />
===[[Flow of control in User Language#LOOP END statement|Loop End]]===<br />
<br />
<p class="syntaxUL">Loop End </p><br />
<br />
===[[Loop Next statement|Loop Next]]===<br />
<br />
<p class="syntaxUL">Loop Next</p><br />
<br />
===MAX PFKEY===<br />
<br />
<p class="syntaxUL">MAX PFKEY <span class="term">n</span> </p><br />
<br />
===<b id="MENU"></b>[[Menu statement or block|Menu]]===<br />
<table class="noBorder"><br />
<tr><br />
<td style="padding:0em">{{Template: Menu statement syntax}} </td></tr><br />
</table><br />
<br />
===MODIFY===<br />
<br />
<p class="syntaxUL">MODIFY <span class="squareb">{</span><span class="term">%menuname</span>:<span class="term">itemname</span> <span class="squareb">|</span> <span class="term">%screenname</span>:<span class="term">itemname</span><span class="squareb">}</span><br />
<span class="squareb">[</span>TO<span class="squareb">]</span> <span class="term">attributes</span> <span class="squareb">[</span><span class="squareb">[</span>FOR<span class="squareb">]</span> <span class="squareb">{</span>ALL <span class="squareb">|</span> READ <span class="squareb">|</span> REREAD <span class="squareb">|</span> TAB<br />
<span class="squareb">|</span> PRINT<span class="squareb">}</span><span class="squareb">]</span><br />
</p><br />
<br />
===MODIFY BUFFER===<br />
<br />
<p class="syntaxUL">MODIFY BUFFER <span class="squareb">[</span>SIZE=<span class="term">n</span><br />
<span class="squareb">|</span> <span class="term">%variable</span> <span class="squareb">[</span>PRESERVE <span class="squareb">|</span> NOPRESERVE<span class="squareb">]</span><span class="squareb">]</span><br />
<span class="squareb">[</span>FILL <span class="squareb">[</span>X'<span class="term">nn</span>'<span class="squareb">]</span> <span class="squareb">|</span> CLEAR<span class="squareb">]</span><br />
</p><br />
<br />
===NEW PAGE===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(C)]] </td><br />
<td><p class="syntaxUL">NEW PAGE </p></td></tr><br />
</table><br />
<br />
===[[Note statement|Note]]===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td><br />
<td><p class="syntaxUL">Note <span class="squareb">{</span><span class="term">fieldname</span> <span class="squareb">[</span>(<span class="term">subscript</span>)<span class="squareb">]</span><span class="squareb">}</span> </p></td></tr><br />
</table><br />
<p class="syntaxUL">Note '<span class="term">string</span>' <br />
</p><br />
<br />
===[[On statement|On]]===<br />
<br />
<p class="syntaxUL">[[On statement|On]] <span class="squareb">{</span>Attention <span class="squareb">|</span> Error <span class="squareb">|</span> Field Constraint Conflict<br />
<span class="squareb">|</span> Find Conflict <span class="squareb">|</span> Missing File <span class="squareb">|</span> Missing Member<br />
<span class="squareb">|</span> Record Locking Conflict<span class="squareb">}</span><br />
<span class="term">statements</span><br />
End On <span class="squareb">[</span><span class="term">label</span><span class="squareb">]</span><br />
</p><br />
<br />
===Open===<br />
<br />
{{Template:Open (External I/O) statement syntax}}<br />
<br />
<p></p> <!--Don't ask me why!--><br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(C)]] </td><br />
<td>{{Template:Open and OpenC statements syntax}} </td></tr><br />
</table><br />
<br />
===OPEN PROCESS===<br />
<br />
<p class="syntaxUL">OPEN PROCESS <span class="squareb">{</span><span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
<span class="squareb">[</span>CID <span class="squareb">{</span><span class="term">name</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><span class="squareb">]</span> </p><br />
<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td><br />
<td><p class="syntaxUL">OPEN PROCESS <span class="squareb">{</span><span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> <br> <span class="squareb">[</span>CID <span class="squareb">{</span><span class="term">name</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><span class="squareb">]</span> <br> <span class="squareb">{</span><span class="term">outbound-options</span> <span class="squareb">|</span> <span class="term">inbound-options</span><span class="squareb">}</span><br />
</p></td></tr><br />
</table><br />
<br />
<div style="margin-left: 30px; background-color: #fBfBfB;"><br />
<p><br />
where <var class="term">outbound-options</var> are:</p><br />
<ul style="font-family: Consolas,monospace"><br />
<li><span class="squareb">[</span>AT DESTINATION<span class="squareb">]</span> <span class="squareb">[</span>WITH<span class="squareb">]</span> <span class="squareb">[</span>USERID <span class="squareb">{</span><i>%variable</i> <span class="squareb">|</span> '<i>string</i>'<span class="squareb">}</span><span class="squareb">]</span><br />
<br />
<li><span class="squareb">[</span>PASSWORD <span class="squareb">{</span><i>%variable</i> <span class="squareb">|</span> '<i>string</i>'<span class="squareb">}</span><span class="squareb">]</span><br />
<br />
<li>[<span class="squareb">{</span>ACCOUNT <span class="squareb">|</span> PROFILE <span class="squareb">{</span>%<i>%variable</i> <span class="squareb">|</span> '<i>string</i>'<span class="squareb">}</span><span class="squareb">]</span><br />
<br />
<li><span class="squareb">[</span>INITIAL <span class="squareb">{</span>DATA '<i>string</i>' <span class="squareb">|</span> DATA <i>%variable</i> <span class="squareb">|</span> IMAGE <i>imagename</i><span class="squareb">]</span> ...<span class="squareb">]</span><br />
</ul><br />
<p><br />
and <var class="term">inbound-options</var> are:</p><br />
<br />
<ul style="font-family: Consolas,monospace"><br />
<li>ACCEPT <span class="squareb">[</span>INITIAL <span class="squareb">{</span>DATA <i>%variable</i> <span class="squareb">|</span> IMAGE <i>image</i><span class="squareb">}</span> ...<span class="squareb">]</span> </li><br />
</ul><br />
<br />
</div> <!-- end indent of options --><br />
<br />
===[[Pause statement|Pause]]===<br />
<br />
{{Template:Pause statement syntax}}<br />
<br />
===PLACE RECORD ON===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td><br />
<td><p class="syntaxUL">[[Lists#PLACE RECORD and REMOVE RECORD statements|PLACE RECORD ON]] <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><br />
</p></td></tr><br />
</table><br />
<br />
===PLACE RECORDS===<br />
<br />
<p class="syntaxUL">PLACE RECORDS <span class="squareb">{</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname1</span><span class="squareb">}</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname2</span><br />
</p><br />
<br />
===Position===<br />
<br />
<p class="syntaxUL">POSITION <span class="squareb">{</span>FOUNDSET <span class="term">foundsortset_name</span> <span class="squareb">|</span> LIST <span class="term">list_name</span><span class="squareb">}</span> <span class="squareb">[</span>AT<span class="squareb">]</span> <span class="term">position_name</span></p><br />
<br />
<p class="note"><b>Note:</b> Use this form of the <var>Position</var> statement with <var>For</var> loop processing; see [[Global features#Position statement|Position statement]].</p><br />
<br />
<p class="syntaxUL">POSITION <span class="squareb">{</span><span class="term">ext-filename</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
AT KEY <span class="term">operator</span><span class="squareb">{</span><span class="term">value</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span></p><br />
<br />
<p class="note"><b>Note:</b> Use this form of the <var>Position</var> statement with external file processing using images; see [[Images#Position statement|Position statement]].</p><br />
<br />
===[[Full-screen feature|PREPARE]]===<br />
<br />
<p class="syntaxUL">PREPARE<br />
<span class="squareb">{</span><span class="squareb">[</span>[[Images#PrepareStmtImage|IMAGE]]<span class="squareb">]</span> <span class="term">imagename</span> <span class="squareb">|</span> <span class="squareb">[</span>[[Full-screen feature#PrepareStmtMenu|MENU]]<span class="squareb">]</span> <span class="term">menuname</span><br />
<span class="squareb">|</span> <span class="squareb">[</span>[[Full-screen feature#PrepareStmtScrn|SCREEN]]<span class="squareb">]</span> <span class="term">screenname</span><span class="squareb">}</span><br />
</p><br />
<br />
===Print===<br />
<br />
<p class="syntaxUL">Print <span class="term">[[#Print specification syntax|printSpecifications]]</span> </p><br />
<br />
===Print All Fieldgroup Information (PAFGI)===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td><br />
<td>{{Template:PAFGI statement syntax}} </td></tr><br />
</table><br />
<br />
===[[Print All Information statement|Print All Information]] or [[PAI statement|PAI]]===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td><br />
<td>{{Template:PAI statement syntax}} </td></tr><br />
</table><br />
<br />
===PRINT MENU===<br />
<br />
<p class="syntaxUL">PRINT <span class="squareb">[</span>MENU<span class="squareb">]</span> <span class="term">menuname</span> <span class="squareb">[</span>ALERT<span class="squareb">]</span><br />
<span class="squareb">[</span>TITLE <span class="squareb">{</span>'<span class="term">text</span>' <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> <span class="squareb">[</span>AT <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">n</span><span class="squareb">]</span><br />
<span class="squareb">[</span>TO <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">m</span> <span class="squareb">|</span> LEN <span class="term">m</span><span class="squareb">]</span> <span class="squareb">[</span><span class="term">attributes</span><span class="squareb">]</span><span class="squareb">]</span><br />
</p><br />
<br />
===PRINT SCREEN===<br />
<br />
<p class="syntaxUL">PRINT SCREEN <span class="term">screenname</span> <span class="squareb">[</span>ALERT<span class="squareb">]</span> <span class="squareb">[</span><span class="squareb">[</span>WITH<span class="squareb">]</span> CURSOR<span class="squareb">]</span><br />
<span class="squareb">[</span>TITLE <span class="squareb">{</span>'<span class="term">text</span>' <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> <span class="squareb">[</span>AT <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">n</span><span class="squareb">]</span><br />
<span class="squareb">[</span>TO <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">m</span> <span class="squareb">|</span> LEN <span class="term">m</span><span class="squareb">]</span> <span class="squareb">[</span><span class="term">attributes</span><span class="squareb">]</span><span class="squareb">]</span><br />
</p><br />
<br />
===[[Horizon SOUL interface#Query Process statement|Query Process]]===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td><br />
<td>{{Template:Query Process statement syntax}} </td></tr><br />
</table><br />
<br />
===<b id="READ"></b>[[Read Image statement|Read Image]]===<br />
<br />
{{Template:Read Image statement syntax}}<br />
<br />
===READ <i>menuname</i>===<br />
<br />
<p class="syntaxUL">READ <span class="squareb">[</span>MENU<span class="squareb">]</span> <span class="term">menuname</span> <span class="squareb">[</span>ALERT<span class="squareb">]</span><br />
<span class="squareb">[</span>TITLE <span class="squareb">[</span>'<span class="term">text</span>' <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> <span class="squareb">[</span>AT <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">n</span><span class="squareb">]</span><br />
<span class="squareb">[</span>TO <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">m</span> <span class="squareb">|</span> LEN <span class="term">m</span><span class="squareb">]</span> <span class="squareb">[</span><span class="term">attributes</span><span class="squareb">]</span><span class="squareb">]</span><br />
</p><br />
<br />
===READ <i>screenname</i>===<br />
<br />
<p class="syntaxUL">READ <span class="squareb">[</span>SCREEN<span class="squareb">]</span> <span class="term">screenname</span> <span class="squareb">[</span>ALERT<span class="squareb">]</span> <span class="squareb">[</span>NO REREAD<span class="squareb">]</span> <span class="squareb">[</span> <span class="squareb">[</span>WITH<span class="squareb">]</span> CURSOR<span class="squareb">]</span><br />
<span class="squareb">[</span>TITLE <span class="squareb">{</span>'<span class="term">text</span>' <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> <span class="squareb">[</span>AT <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">n</span><span class="squareb">]</span><br />
<span class="squareb">[</span>TO <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">m</span> <span class="squareb">|</span> LEN <span class="term">m</span><span class="squareb">]</span> <span class="squareb">[</span><span class="term">attributes</span><span class="squareb">]</span><span class="squareb">]</span><br />
</p><br />
<br />
===RECEIVE IMAGE===<br />
<br />
<p class="syntaxUL">RECEIVE <span class="squareb">{</span>IMAGE <span class="term">imagename</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
FROM <span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> <span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> <span class="squareb">[</span>RESULT <span class="term">%variable</span><span class="squareb">]</span> </p><br />
<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td><br />
<td><p class="syntaxUL">RECEIVE <span class="squareb">{</span>IMAGE <span class="term">imagename</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> <br> FROM <span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> <span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> <br> RESULT <span class="term">%variable</span><br />
</p></td></tr><br />
</table><br />
<br />
===[[Release All Records statement|Release All Records]]===<br />
<br />
{{Template:Release All Records statement syntax}}<br />
<br />
===RELEASE POSITION===<br />
<br />
<p class="syntaxUL">RELEASE POSITION <span class="squareb">{</span><span class="term">ext-filename</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
</p><br />
<br />
===[[Release Records statement|Release Records]]===<br />
<br />
{{Template:Release Records statement syntax}}<br />
<br />
===REMEMBER===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td><br />
<td><p class="syntaxUL">REMEMBER <span class="squareb">[</span>GLOBAL<span class="squareb">]</span> <span class="term">position_name</span> <br> <span class="squareb">[</span>IN <span class="term">foundsortset_name</span> <span class="squareb">|</span> ON <span class="term">list_name</span><span class="squareb">]</span><br />
</p></td></tr><br />
</table><br />
<br />
===REMOVE RECORD FROM===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td><br />
<td><p class="syntaxUL">[[Lists#PLACE RECORD and REMOVE RECORD statements|REMOVE RECORD FROM]] <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><br />
</p></td></tr><br />
</table><br />
<br />
===REMOVE RECORDS===<br />
<br />
<p class="syntaxUL">REMOVE RECORDS <span class="squareb">{</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">}</span><br />
FROM <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname2</span><br />
</p><br />
<br />
===REPEAT===<br />
<br />
<p class="syntaxUL">REPEAT <span class="squareb">[</span>FOREVER <span class="squareb">|</span> <span class="term">n</span> TIMES <span class="squareb">|</span> WHILE <span class="term">expression</span><span class="squareb">]</span><br />
</p><br />
<br />
===REREAD===<br />
<br />
<p class="syntaxUL">REREAD <span class="squareb">[</span>SCREEN<span class="squareb">]</span> <span class="term">screenname</span> <span class="squareb">[</span>ALERT<span class="squareb">]</span> <span class="squareb">[</span><span class="squareb">[</span>WITH<span class="squareb">]</span> CURSOR<span class="squareb">]</span><br />
<span class="squareb">[</span>TITLE <span class="squareb">{</span>'<span class="term">text</span>' <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> <span class="squareb">[</span>AT <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">n</span><span class="squareb">]</span><br />
<span class="squareb">[</span>TO <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">m</span> <span class="squareb">|</span> LEN <span class="term">m</span><span class="squareb">]</span> <span class="squareb">[</span><span class="term">attributes</span><span class="squareb">]</span><span class="squareb">]</span><br />
</p><br />
<br />
===RESET===<br />
<br />
<p class="syntaxUL">RESET <span class="squareb">{</span>HEADER <span class="squareb">|</span> TRAILER<span class="squareb">}</span> <span class="term">m</span><br />
</p><br />
<br />
===RETRY===<br />
<br />
<p class="syntaxUL">RETRY <span class="squareb">[</span>PENDING STATEMENT<span class="squareb">]</span><br />
</p><br />
<br />
===RETURN===<br />
<br />
<p class="syntaxUL">RETURN<br />
</p><br />
<br />
===<b id="SCREEN"></b>[[Screen statement or block|Screen]]===<br />
<br />
{{Template:Screen statement syntax}}<br />
<br />
===SEND===<br />
<br />
<p class="syntaxUL">SEND <span class="squareb">{</span>IMAGE <span class="term">imagename</span> <span class="squareb">|</span> '<span class="term">string</span>' <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
TO <span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> <span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
<span class="squareb">[</span>REQSEND <span class="term">%variable</span><span class="squareb">]</span><br />
<span class="squareb">[</span>FLUSH<span class="squareb">]</span><br />
<br />
<br />
<b><sup>(+)</sup></b>SEND <span class="squareb">{</span>IMAGE <span class="term">imagename</span> <span class="squareb">|</span> '<span class="term">string</span>' <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
TO <span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> <span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
<span class="squareb">[</span>FLUSH <span class="squareb">|</span> CONFIRM<span class="squareb">]</span><br />
<span class="squareb">[</span>REQSEND <span class="term">%variable</span><span class="squareb">]</span><br />
</p><br />
<br />
===[[Horizon SOUL interface#Send Error statement|Send Error]]===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td><br />
<td>{{Template:Send Error statement syntax}} </td></tr><br />
</table><br />
<br />
===SET===<br />
<br />
<p class="syntaxUL">SET <span class="squareb">{</span>HEADER <span class="squareb">|</span> TRAILER<span class="squareb">}</span> <span class="term">m</span> <span class="term">[[#Print specification syntax|print-specifications]]</span><br />
</p><br />
<br />
===[[SetText statement|SetText]]===<br />
<br />
{{Template:SetText statement syntax}}<br />
<br />
===SIGNAL PROCESS===<br />
<br />
<p class="syntaxUL">SIGNAL PROCESS<br />
<span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> [<span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> <span class="squareb">{</span><span class="term">nnn</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> </p><br />
<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td><br />
<td><p class="syntaxUL">SIGNAL PROCESS <br> <span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> [<span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
</p></td></tr><br />
</table><br />
<br />
===SKIP LINES===<br />
<br />
<p class="syntaxUL">SKIP <span class="term">n</span> LINE<span class="squareb">[</span>S<span class="squareb">]</span><br />
</p><br />
<br />
===[[Skip Position statement|Skip Position]]===<br />
<br />
<table class="noBorder"><br />
<tr><td>{{Template:Skip Position statement syntax}} </td></tr><br />
</table><br />
<br />
===SORT RECORDS===<br />
<br />
<p class="syntaxUL">SORT [<span class="term">k</span><span class="squareb">]</span> RECORDS <span class="squareb">{</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">}</span><br />
BY <span class="term">key</span> <span class="squareb">[</span>AND <span class="term">key</span><span class="squareb">]</span> ...<br />
</p><br />
<br />
<div style="margin-left: 20px; background-color: #fBfBfB;"><br />
<p><br />
where <var class="term">key</var> is:</p><br />
<ul style="font-family: Consolas,monospace"><br />
<li><i>key</i> = <i>fieldname</i> <br><br />
<span class="squareb">[</span>VALUE <span class="squareb">{</span><span class="squareb">[</span>ASCENDING <span class="squareb">|</span> DESCENDING<span class="squareb">]</span> <br><br />
<span class="squareb">[</span>CHARACTER <span class="squareb">|</span> NUMERICAL<span class="squareb">]</span> <span class="squareb">|</span> RIGHT-ADJUSTED<span class="squareb">]</span><span class="squareb">}</span> ...<span class="squareb">]</span> </li><br />
</ul><br />
<br />
</div> <!--end key indent --><br />
<br />
===SORT RECORD KEYS===<br />
<br />
<p class="syntaxUL">SORT [<span class="term">k</span><span class="squareb">]</span> RECORD KEYS<br />
<span class="squareb">{</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">}</span><br />
BY <span class="term">key</span> <span class="squareb">[</span>AND <span class="term">key</span><span class="squareb">]</span> ...<br />
</p><br />
<br />
<div style="margin-left: 20px; background-color: #fBfBfB;"><br />
<p><br />
where <var class="term">key</var> is:</p><br />
<ul style="font-family: Consolas,monospace"><br />
<li><i>key</i> = <i>fieldname</i> <br><br />
<span class="squareb">[</span>VALUE <span class="squareb">{</span><span class="squareb">[</span>ASCENDING <span class="squareb">|</span> DESCENDING<span class="squareb">]</span> <br><br />
<span class="squareb">[</span>CHARACTER <span class="squareb">|</span> NUMERICAL<span class="squareb">]</span> <span class="squareb">|</span> <span class="squareb">[</span>RIGHT-ADJUSTED<span class="squareb">]</span><span class="squareb">}</span> ...<span class="squareb">]</span> </li><br />
</ul><br />
<br />
</div><br />
<br />
===SORT VALUE IN===<br />
<br />
<p class="syntaxUL">SORT VALUE IN <span class="term">label</span> <span class="squareb">[</span>IN <span class="squareb">[</span>ASCENDING <span class="squareb">|</span> DESCENDING<span class="squareb">]</span><br />
[<u>CHARACTER</u> <span class="squareb">|</span> NUMERICAL<span class="squareb">]</span> <span class="squareb">|</span> <span class="squareb">[</span>RIGHT-ADJUSTED<span class="squareb">]</span> ORDER<span class="squareb">]</span><br />
</p><br />
<br />
===STOP===<br />
<br />
<p class="syntaxUL">STOP <span class="squareb">[</span>IF COUNT IN <span class="term">label</span> EXCEEDS <span class="term">n</span><span class="squareb">]</span><br />
</p><br />
<br />
===STORE RECORD===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*)]] </td><br />
<td><p class="syntaxUL">STORE RECORD [<span class="term">sort or hash key value</span><span class="squareb">]</span> <br> <span class="term">fieldname1</span>=[<span class="term">value1</span> <span class="squareb">|</span> (<span class="term">expression1</span>)<span class="squareb">]</span> <br> [<span class="term">fieldname2</span>=(<span class="term">expression</span>)<span class="squareb">]</span> <br> ... <br> <span class="squareb">[</span>THEN CONTINUE <br> <span class="term">statement</span> <br> <span class="term">statement</span> <br> ...<span class="squareb">]</span> <br> END STORE<br />
</p></td></tr><br />
</table><br />
<br />
===SUBROUTINE===<br />
<br />
<p class="syntaxUL">SUBROUTINE<br />
<br />
SUBROUTINE <span class="term">subname</span><br />
<span class="squareb">[</span>(<span class="term">formal-parameter</span> <span class="squareb">[</span>INPUT <span class="squareb">|</span> OUTPUT <span class="squareb">|</span> INPUT OUTPUT<span class="squareb">]</span> <span class="squareb">[</span>,...<span class="squareb">]</span>)<span class="squareb">]</span><br />
</p><br />
<br />
<div style="margin-left: 20px; background-color: #fBfBfB;"><br />
<p><br />
where <var class="term">formal-parameter</var> is one of the following:</p><br />
<ul style="font-family: Consolas,monospace"><br />
<li><i>%variable</i> <span class="squareb">[</span>IS STRING <span class="squareb">[</span>LEN <i>n</i><span class="squareb">]</span> <span class="squareb">[</span>DP <span class="squareb">{</span><i>n</i> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span>ARRAY (*<span class="squareb">[</span>,*<span class="squareb">[</span>,*<span class="squareb">]</span><span class="squareb">]</span>) <span class="squareb">[</span>NO FS<span class="squareb">]</span><span class="squareb">]</span> <br><br />
<span class="squareb">|</span> IS <span class="squareb">{</span>FIXED <span class="squareb">[</span>DP <i>n</i><span class="squareb">]</span> <span class="squareb">|</span> FLOAT<span class="squareb">}</span> <span class="squareb">[</span>ARRAY (*<span class="squareb">[</span>,*<span class="squareb">[</span>,*<span class="squareb">]</span><span class="squareb">]</span>)<span class="squareb">]</span><span class="squareb">]</span><br />
<br />
<li>LIST <i>listname</i> <span class="squareb">[</span>IN <span class="squareb">[</span>FILE <span class="squareb">|</span> <span class="squareb">[</span>PERM <span class="squareb">|</span> TEMP<span class="squareb">]</span> GROUP<span class="squareb">]</span> <i>name</i><span class="squareb">]</span><br />
</ul><br />
</div><br />
<br />
===TAG===<br />
<br />
<p class="syntaxUL">TAG <span class="term">%screenname</span>:<span class="term">inputname</span> <span class="squareb">[</span><span class="term">attributes</span><span class="squareb">]</span> <span class="squareb">[</span>WITH 'c'<span class="squareb">]</span><br />
</p><br />
<br />
===[[Horizon SOUL interface#Test Receipt statement|Test Receipt]]===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td><br />
<td>{{Template:Test Receipt statement syntax}} </td></tr><br />
</table><br />
<br />
===TITLE===<br />
<br />
<p class="syntaxUL">TITLE <span class="squareb">{</span>'<span class="term">text</span>' <span class="squareb">|</span> <span class="term">promptname</span><span class="squareb">}</span><br />
<span class="squareb">[</span>AT <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">n</span><span class="squareb">]</span> <span class="squareb">[</span>TO <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">m</span> <span class="squareb">|</span> <span class="squareb">[</span>LEN <span class="term">m</span><span class="squareb">]</span><br />
<span class="squareb">[</span>DP <span class="squareb">{</span><span class="term">k</span> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span><span class="squareb">]</span><br />
<span class="squareb">[</span>DEFAULT '<span class="term">value</span>'<span class="squareb">]</span><br />
<span class="squareb">[</span><span class="squareb">[</span>READ<span class="squareb">]</span> <span class="term">attributes</span><span class="squareb">]</span> <span class="squareb">[</span>REREAD <span class="term">attributes</span><span class="squareb">]</span> <span class="squareb">[</span>PRINT <span class="term">attributes</span><span class="squareb">]</span><br />
</p><br />
<br />
===<b id="trace"></b>[[Trace statement|Trace]]===<br />
<br />
{{Template:Trace statement syntax}}<br />
<br />
<p class="note"><b>Note:</b> The output of the <var>Trace</var> statement is controlled by the <var>[[ULTRACE parameter|ULTRACE]]</var> parameter.</p><br />
<br />
===TRANSFER===<br />
<br />
<p class="syntaxUL">TRANSFER <span class="squareb">[</span>CONTROL<span class="squareb">]</span> TO PROCESS <span class="squareb">{</span><span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
<span class="squareb">[</span>WITH<span class="squareb">]</span> <span class="squareb">[</span>USERID <span class="squareb">{</span><span class="term">string</span> <span class="squareb">|</span> '<span class="term">%variable</span>'<span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">[</span>PASSWORD <span class="squareb">{</span><span class="term">variable</span> <span class="squareb">|</span> '<span class="term">string</span>'<span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">[</span>ACCOUNT <span class="squareb">{</span><span class="term">%variable</span> <span class="squareb">|</span> '<span class="term">string</span>'<span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">[</span>PASSING <span class="squareb">{</span>IMAGE <span class="term">imagename</span> <span class="squareb">|</span> '<span class="term">string</span>' <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><span class="squareb">]</span><br />
</p><br />
<br />
===UPDATE RECORD===<br />
<br />
<p class="syntaxUL">UPDATE RECORD</p><br />
<br />
===VARIABLES ARE===<br />
<br />
<p class="syntaxUL">VARIABLES ARE<br />
<span class="squareb">{</span>FIXED <span class="squareb">[</span>DP <span class="term">n</span><span class="squareb">]</span> <span class="squareb">|</span> FLOAT<br />
<span class="squareb">|</span> STRING <span class="squareb">[</span>LEN <span class="term">n</span><span class="squareb">]</span> <span class="squareb">[</span>DP <span class="squareb">{</span><span class="term">n</span> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">|</span> UNDEFINED<span class="squareb">}</span><br />
</p><br />
<br />
===Declare <i>%variable</i>===<br />
<br />
<p class="syntaxUL"><span class="squareb">[</span>DECLARE<span class="squareb">]</span> <span class="term">%variable</span> <span class="squareb">[</span>IS<span class="squareb">]</span><br />
<span class="squareb">{</span>FIXED <span class="squareb">[</span>DP <span class="term">n</span><span class="squareb">]</span> <span class="squareb">|</span> FLOAT<span class="squareb">}</span> <span class="squareb">[</span>ARRAY (<span class="term">d1</span><span class="squareb">[</span>,<span class="term">d2</span><span class="squareb">[</span>,<span class="term">d3</span><span class="squareb">]</span><span class="squareb">]</span>)<span class="squareb">]</span><br />
<span class="squareb">[</span>COMMON<span class="squareb">]</span><br />
<br />
<span class="squareb">[</span>DECLARE<span class="squareb">]</span> <span class="term">%variable</span> <span class="squareb">[</span>IS<span class="squareb">]</span><br />
STRING <span class="squareb">[</span>LEN <span class="term">n</span><span class="squareb">]</span> <span class="squareb">[</span>DP <span class="squareb">{</span><span class="term">n</span> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span>ARRAY (<span class="term">d1</span><span class="squareb">[</span>,<span class="term">d2</span>[<span class="term">d3</span><span class="squareb">]</span><span class="squareb">]</span>)<span class="squareb">]</span><br />
<span class="squareb">[</span>NO FIELD SAVE<span class="squareb">]</span> <span class="squareb">[</span>COMMON<span class="squareb">]</span><br />
<span class="term">%variable</span> <span class="squareb">[</span>(<span class="term">subscript</span>)<span class="squareb">]</span> = <span class="term">expression</span><br />
</p><br />
<br />
===WAIT===<br />
<table class="noBorder"><br />
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td><br />
<td><p class="syntaxUL">WAIT [<span class="squareb">{</span><span class="term">n</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> SEC<span class="squareb">[</span>S<span class="squareb">]</span><span class="squareb">]</span> <span class="squareb">[</span>FOR<span class="squareb">]</span> <br> <span class="squareb">{</span>ANY RECEIPT RETURN <span class="term">%variable</span> <br> <span class="squareb">|</span> RECEIPT <span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> <span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><span class="squareb">}</span><br />
</p></td></tr><br />
</table><br />
<br />
===WRITE===<br />
<br />
<p class="syntaxUL">WRITE <span class="squareb">[</span>IMAGE<span class="squareb">]</span> <span class="term">imagename</span><br />
ON <span class="squareb">{</span><span class="term">seq-filename</span> <span class="squareb">|</span> TERMINAL <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
</p><br />
<br />
===WRITE IMAGE===<br />
<br />
<p class="syntaxUL">WRITE IMAGE <span class="term">imagename</span> ON BUFFER<br />
<span class="squareb">[</span>POSITION=<span class="term">%pvariable</span> <span class="squareb">|</span> <span class="term">n</span><span class="squareb">]</span> <span class="squareb">[</span>MAXLEN=<span class="squareb">{</span><span class="term">%lvariable</span> <span class="squareb">|</span> <span class="term">n</span><span class="squareb">}</span><span class="squareb">]</span><br />
</p><br />
<br />
==Other syntax==<br />
<br />
===<b id="tokens"></b>Names, numbers, literals, comments===<br />
<br />
<ul><br />
<li>Names (for example, %variables, labels): see [[Model 204 naming conventions]]<br />
<li>Other constructs: see [[Basic request structure]] (which also discusses some rules for statement labels)<br />
</ul><br />
<br />
===Value specification syntax===<br />
<p><br />
For all User Language statements and retrieval conditions, wherever the term <var class="term">value</var> appears in the syntax, it can be any of these:</p><br />
<ul><br />
<li>Literal number or string </li><br />
<li><var>VALUE IN</var> clause of the form:<br />
<p class="syntax">VALUE <span class="squareb">[</span>IN<span class="squareb">]</span> <span class="term">label</span><br />
</p><br />
</li><br />
<li>%variable</li><br />
</ul><br />
<br />
===Retrieval condition syntax===<br />
<p><br />
A <var>Find</var> or <var>For Each Record Where</var> statement can be followed by any number of retrieval conditions separated by an end of line or [[LINEND parameter]] character.</p><br />
<p><br />
Conditions can be constructed as a series of phrases that are combined "in the usual way" with <var>And</var>, <var>Or</var>, <var>Not</var>, and parentheses (<b>()</b>):<br />
</p><br />
<p class="syntax">[Not] <span class="term">phrase</span> [<span class="squareb">{</span>And <span class="squareb">|</span> Or <span class="squareb">|</span> Nor<span class="squareb">}</span> [Not] <span class="term">phrase</span>] ...<br />
</p><br />
<p><br />
Where: </p><br />
<p><br />
<var class="term">phrase</var> can be constructed from these options: </p><br />
<ul style="font-family: Consolas,monospace"><br />
<li><var class="term">fieldname</var> = <span class="squareb">[</span>Not<span class="squareb">]</span> <i>value</i> </li><br />
<br />
<li><var class="term">fieldname</var> Like <i>pattern</i> </li><br />
<br />
<li><var class="term">fieldname</var> Is [Not] <span class="squareb">{</span>Present <span class="squareb">|</span> Like '<i>pattern</i>'<span class="squareb">}</span> </li><br />
<br />
<li><var class="term">fieldname</var> Is [Not] <span class="squareb">{</span>[Numerically <span class="squareb">|</span> Alphabetically] <br><br />
[Eq <span class="squareb">|</span> = <span class="squareb">|</span> Ne <span class="squareb">|</span> ¬= <span class="squareb">|</span> Greater Than <span class="squareb">|</span> Gt <span class="squareb">|</span> > <span class="squareb">|</span> Less Than <br><span class="squareb">|</span> Lt <span class="squareb">|</span> < <span class="squareb">|</span> Le <span class="squareb">|</span> <= <span class="squareb">|</span> Ge <span class="squareb">|</span> >= <span class="squareb">|</span> Before <span class="squareb">|</span> After] <i>value</i><span class="squareb">}</span> </li><br />
<br />
<li><var class="term">fieldname</var> Is [Not] <span class="squareb">{</span>[Numerically <span class="squareb">|</span> Alphabetically] <br><br />
<span class="squareb">{</span>In Range [From <span class="squareb">|</span> After] <i>value1</i> <span class="squareb">{</span>To <span class="squareb">|</span> [And] Before<span class="squareb">}</span> <br><br />
<i>value2</i> <span class="squareb">|</span> Between <i>value1</i> And <i>value2</i><span class="squareb">}</span> </li><br />
<br />
<li>[[Record retrievals#FILE$ condition|File$]] <span class="squareb">{</span><i>filename</i> <span class="squareb">|</span> =<span class="squareb">}</span> </li><br />
<br />
<li>Find$ <var class="term">label</var> </li><br />
<br />
<li>[[Lists#Using the LIST$ condition|List$]] <i>listname</i> </li><br />
<br />
<li>[[Record retrievals#LOCATION$ condition|Location$]] <span class="squareb">{</span><i>location</i> <span class="squareb">|</span> =<span class="squareb">}</span> </li><br />
<br />
<li>[[#Point$|Point$]] <var class="term">value</var> </li><br />
<br />
<li>[[#Sfl$ and Sfge$|Sfge$]] <var class="term">value</var> </li><br />
<br />
<li>[[#Sfl$ and Sfge$|Sfl$]] <var class="term">value</var> </li><br />
</ul><br />
<p><br />
where <var class="term">value</var> can be: </p><br />
<ul><br />
<li>A literal number or string</li><br />
<br />
<li>A %variable </li><br />
<br />
<li><var>Value <span class="squareb">{</span>(<i>[[#Use of expressions|expression]]</i>)</var> | [In] <i>label</i><span class="squareb">}</span><br />
<p><br />
<var class="term">label</var> points to an existing value set. If an <var>Eq Value In <i>value_set</i></var> clause, value set values are treated as Boolean OR, for example: <br />
</p><br />
<p class="code"><i>field</i> = <i>value1</i> OR <i>field</i> = <i>value2</i> OR.... </p><br />
<p><br />
If an <var>Ne Value In <i>value_set</i></var> clause, values are treated as Boolean AND: </p><br />
<p class="code"><i>field</i> <> <i>value1</i> AND <i>field</i> <> <i>value2</i> AND.... </p><br />
<p><br />
See also [[Basic SOUL statements and commands#Processing a VALUE IN clause|Processing a VALUE IN clause]].</p></li><br />
</ul><br />
<br />
<p><b>Notes:</b></p><br />
<ul><br />
<li>The first character (<code>¬</code>) of the "not-equal" test (<code>¬=</code>) in the fourth of the items in the list of <var class="term">phrase</var> options above is the EBCDIC "not sign," which has the hexadecimal value <code>5f</code>. </li><br />
<br />
<li>For a description of the pattern in the <var>[Is] Like</var> and <var>Is Not</var> clauses, see the syntax of [[Is Like pattern matching#likeSyntax|Is Like patterns]]. </li><br />
<br />
<li>In addition to the discussions in the subsections that follow, see [[Record retrievals]] for a comprehensive description of retrieval conditions. </li><br />
</ul><br />
<br />
====Omitting repeated first words====<br />
<p><br />
If a sequence of phrases in a particular retrieval condition all have the same first word, that word can be omitted from the latter phrases. For example:</p><br />
<p class="code">List$ A And Not List$ B<br />
</p><br />
<p><br />
can be written:</p><br />
<p class="code">List$ A And Not B<br />
</p><br />
<p><br />
And:</p><br />
<p class="code">x Is 13 Or x Is Less Than 7<br />
</p><br />
<p><br />
can be written:</p><br />
<p class="code">x Is 13 Or Is Less Than 7<br />
</p><br />
<br />
====Omitting duplicated equal signs====<br />
<p><br />
Duplicated equal signs can be omitted. For example, the expression:</p><br />
<p class="code">a = 3 Or a = 5 Or a = 40<br />
</p><br />
<p><br />
is equivalent to:</p><br />
<p class="code">a = 3 Or 5 Or 40<br />
</p><br />
<br />
====Use of parentheses====<br />
<p><br />
Parentheses can be placed around any sequence of phrases to clarify the condition or force the evaluation to occur in a particular order. For example:</p><br />
<p class="code">Not (a = 2 Or List$ y)<br />
a = 1 And (b = 2 OR c = 3)<br />
</p><br />
<br />
====Use of expressions====<br />
<p><br />
[[Using variables and values in computation#Expressions|Expressions]] can be used in <var>Find</var> and <var>For Each Record</var> statements to provide the retrieval condition for the <var>Point$</var>, <var>Sfl$</var>, and <var>Sfge$</var> conditions, as well as for the <var>Eq Value</var> clause: </p><br />
<br />
=====Point$=====<br />
<p class="syntax">Point$ Value(<span class="term">expression</span>)<br />
</p><br />
Where:<br />
<p><br />
<var class="term">expression</var> is a function call, string concatenation, arithmetic operation, SOUL construct, or Boolean expression. It is preceded by the keyword <var>Value</var>. </p><br />
<p> <br />
Example: </p><br />
<p><br />
This example finds the first <code>MA</code> record on file, and then counts the number of records from this point in the file:</p><br />
<p class="code">FD1:<br />
<br />
IN ICSCUST FPC STATE = MA<br />
END FIND<br />
FOR 1 RECORD IN FD1<br />
PRINT 'CURREC = ' WITH $CURREC<br />
PRINT '>= POINT$'<br />
FD2:<br />
IN ICSCUST FPC POINT$ VALUE($CURREC)<br />
END FIND<br />
END FOR<br />
</p><br />
<br />
=====Sfl$ and Sfge$=====<br />
<p class="syntax">Sfl$ Value(<span class="term">expression</span>)<br />
</p><br />
<p><br />
Or:</p><br />
<p class="syntax">Sfge$ Value(<span class="term">expression</span>)<br />
</p><br />
Where:<br />
<p><br />
<var class="term">expression</var> is a function call, string concatenation, arithmetic operation, SOUL construct, or Boolean expression. It is preceded by the keyword <var>Value</var>. </p><br />
<p><br />
Example:<br />
</p><br />
<p class="code">FOR %CT FROM 1 TO 10<br />
IN EXPRESS STORE RECORD ($EDITN(%CT,'999'))<br />
ORD1 = (%REC WITH %CT)<br />
ORD2 = (%CT * 2)<br />
ORD4 = (%CT * 4)<br />
END STORE<br />
END FOR<br />
COMMIT<br />
FOR %CT FROM 1 TO 5<br />
PRINT 'LESS THAN ' WITH %CT<br />
FD1:<br />
IN EXPRESS FPC SFL$ VALUE($EDITN(%CT,'999'))<br />
END FIND<br />
PRINT 'GREATER THAN OR EQUAL TO ' WITH %CT<br />
FD2:<br />
IN EXPRESS FPC SFGE$ VALUE($EDITN(%CT,'999'))<br />
END FIND<br />
END FOR<br />
</p><br />
<br />
=====Eq Value=====<br />
<p class="syntax"><span class="term">fieldname</span> Eq Value(<span class="term">expression</span>)<br />
</p><br />
Where:<br />
<p><br />
<var class="term">expression</var> is a function call, string concatenation, arithmetic operation, SOUL construct, or Boolean expression. </p><br />
<p><br />
Example:<br />
</p><br />
<p class="code">FD: IN FILE PEOPLE FD<br />
LAST EQ VALUE($READ('LAST NAME?') )<br />
END FIND<br />
</p><br />
<br />
===Print specification syntax===<br />
<p><br />
A <var>Print</var>, <var>Set</var>, <var>Audit</var>, or <var>Trace</var> statement contains print specifications of the following form:<br />
</p><br />
<p class="syntax">[<span class="term">term</span>] <span class="squareb">[</span>And <span class="squareb">|</span> Tab <span class="squareb">|</span> With]...[[<span class="term">term</span>] [And <span class="squareb">|</span> Tab <span class="squareb">|</span> With] ...] ... [...]<br />
</p><br />
Where:<br />
<p><br />
<var class="term">term</var> can be constructed as follows:</p><br />
<p class="syntax"><span class="squareb">{</span>'<span class="term">string</span>' <span class="squareb">|</span> <span class="term">%variable</span> <span class="squareb">|</span> Count In <span class="term">label</span> <span class="squareb">|</span> Occurrence In <span class="term">label</span> <span class="squareb">|</span> Value in <span class="label">term</span> <span class="squareb">|</span> <span class="term">function</span><span class="squareb">}</span><br />
<span class="squareb">[</span>At <span class="squareb">[</span>Column<span class="squareb">]</span> <span class="term">m</span><span class="squareb">]</span> <span class="squareb">[</span>To <span class="squareb">[</span>Column<span class="squareb">]</span> <span class="term">n</span><span class="squareb">]</span> </p><br />
<p><br />
Or, if the statement is within a record loop:<br />
</p><br />
<p class="syntax"><span class="squareb">{</span><span class="squareb">{</span>Each <span class="squareb">|</span> <span class="n">term</span><span class="squareb">}</span> <span class="term">fieldname</span> <span class="squareb">|</span> *Record <span class="squareb">|</span> *Id<span class="squareb">}</span><br />
[At [Column] <span class="term">m</span>] [To [Column] <span class="term">n</span><span class="squareb">}</span><br />
</p><br />
<br />
<p class="note"><b>Note:</b> For additional <var>Print</var> statement details regarding multiply occurring fields and field groups, see [[Processing multiply occurring fields and field groups#PRINT and PRINT n statements|Print and Print <i>n</i>]] statements for fields. </p><br />
<br />
===Expression syntax===<br />
<p><br />
The following syntax can be used in: </p><br />
<ul><br />
<li>Assignment statements </li><br />
<li>Conditional <var>If</var> statements and <var>ElseIf</var> clauses<br />
<p><br />
In the simplified syntax for an <var>If</var> statement, which is:</p><br />
<p class="syntax">If <span class="term">condition</span> Then <span class="term">statements</span><br />
</p><br />
<p><br />
<var class="term">condition</var> expands to the syntax described in this section. </p></li><br />
<br />
<li>Computed <var>Jump To</var> statements </li><br />
<br />
<li>Subscripts </li><br />
<br />
<li>Function arguments </li><br />
</ul><br />
<br />
=====Syntax=====<br />
<p class="syntax"><span class="squareb">{</span>operand | (expression)<span class="squareb">}</span> [operator <span class="squareb">{</span>operand <span class="squareb">|</span> (expression)<span class="squareb">}</span>] ...<br />
</p><br />
Where:<br />
<ul><br />
<li><var class="term">operand</var> can be constructed as follows:<br />
<p class="syntax">[+ <span class="squareb">|</span> - <span class="squareb">|</span> Not]<br />
<span class="squareb">{</span>'<span class="term">string</span>' <span class="squareb">|</span> <span class="term">%variable</span> <span class="squareb">|</span> <span class="term">number</span><br />
<span class="squareb">|</span> <span class="term">fieldname</span> <span class="squareb">[</span>(subscript)<span class="squareb">]</span> Is <span class="squareb">[</span>Not<span class="squareb">]</span> Present<br />
<span class="squareb">|</span> Count In <span class="term">label</span> <span class="squareb">|</span> Occurrence In <span class="term">label</span><br />
<span class="squareb">|</span> Value In <span class="term">label</span><br />
<span class="squareb">|</span> <span class="term">function</span><span class="squareb">}</span><br />
</p></li><br />
<br />
<li><var class="term">expression</var> (Note: enclosed by parentheses) is a function call, string concatenation, arithmetic operation, SOUL construct, or Boolean expression. For further details, see [[Using variables and values in computation#Expressions|Expressions]]. </li><br />
<br />
<li><var class="term">operator</var> may be one of the following: <br />
<table style="table-layout: fixed"><br />
<tr><br />
<td><b>+</b>&nbsp;&nbsp;&nbsp;</td><br />
<td><b>=</b></td><br />
<td>EQ</td><br />
<td>And</td><br />
</tr><br />
<br />
<tr><br />
<td><b>-</b></td><br />
<td><b>¬=</b>&nbsp;&nbsp;&nbsp;</td><br />
<td>NE&nbsp;&nbsp;</td><br />
<td>Or</td><br />
</tr><br />
<br />
<tr><br />
<td><b>*</b></td><br />
<td><b>></b></td><br />
<td>GT</td><br />
<td>With (Note: this can also be achieved via [[Implicit concatenation]])</td><br />
</tr><br />
<br />
<tr><br />
<td><b>/</b></td><br />
<td><b><</b></td><br />
<td>LT</td><br />
<td>Is [Not] Present (Note: applied either to a field or to an [[Methods#optionalParams|optional or default method parameter]])</td><br />
</tr><br />
<br />
<tr><br />
<td>&nbsp;</td><br />
<td><b>>=</b></td><br />
<td>GE</td><br />
<td>Is [Not] Like</td><br />
</tr><br />
<br />
<tr><br />
<td>&nbsp;</td><br />
<td><b><=</b></td><br />
<td>LE</td><br />
<td></td><br />
</tr><br />
</table><br />
<blockquote class="note"><b>Notes:</b><br />
<ul><br />
<li>The first character (<code>¬</code>) of the inequality test above is the EBCDIC "not sign," which has the hexadecimal value <code>5f</code>. </li><br />
<br />
<li>For a description of the <code>Is Like</code> and <code>Is Not</code> clauses, see the syntax of [[Is Like pattern matching|Is Like patterns]]. </li><br />
<br />
<li>For more information about operators, see [[Using variables and values in computation#Operators|Operators]]. </li><br />
</ul><br />
</blockquote ></li><br />
</ul><br />
<br />
===In clause syntax===<br />
<p><br />
The SOUL statements on this page whose syntax display is preceded by an asterisk (<tt>*</tt>) support an <var>In</var> clause. </p><br />
<p><br />
The three basic forms of the <var>In</var> clause are: </p><br />
<br />
<p class="syntax">In [Permanent <span class="squareb">|</span> Temporary ] Group <span class="term">groupname</span><br />
Member [<span class="term">%member</span> <span class="squareb">|</span> [<span class="term">filename</span> [At <span class="squareb">{</span>location <span class="squareb">|</span> =<span class="squareb">}</span>]]</p><br />
<br />
<p class="syntax">In <span class="term">file1</span> [,<span class="term">file2</span>] ...</p><br />
<br />
<p class="syntax">In <span class="squareb">{</span>$Curfile <span class="squareb">|</span> $Update<span class="squareb">}</span></p><br />
<p><br />
The form <var>In $Curfile</var> can be used only within a record loop.</p><br />
<br />
====In Group Member limitations====<br />
<p><br />
In addition to the three basic forms of the In clause shown above, the <var>In Group Member</var> clause restricts the following statements to one member file in a group context:</p><br />
<ul><br />
<li><var>Clear List</var></li><br />
<br />
<li><var>Find All Records</var> (and its variants)</li><br />
<br />
<li><var>Find All Values</var></li><br />
<br />
<li><var>For Record Number</var> (or <var>FRN</var>)</li><br />
<br />
<li><var>Store Record</var> </li><br />
</ul><br />
<p><br />
You cannot use an <var>In Group Member</var> clause with a <var>For Each Record</var> statement or with an <var>Add</var>, <var>Change</var>, or <var>Delete Record</var> statement. Only the previously listed statements call accept an <var>In Group Member</var> clause.</p><br />
<br />
====Using an In clause in a Begin...End block====<br />
<p><br />
The file name in the <var>In</var> clause used within a <var>Begin...End</var> block is resolved by the compiler. You can hard-code a file name or use some type of dummy string for the file name. Using a %variable for the file name is not allowed. </p><br />
<br />
===Subscript syntax===<br />
<p><br />
A subscript has the format: </p><br />
<br />
=====Syntax=====<br />
<p class="syntax">(<span class="term">subscript1</span> [,<span class="term">subscript2</span> [,<span class="term">subscript3</span>]] )<br />
</p><br />
Where:<br />
<p><br />
<var class="term">subscript1</var>, <var class="term">subscript2</var>, and <var class="term">subscript3</var> can be any expression. </p><br />
<br />
==Terminal display attributes==<br />
<p><br />
One or more of the following terminal display attributes can replace the term attribute in a full-screen formatting statement, if the display attribute is supported by the installation:</p><br />
<br />
<table><br />
<caption>List of attributes</caption><br />
<tr><br />
<td>BLINK</td><br />
</tr><br />
<tr><br />
<td>BLUE</td><br />
</tr><br />
<tr><br />
<td>BRIGHT</td><br />
</tr><br />
<tr><br />
<td>DIM</td><br />
</tr><br />
<tr><br />
<td>GREEN</td><br />
</tr><br />
<tr><br />
<td>INV[IS[BLE]] </td><br />
</tr><br />
<tr><br />
<td>NOBLINK</td><br />
</tr><br />
<tr><br />
<td>NOREV[ERSE]</td><br />
</tr><br />
<tr><br />
<td>NOU[NDER]SCORE</td><br />
</tr><br />
<tr><br />
<td>PINK</td><br />
</tr><br />
<tr><br />
<td>PROT[ECTED]</td><br />
</tr><br />
<tr><br />
<td>RED</td><br />
</tr><br />
<tr><br />
<td>REV[ERSE]</td><br />
</tr><br />
<tr><br />
<td>TURQUOISE</td><br />
</tr><br />
<tr><br />
<td>[UNDER]SCORE</td><br />
</tr><br />
<tr><br />
<td>UNPROT[ECTED]</td><br />
</tr><br />
<tr><br />
<td>VIS[IBLE]</td><br />
</tr><br />
<tr><br />
<td>WHITE</td><br />
</tr><br />
<tr><br />
<td>YELLOW </td><br />
</tr><br />
</table><br />
<br />
==Notation conventions==<br />
<p><br />
This page uses the following syntax notation conventions: </p><br />
<br />
<table><br />
<tr class="head"><br />
<th>Syntax notation </th><br />
<th>Indicates that...</th><br />
</tr><br />
<br />
<tr><br />
<td>Single asterisk (*) </td><br />
<td>Statements can be preceded by an IN clause, if there is no reference to a previous set (label or list). See [[#IN clause syntax|IN clause syntax]] for more discussion.</td><br />
</tr><br />
<br />
<tr><br />
<td>Two asterisks (**) </td><br />
<td>Construct can appear only within a record loop.</td><br />
</tr><br />
<br />
<tr><br />
<td>Plus sign (+) </td><br />
<td>Construct requires the optional [[Horizon]] feature.</td><br />
</tr><br />
<br />
<tr><br />
<td nowrap>Two plus signs (++) </td><br />
<td>Construct requires the optional User Language to Database 2 feature.</td><br />
</tr><br />
<br />
<tr><br />
<td>C</td><br />
<td>The syntax applies to a <var class="product">Model&nbsp;204</var> command as well as a SOUL statement, except any %variable options or clauses.<br />
<p><br />
<var class="product">Model&nbsp;204</var> commands are listed alphabetically and documented in [[List of Model 204 commands]]. </p></td><br />
</tr><br />
<br />
<tr><br />
<td>Lowercase italic </td><br />
<td>Constructs are replaced with variable information.</td><br />
</tr><br />
</table><br />
<br />
<ul><br />
<li>A field name (%%) variable can be used anywhere fieldname appears. The %%variable can contain its own subscript, separate from the field name subscript.<br />
<p class="note"><b>Note: </b><br />
The subscript of an array element must be specified before a field name subscript.</p> </li><br />
<br />
<li>The lowercase constructs &mdash; retrieval-conditions, print-specifications, expression, subscript, attribute, and type &mdash; are discussed separately following the syntax summaries, beginning with [[#Value specification syntax|Value specification syntax]]. </li><br />
<br />
<li>For more Model 204 notation conventions, see [[Notation conventions]].</li><br />
</ul><br />
<br />
<br />
[[Category:SOUL]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=MediaWiki:Common.css&diff=115155MediaWiki:Common.css2018-05-07T20:25:33Z<p>Admin: line-height for syntax increased to 1.35</p>
<hr />
<div>/* CSS placed here will be applied to all skins */<br />
/* See also MediaWiki:Vector.css, MediaWiki:MonoBook.css, <br />
/* MediaWiki:Modern.css */<br />
<br />
/* *** NOTE: MANY SKIN TWEAKS ARE SPECIFIED IN MediaWiki:Vector.css *** /*<br />
<br />
/* following comment won't work for IE>9 */<br />
<!-[if gte IE8]<br />
<linkrel=”stylesheet” type=”text/css” href=”/stylesheets/standards.css”/><br />
<![endif]-><br />
<br />
/* current practice is to use p class="code" instead of this pre tag */<br />
pre {<br />
overflow-x: auto; /* Use horizontal scroller if needed; for FF2, not needed in FF3 */<br />
overflow-y: hidden; /* overflow-x above messes up Chrome, this is the fix. Sigh */<br />
white-space: pre-wrap; /* css-3 */<br />
white-space: -moz-pre-wrap !important; /* Mozilla, since 1999 */<br />
white-space: -pre-wrap; /* Opera 4-6 */<br />
white-space: -o-pre-wrap; /* Opera 7 */ /*<br />
width: 99%; */<br />
word-wrap: break-word; /* Internet Explorer 5.5+ */<br />
}<br />
<br />
p.pre, p.code, p.codeInTable, p.output, p.syntax, p.syntaxUL, p.pre pre.syntax {<br />
color: #000;<br />
background-color: #f9f9f9;<br />
padding: 5px 5px 5px 10px;<br />
border: 1px dashed #4169E1;<br />
font-family: Consolas,"Liberation Mono",monospace;<br />
line-height: 1.2;<br />
vertical-align: baseline;<br />
white-space: pre; /* pre-wrap OK if IE>=11, but we want code not to wrap */<br />
overflow: auto; <br />
}<br />
<br />
p.codeInTable {<br />
border:0; <br />
padding:0;<br />
margin-top:0;<br />
font-family: Consolas,"Liberation Mono",monospace;<br />
}<br />
<br />
p.syntax {<br />
line-height: 1.35; <br />
}<br />
<br />
p.syntaxUL {<br />
line-height: 1.35; <br />
display: inline-block;<br />
}<br />
<br />
/* make bold in syntax larger */<br />
.syntax b {<br />
font-size: 105%;<br />
}<br />
<br />
p.syntaxUL~hr {<br />
height: 2px;<br />
margin: 2px 0;<br />
}<br />
<br />
span.squareb {<br />
font-size: 105%;<br />
font-weight: bold;<br />
color: black;<br />
}<br />
<br />
span.literal {<br />
font-style: normal;<br />
color: #501010;<br />
}<br />
<br />
span.term {<br />
font-style: italic;<br />
color: #000;<br />
}<br />
<br />
<br />
span.boldGreen {<br />
font-weight: bold;<br />
color: green;<br />
}<br />
<br />
/* for error-message page subtitle */<br />
span.msgtext {<br />
font-family: Arial, Helvetica, sans-serif; <br />
font-size:150%;<br />
line-height:1.5em;<br />
}<br />
<br />
/* the following tag is designed for the superscript star in Connect*; */<br />
/* HTML superscript tag (sup) makes star char (&#9733;) too large and lines displace */<br />
span.superstar, span.toctext span {<br />
font-size: .6em;<br />
vertical-align: baseline;<br />
position: relative;<br />
top: -0.5em;<br />
}<br />
<br />
.pageBreak { page-break-before: always; }<br />
<br />
<br />
/* table element variations *************************************************** */<br />
<br />
/* thJustBold for a table with non-heading <th>s bold but not italicized */<br />
/* also see tr.head, below */<br />
table, table.list table.thJustBold {<br />
margin: 1em 1em 1em 0;<br />
background: #f9f9f9;<br />
border: 1px #aaa solid;<br />
border-collapse: collapse;<br />
}<br />
th, td, .list th, .list td, .thJustBold th, .thJustBold td {<br />
border: 1px #aaa solid;<br />
padding: 0.5em;<br />
text-align: left;<br />
vertical-align: top;<br />
}<br />
<br />
td.bold {<br />
font-weight: bold;<br />
}<br />
<br />
/* JAL added explicit bkgrd color to preserve it in table column *headings* in a */ <br />
/* class=thJustBold table */<br />
tr.head > th {<br />
vertical-align: bottom;<br />
white-space: nowrap;<br />
font-style: normal;<br />
background: #f2f2f2;<br />
}<br />
<br />
th, .list th {<br />
font-style: italic;<br />
background: #f2f2f2;<br />
}<br />
<br />
/* if <th> in first columns in table *content* in a class thJustBold table, make sure */ <br />
/* tr class=head for column headings */<br />
.thJustBold th {<br />
font-style: normal;<br />
background: #f2f2f2;<br />
}<br />
<br />
th var, th var.term {<br />
font-weight: bold;<br />
font-size: 100%;<br />
color: black;<br />
}<br />
<br />
table.optionTable {<br />
margin: 0;<br />
border: none;<br />
border-collapse: collapse;<br />
}<br />
<br />
table.noBorder {<br />
margin: 0;<br />
border: none;<br />
border-collapse: collapse;<br />
background-color: transparent;<br />
}<br />
<br />
table.noBorder th, table.noBorder td {<br />
border: none;<br />
}<br />
<br />
table.nested {<br />
margin: 0;<br />
border: hidden;<br />
border-collapse: collapse;<br />
}<br />
<br />
table table.nested th {<br />
border: hidden;<br />
}<br />
<br />
/* following two tweaks tighten spacing for search result list items */<br />
table.gsc-table-result {<br />
margin: 0;<br />
}<br />
<br />
table.gsc-resultsHeader {<br />
display: none;<br />
}<br />
<br />
/* for the List of MSIR and M204 message tables ************* */<br />
/* more visible vertical borders & merges msg num w/ its text */<br />
table.msgList {<br />
border: 2px #aaa solid;<br />
}<br />
<br />
.msgList th {<br />
border-right-style:none;<br />
border-left:2px solid #aaa;<br />
font-style: normal;<br />
background: #f9f9f9;<br />
}<br />
<br />
.msgList td {<br />
border-left-style:none;<br />
}<br />
<br />
/* for SoftSpy message tables ****************************** */<br />
table.message {<br />
margin: 0;<br />
border: none;<br />
border-collapse: collapse;<br />
background-color: transparent;<br />
}<br />
<br />
table.message th {<br />
border: none;<br />
font-style: normal;<br />
white-space: nowrap;<br />
}<br />
<br />
table.message td {<br />
border: none;<br />
}<br />
<br />
table.message tr:first-child th {<br />
min-width: 7em;<br />
}<br />
<br />
table.message tr:first-child td {<br />
font-weight: bold;<br />
}<br />
<br />
table.message~hr {<br />
height: 2px;<br />
margin: 1em 0;<br />
}<br />
/* ******************************************************* */<br />
<br />
code, p.output {<br />
background-color: #F0F0F9;<br />
}<br />
<br />
var {<br />
font-style: normal;<br />
font-weight: bold;<br />
font-size: 95%;<br />
color: #555;<br />
}<br />
/* tentatively removed from above: text-transform: capitalize; */ <br />
<br />
/* link-within-var */<br />
var a:link {<br />
color: #5353EF;<br />
}<br />
<br />
var a:visited {<br />
color: #5353EF;<br />
}<br />
<br />
var.syntax {<br />
font-size: 100%;<br />
color: black;<br />
}<br />
<br />
var.term {<br />
text-transform: none;<br />
font-style: italic;<br />
font-weight: normal;<br />
font-size: 100%;<br />
color: black;<br />
}<br />
<br />
/* Sirius style was italic */<br />
var.product {<br />
text-transform: none;<br />
color: black;<br />
font-style: normal;<br />
font-weight: normal;<br />
font-size: 100%;<br />
}<br />
<br />
/* JAL added 04/13 */<br />
var.book {<br />
color: black;<br />
font-style: italic;<br />
font-weight: normal;<br />
font-size: 100%;<br />
}<br />
<br />
/* darker color used when font-style was italic */<br />
/* Otherwise product links are very faint */<br />
/* var.product a { color: #002bb8; } */<br />
<br />
var.camel {<br />
text-transform: none;<br />
}<br />
<br />
/* prevent break before parens for terms like %(System in IE and Chrome */<br />
var.nobr {<br />
white-space: pre;<br />
}<br />
<br />
pre var {<br />
font-weight: bold;<br />
}<br />
<br />
.pageSubtitle {<br />
font-size:120%;<br />
color:black;<br />
font-weight: bold;<br />
}<br />
<br />
a:visited {<br />
color: #002bb8;<br />
}<br />
<br />
/* The "normal" source of the #bodyContent styles is the monobook css file on lin875 */<br />
/* make links to non-wiki targets same color as non-var wiki links */<br />
#bodyContent a.external:link,<br />
#bodyContent a.external:visited {<br />
color: #002bb8;<br />
}<br />
<br />
.showVisit a:link {<br />
color: #002bb8;<br />
}<br />
.showVisit a:visited {<br />
color: #5a3696;<br />
}<br />
.showVisit a:hover {<br />
text-decoration: underline;<br />
}<br />
.showVisit a:active {<br />
color: #faa700;<br />
}<br />
.showVisit a.new, #p-personal a.new {<br />
color: #ba0000;<br />
}<br />
.showVisit a.new:visited, #p-personal a.new:visited {<br />
color: #a55858;<br />
}<br />
<br />
/* to caption a table, as child of a "table" tag */<br />
caption {<br />
font-weight: bold;<br />
font-size: 110%;<br />
padding-bottom: .6em;<br />
}<br />
<br />
/* use for fig (image) caption; as class for "p" tag; compare with "caption" above */<br />
/* use style="width:XXpx" on "p" tag to center precisely; XX is width of graphic */<br />
/* or use style="margin-right:XXem" to ctr a non-image manually; XX often around 15 */<br />
/* then "p class=figure" before the image & append image sz in its "File:" value */<br />
/* IE wraps caption if it is wider than the image */<br />
.caption, div#content p.caption {<br />
color: black;<br />
font-size: 100%;<br />
font-weight: bold;<br />
text-align: center;<br />
line-height: 100%;<br />
margin-left: 1.6em;<br />
margin-top: 2em;<br />
margin-bottom: 1.6em;<br />
}<br />
<br />
.figure, div#content p.figure {<br />
margin-left: 1.6em;<br />
margin-top: 1.6em;<br />
margin-bottom: 2em;<br />
}<br />
<br />
<br />
/* enclose non-single-paragraph Notes with blockquote class="note". */<br />
/* Otherwise, use p class="note" */<br />
/* use noteN class to automatically get a bolded "Note:" term */<br />
.note, div#content p.note, .noteN, div#content p.noteN {<br />
margin-left: 15px;<br />
margin-right: 30px;<br />
border: none;<br />
padding: 0px;<br />
}<br />
<br />
/* auto-provision of bold text "Note:" */<br />
.noteN:before {<br />
content: "Note: ";<br />
font-weight: bold;<br />
}<br />
<br />
<br />
li *.note, td *.note, th *.note, li *.noteN, td *.noteN, th *.noteN {<br />
margin-left: 10px;<br />
margin-right: 30px;<br />
border: none;<br />
padding: 0px;<br />
}<br />
<br />
/* enclose non-single-paragraph Cautions & Warnings with blockquote class="warn". */<br />
/* Otherwise, use p class="warn" */<br />
.warn, div#content p.warn {<br />
margin-left: 20px;<br />
margin-right: 60px;<br />
margin-top: 1em;<br />
margin-bottom: 1em;<br />
text-align: justify;<br />
border-top: 1px solid #000;<br />
border-bottom: 1px solid #000;<br />
padding: 5px 5px 5px 10px;<br />
}<br />
<br />
/* used by message on Sirius $function pgs; consider .warn class (above) instead */<br />
.warning {<br />
color: #990000;<br />
font-style: italic;<br />
}<br />
<br />
.smallAndTightList {<br />
line-height: 1.3;<br />
}<br />
<br />
ul.nobul li {<br />
list-style-type: none;<br />
list-style-image: none;<br />
margin-left: 0;<br />
}<br />
<br />
ul.nobulnoindent li {<br />
list-style-type: none;<br />
list-style-image: none;<br />
margin-left: 0;<br />
text-indent: -1.5em;<br />
}<br />
<br />
/* square bullets for lower-level nested lists */<br />
ul li ul {<br />
list-style-type:square;<br />
list-style-image: none;<br />
}<br />
<br />
/* HTML for types of ordered list doesn't work in wiki, hence the following CSS */<br />
ol.low-al li {<br />
list-style-type:lower-alpha;<br />
}<br />
<br />
<br />
/** * Allow limiting of which header levels are shown in a TOC;<br />
* <div class="toclimit-3">, for instance, will limit to<br />
* showing ==headings== and ===headings=== but no further.<br />
* Used in [[Template:TOCright]]; see MediaWiki's Template:TOC page<br />
*/<br />
<br />
.toclimit-2 .toclevel-1 ul,<br />
.toclimit-3 .toclevel-2 ul,<br />
.toclimit-4 .toclevel-3 ul,<br />
.toclimit-5 .toclevel-4 ul,<br />
.toclimit-6 .toclevel-5 ul,<br />
.toclimit-7 .toclevel-6 ul {<br />
display: none; <br />
}<br />
<br />
/* selectively suppress TOC numbering -- put TOC within div class=autonum */<br />
.noautonum .tocnumber { <br />
display: none; <br />
}<br />
<br />
/* add top space to TOC */<br />
div#toc.toc {<br />
margin-top:1em;<br />
}<br />
<br />
/* squeeze footer list items a bit to fit Sirius copyright claim */<br />
#footer li {<br />
margin:0 1em;<br />
}<br />
<br />
/* use same red as Sirius PDFs */<br />
h1 {<br />
color: #660000;<br />
font-family: Arial, Helvetica, sans-serif;<br />
}<br />
<br />
h2 { <br />
font-family: Arial, Helvetica, sans-serif;<br />
color: #660000;<br />
}<br />
<br />
div#content h3 {<br />
font-size: 1.25em; <br />
}<br />
<br />
h5, h6, div#content h5, div#content h6 {<br />
font-style: italic;<br />
font-size: 92%; <br />
}<br />
<br />
tt {<br />
font-family: Consolas, "Liberation Mono", monospace;<br />
font-size:105%;<br />
}<br />
<br />
/* two cosmetic tweaks for Category page sections to remove some extra space */<br />
div#mw-subcategories h3 {<br />
padding-top:0px;<br />
margin-top:0px;<br />
}<br />
<br />
div#mw-pages h3 {<br />
padding-top:0px;<br />
}<br />
<br />
/* redirect pgs that have Category tag won't have italicized names on cat pg: */<br />
.redirect-in-category {<br />
font-style: normal;<br />
}<br />
<br />
code {<br />
font-family: Consolas,"Liberation Mono",monospace;<br />
}<br />
<br />
/** <br />
* make toggle text/icon display to the left of toggled content; <br />
* but elements after this floated element will try to flow around it,<br />
* so after the collapsible element's closing tag, specify <br close="all"><br />
*/<br />
.mw-collapsible span.mw-collapsible-toggle { float: left; }<br />
<br />
/* indent collapsed text to line-up with h2 title text */<br />
div.mw-collapsible-content {<br />
margin-left:2.32em;<br />
}<br />
<br />
<br />
/* ************************changes for Vector default ***************************** */<br />
/* hides sidebar Toolbox (so we can substitute our own set of items) */<br />
#p-tb { display:none; <br />
}<br />
<br />
/* for Monobook, widens sidebar boxes a tiny bit */<br />
.portlet {<br />
width: 11.75em;<br />
}<br />
<br />
/* for Monobook, reduces (moves right) page content area a tiny bit */<br />
/* b/c IE doesn't respond, need to snug box padding (see 'portlet pBody', below) */<br />
div#content { <br />
margin-left: 12.4em; /* not needed for Vector */<br />
}<br />
<br />
/* four tweaks to increase Vector sidebar width and make associated adjustments; */<br />
/* see also MediaWiki:Vector.css */<br />
div#mw-panel { <br />
width: 11.5em;<br />
padding-left: 0; /* was .5, which is not needed if centering vector */ <br />
left:auto; /* for Vector centering project */<br />
}<br />
<br />
#left-navigation { <br />
left: 11em;<br />
margin-left: 11.5em; /* increase of .5 for Vector centering project */<br />
}<br />
<br />
div#content.mw-body { <br />
margin-left: 11.5em; /* increase of .5 for Vector centering project */<br />
border-width: 1px; /* blue right border for Vector centering project */<br />
}<br />
<br />
div#footer ul {<br />
margin-left: 1em;<br />
}<br />
<br />
<br />
/* Monobook: for IE, lets sidebar box close on right by reducing the right padding */<br />
.portlet .pBody {<br />
padding-right: .1em;<br />
}<br />
<br />
/* Vector: used to widen sidebar boxes a tiny bit by larger padding to right */<br />
/* moving some divs undid that, so reducing it gives more room to text items */<br />
.portal .body {<br />
padding-right: .5em;<br />
} <br />
<br />
/* Monobook: rmv box from containing class of "What's New" element; tweak bot space */<br />
#p-\.C2\.A0.generated-sidebar.portlet .pBody {<br />
background-color:transparent;<br />
border:0px hidden transparent;<br />
padding-bottom: 0em; <br />
}<br />
<br />
/* for Monobook, removes bullet graphic, chngs font sz & left margin for "What's New" */<br />
#p-\.C2\.A0.generated-sidebar.portlet ul {<br />
list-style-type: none;<br />
list-style-image: none;<br />
font-style: normal;<br />
font-size: 100%;<br />
margin: .75em 0 0 .75em;<br />
} <br />
<br />
/* hides Blank list item but preserves its space so sibling list el has more cushion */ <br />
#n-Blank {<br />
visibility:hidden;<br />
} <br />
<br />
/* in Vector, tweaks "What's New" element */<br />
#mw-panel div.portal div.body ul:first-child li:only-child {<br />
line-height: 2.5em;<br />
padding-bottom: 1em;<br />
}<br />
<br />
/* tweaks list containing "What's New" element in Monobook and Vector */<br />
#p-\.C2\.A0 ul {<br />
line-height: 1em;<br />
padding-bottom: 0em;<br />
}<br />
<br />
/* makes Vector left margin for "What's New" same as list items in lower sections */<br />
/* default for this was .5; needed to precisely specify the "first" and "persistent" */<br />
#mw-panel.noprint.collapsible-nav .portal.first.persistent div.body {<br />
margin-left: 1.25em; /* this gets overridden to .5 */<br />
} <br />
<br />
/* -- Vector centering proj (also see few commented tweaks above & in Vector.css) -- */<br />
div#center {<br />
margin: auto;<br />
max-width: 60em;<br />
}<br />
<br />
div#mw-head {<br />
right: auto;<br />
max-width: 60em;<br />
background-image: none;<br />
background-color: transparent;<br />
}<br />
<br />
div#p-logo {<br />
left: 0; /* was .5, not needed if centering vector (Vector.css overrides it) */ <br />
} /* see also mw-panel chg above */<br />
<br />
/* move top tab text up a bit to make white space above it less noticeable */<br />
div.vectorTabs ul li {<br />
line-height: .6em; <br />
}<br />
<br />
/* next 2 tweaks to snug right-nav els to content edge xcpt for 1px */<br />
div#p-personal {<br />
right: 1px;<br />
}<br />
<br />
div#p-search {<br />
margin-right: 1px;<br />
}<br />
<br />
div#mw-page-base {<br />
background-image: none;<br />
background-color: transparent;<br />
}<br />
<br />
/* ----------------------------------------------- */<br />
<br />
/* ****************************************************************************** */</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=For_Record_Number_statement&diff=115038For Record Number statement2018-04-27T17:01:54Z<p>Admin: Admin moved page FOR RECORD NUMBER statement to For Record Number statement without leaving a redirect: mixed case for SOUL stmts</p>
<hr />
<div>#REDIRECT [[Record loops#For Record Number processing]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Data_maintenance&diff=115014Data maintenance2018-04-25T21:00:58Z<p>Admin: /* Change statement */ link repair</p>
<hr />
<div><div class="toclimit-3"><br />
<br />
==Overview==<br />
<p><br />
<var class="product">Model&nbsp;204</var> data are maintained and updated with a variety of [[SOUL]] statements. This topic describes data maintenance statements and special conditions regarding their usage. </p><br />
<br />
===Data maintenance statements===<br />
<p><br />
Use the following statements to perform basic data maintenance (record and field additions and updates):</p><br />
<table><br />
<tr class="head"><br />
<th>Statement </th><br />
<th> Action</th><br />
</tr><br />
<br />
<tr><br />
<td><var>Add</var> </td><br />
<td>Place a new field-value pair on a record.</td><br />
</tr><br />
<br />
<tr><br />
<td><var>Change</var> </td><br />
<td>Alter the value of fields in a record.</td><br />
</tr><br />
<br />
<tr><br />
<td><var>Delete</var> </td><br />
<td>Remove fields from a record.</td><br />
</tr><br />
<br />
<tr><br />
<td><var>Delete Record</var> </td><br />
<td>Remove a record from a <var class="product">Model&nbsp;204</var> file; this statement reclaims space occupied by the deleted record.</td><br />
</tr><br />
<br />
<tr><br />
<td><var>Delete Records</var> </td><br />
<td>Remove sets of records from a <var class="product">Model&nbsp;204</var> file; this statement executes faster than the <var>Delete Record</var> statement but does not reclaim the space occupied by the deleted records.</td><br />
</tr><br />
<br />
<tr><br />
<td nowrap><var>File Records Under</var> </td><br />
<td>Save retrieved or collected sets of record numbers for reference in later requests. </td><br />
</tr><br />
<br />
<tr><br />
<td><var>Store Record</var> </td><br />
<td>Put a new record into a <var class="product">Model&nbsp;204</var> file.</td><br />
</tr><br />
<br />
<tr><br />
<td><var>Update Record </var></td><br />
<td>Perform a series of field-level updates in a single call. This statement is intended for use with <var class="product">Parallel Query Option/204.</var></td><br />
</tr><br />
</table><br />
<br />
====Example data====<br />
<p><br />
Each statement is discussed separately in the sections that follow. To illustrate their usage, assume that the following two records have been stored:</p><br />
<p class="code">VIN = A99999998E VIN = X99999999Z<br />
MAKE = FORD MAKE = FORD<br />
COLOR = GREEN COLOR = RED<br />
YEAR = 88 YEAR = 04<br />
MODEL = FOCUS MODEL = MUSTANG<br />
</p><br />
<br />
===Using For Each Record loops===<br />
<p><br />
The SOUL data maintenance statements handle one record at a time, therefore the data maintenance statements are always part of a <var>For Each Record</var> loop. The data maintenance may involve a field-value pair for the field.</p><br />
<br />
==ADD statement==<br />
<p><br />
The <var>ADD</var> statement adds a new occurrence of a field and/or value to a record.</p><br />
<br />
====Syntax====<br />
<p><br />
The basic format of the ADD statement is:</p><br />
<p class="syntax">ADD <span class="term">fieldname</span> = {<span class="term">value</span> <span class="squareb">|</span> (<span class="term">expression</span>)}<br />
</p><br />
<p><br />
Where:</p><br />
<ul><br />
<li><span class="term">fieldname</span> identifies the field in a record.</li><br />
<br />
<li><span class="term">value</span> specifies the value you want to store.</li><br />
<br />
<li>(<span class="term">expression</span>) can be used in place of value to specify the resolved value at the time of evaluation. (<span class="term">expression</span>) can be a function call, string concatenation, arithmetic operation, User Language construct, or Boolean expression. The expression must be enclosed in parentheses to invoke the expression compiler; otherwise the value will be treated as a literal string.</li><br />
</ul><br />
<br />
<p class="note"><b>Note:</b> For Large Object data in <var class="product">Model&nbsp;204</var> V7.5 and later, a file must be defined with the <var>[[FILEORG parameter|FILEORG]]</var> X'100' bit in order to use the above syntax. With LOB fields, the assigned value is typically held in a <var>[[Longstrings|Longstring]]</var> variable. [[Large Object field processing for non-FILEORG X'100' files|In non-FILEORG X'100' files, a special syntax must be used to ADD a LOB field.]]</p><br />
<br />
====Example====<br />
<p><br />
Referring to the two sample stored records (see [[#Data used in examples in this topic|Data used in examples in this topic]]), this request:</p><br />
<p class="code">BEGIN<br />
FIND.RECS: FIND ALL RECORDS FOR WHICH<br />
MAKE = FORD<br />
BODY IS NOT PRESENT<br />
END FIND<br />
FOR EACH RECORD IN FIND.RECS<br />
ADD BODY = 2DR<br />
END FOR<br />
END<br />
</p><br />
<p><br />
would change the records to:</p><br />
<p class="code">VIN = A99999998E VIN = X99999999Z<br />
MAKE = FORD MAKE = FORD<br />
COLOR = GREEN COLOR = RED<br />
BODY = 2DR BODY = 2DR<br />
YEAR = 98 YEAR = 04<br />
MODEL = FOCUS MODEL = MUSTANG<br />
</p><br />
<br />
====Usage====<br />
<ul><br />
<li>The <var>ADD</var> statement places an additional occurrence of a field-value pair on the record.</li><br />
<br />
<li>You can use the <var>ADD</var> statement to add any field to a record except for a sort or hash key field. You can use this statement only within a <var>FOR EACH RECORD</var> loop.</li><br />
<br />
<li>The <var>ADD</var> statement is supported in remote file and scattered group contexts.</li><br />
<br />
<li>To use the <var>ADD</var> statement with multiply occurring fields, see the [[Processing multiply occurring fields and field groups#ADD statement|ADD statement for multiply occurring fields]]. </li><br />
<br />
<li>To add a field whose value you do not explicitly specify, see [[#Using VALUE IN to reference a NOTE value|Using VALUE IN to reference a NOTE value]], below. </li><br />
<br />
<li>For Large Object data in non-[[FILEORG parameter|FILEORG X'100']] files, a compiler error is issued for <var>ADD</var> (and <var>STORE</var>) statements if the context to the right of the equal sign (<tt>=</tt>) is not a <var>BUFFER</var> reference:<br />
<p class="code">M204.0037: INVALID SYNTAX<br />
</p></li><br />
</ul><br />
<br />
==Change statement==<br />
<p><br />
The <var>Change</var> statement alters a record by adding a field and value pair, or altering the value of an existing field within a record. </p><br />
<br />
====Syntax====<br />
<p><br />
The basic format of the <var>Change</var> statement is: </p><br />
{{Template:Change fieldname statement syntax (basic)}}<br />
<p><br />
Where:</p><br />
<ul><br />
<li><var class="term">fieldname</var> specifies the name of the field to add to the record, or identify the field where the value is changed. </li><br />
<br />
<li>(<var class="term">subscript</var>) specifies an ordinal number that is used to select a particular occurrence of a multiply occurring field. See the discussion in [[Processing multiply occurring fields and field groups#Subscripts|Subscripts]]. </li><br />
<br />
<li><var class="term">value</var> is required only if the field has the <var>INVISIBLE</var> attribute. See the discussion of the [[Field attributes#INVISIBLE attribute|INVISIBLE attribute]]. </li><br />
<br />
<li><var class="term">newvalue</var> specifies the value that overwrites the existing value for the field. </li><br />
<br />
<li>(<var class="term">expression</var>) is resolved by the expression compiler and overwrites the existing value for the field. (<var class="term">expression</var>) can be a function call, string concatenation, arithmetic operation, SOUL construct, or Boolean expression. The expression must be enclosed in parentheses to invoke the expression compiler; otherwise the value will be treated as a literal string. </li><br />
</ul> <br />
<br />
====Usage====<br />
<ul><br />
<li>You can use the <var>Change</var> statement to change any field in a record except for a sort or hash key field. </li><br />
<br />
<li>You can use this statement only within a <var>For Each Record</var> loop. </li><br />
<br />
<li>The <var>Change</var> statement is supported in remote file and scattered group contexts.</li><br />
<br />
<li>If a <var>Change</var> statement is applied to a record that does not contain the field to be changed, the specified field name and value are added to the record. </li><br />
<br />
<li>To use the <var>Change</var> statement with multiply occurring fields, see the [[Processing multiply occurring fields and field groups#Change statement|Change statement for multiply occurring fields]]. </li><br />
<br />
<li>To use the <var>Change</var> statement with fields containing Large Object data, where the assigned value is typically held in a <var>[[Longstrings|Longstring]]</var> variable:<br />
<ul><br />
<li>Use the syntax above <em>only</em> for a <var class="product">Model&nbsp;204</var> V7.5 and later file that is defined with the <var>[[FILEORG parameter|FILEORG]]</var> X'100' bit. </li><br />
<br />
<li>For pre-7.5 or non-FILEORG X'100' files, use the [[Large Object field processing for non-FILEORG X'100' files|special syntax for changing a LOB field.]] </li><br />
</ul></li><br />
<br />
<li>To change a field whose value you do not explicitly specify, see [[#Using VALUE IN to reference a NOTE value|Using VALUE IN to reference a NOTE value]], below. </li><br />
</ul><br />
<br />
==DELETE statement==<br />
<p><br />
The <var>DELETE</var> statement removes fields from a record. </p><br />
<br />
====Syntax====<br />
<p><br />
The format of the <var>DELETE</var> statement is:</p><br />
<p class="syntax">DELETE <span class="term">fieldname</span> [<b></b>= <span class="term">value</span> | (<span class="term">expression</span>)]<br />
</p><br />
<p><br />
Where:</p><br />
<ul><br />
<li><var class="term">fieldname</var> specifies the name of the field to remove from the record.</li><br />
<br />
<li><var class="term">value</var> is required only if the field has the <var>INVISIBLE</var> attribute. (See the discussion in [[Field attributes]].) </li><br />
<br />
<li>(<var class="term">expression</var>) can be used in place of value to specify the resolved value at the time of evaluation. (<var class="term">expression</var>) can be a function call, string concatenation, arithmetic operation, SOUL construct, or Boolean expression. The expression must be enclosed in parentheses to invoke the expression compiler; otherwise the value will be treated as a literal string.</li><br />
</ul><br />
<br />
====Example====<br />
<p><br />
This request directs <var class="product">Model&nbsp;204</var> to remove the field <code>BODY</code> from the records retrieved by the <code>FIND.RECS</code> statement:</p><br />
<p class="code">BEGIN<br />
FIND.RECS: FIND ALL RECORDS FOR WHICH<br />
VIN = A99999998E OR X99999999Z<br />
END FIND<br />
FOR EACH RECORD IN FIND.RECS<br />
DELETE BODY<br />
END FOR<br />
END<br />
</p><br />
<p><br />
The records then appear as:</p><br />
<p class="output">VIN = A99999998E VIN = X99999999Z<br />
MAKE = FORD MAKE = FORD<br />
COLOR = BLUE COLOR = BLUE<br />
YEAR = 98 YEAR = 04<br />
MODEL = FOCUS MODEL = MUSTANG<br />
</p><br />
<br />
====Usage====<br />
<ul><br />
<li>You can use the <var>DELETE <i>fieldname</i></var> statement on any field in a record except for a sort or hash key field. This statement can be used only within a <var>FOR EACH RECORD</var> loop. </li><br />
<br />
<li>If the <var>DELETE <i>fieldname</i></var> statement is applied to a record that does not contain the field to be deleted, no action is taken on that record. </li><br />
<br />
<li>The <var>DELETE <i>fieldname</i></var> statement is supported in remote file and scattered group contexts.</li><br />
<br />
<li>The <var>DELETE <i>fieldname</i></var> statement supports Large Object data. Processing this statement frees the Table B and Table E data.</li><br />
<br />
<li>To use with multiply occurring fields, see [[Processing multiply occurring fields and field groups#DELETE statement|Deleting multiply occurring fields]]. </li><br />
<br />
<li>To use with field groups, see [[Processing multiply occurring fields and field groups#Deleting a field group|Deleting field groups]]. </li><br />
<br />
<li>For information about space recovered from deletions and about attempting to delete missing records, see [[#Deleting fields and records|Deleting fields and records]], below.</li><br />
</ul><br />
<br />
==DELETE RECORD statement==<br />
<p><br />
The <var>DELETE RECORD</var> statement removes a record or sets of records from a <var class="product">Model&nbsp;204</var> file. </p><br />
<br />
===Syntax===<br />
<p><br />
The format of the <var>DELETE RECORD</var> statement is:</p><br />
<p class="syntax">DELETE RECORD<br />
</p><br />
<br />
===Example===<br />
<p><br />
This request deletes all records found by the <var>FIND</var> statement: </p><br />
<p class="code">BEGIN<br />
FIND.RECS: FIND ALL RECORDS FOR WHICH<br />
MAKE = FORD<br />
YEAR = 96<br />
END FIND<br />
FOR EACH RECORD IN FIND.RECS<br />
DELETE RECORD<br />
END FOR<br />
END<br />
</p><br />
<br />
===Usage===<br />
<ul><br />
<li>When you delete records with the <var>DELETE RECORD</var> statement, the space those records occupy may be reclaimed depending on the file order. For more information on reclaiming space, refer to [[#Reused space|Reused space]]. </li><br />
<br />
<li>You can use this statement only inside a <var>FOR EACH RECORD</var> loop.</li><br />
<br />
<li>The <var>DELETE RECORD</var> statement is supported in remote file and scattered group contexts. </li><br />
<br />
<li>For information about space recovered from deletions and about attempting to delete missing records, see [[#Deleting fields and records|Deleting fields and records]], below.</li><br />
</ul><br />
<br />
====Limitation of the date-time stamp feature deleting records====<br />
<p><br />
The [[Adding a date-time stamp field#Overview of the date-time stamp feature|date-time stamp feature]] does not include support for <var>DELETE RECORD</var> or <var>DELETE RECORDS</var> processing. <var>DELETE RECORD</var> or <var>DELETE RECORDS</var> processing must be handled by your application software.</p><br />
<p><br />
As well, you can use logical delete techniques. However, in all forms of deleting records, it is your responsibility to maintain a log of record deletions, if you want one.</p><br />
<br />
==DELETE ALL RECORDS statement==<br />
<p><br />
The <var>DELETE ALL RECORDS</var> statement deletes sets of records from a <var class="product">Model&nbsp;204</var> file. </p><br />
<br />
===Syntax===<br />
<p><br />
The forms of this statement are:</p><br />
<p class="syntax">DELETE [ALL] RECORDS IN <span class="term">label</span><br />
<br />
DELETE [ALL] RECORDS ON [LIST] <span class="term">listname</span><br />
</p><br />
<ul><br />
<li><var>DELETE ALL RECORDS IN</var> deletes a set of records located by a <var>FIND</var> statement. </li><br />
<br />
<li><var>DELETE ALL RECORDS ON LIST</var> deletes the set of records on the named list from the file. <br />
</li><br />
</ul><br />
<br />
===Example===<br />
<p><br />
This request deletes the set of records located by the <var>FIND</var> statement:</p><br />
<p class="code">BEGIN<br />
FIND.RECS: FIND ALL RECORDS FOR WHICH<br />
MAKE = FORD<br />
YEAR = 00<br />
END FIND<br />
DELETE ALL RECORDS IN FIND.RECS<br />
END<br />
</p><br />
<br />
===Usage===<br />
<ul><br />
<li>The <var>DELETE ALL RECORDS</var> statement initiates fewer internal operations and therefore executes faster than the <var>DELETE RECORD</var> statement. However, use the <var>DELETE RECORD</var> statement rather than <var>DELETE ALL RECORDS</var> for records with <var>ORDERED</var> or <var>UNIQUE</var> fields, to ensure that values in the Ordered Index accurately reflect the contents of the data stored in Table B.<br />
<p><br />
In addition, when records are deleted with <var>DELETE ALL RECORDS IN</var>, the space they occupy is not reclaimed. When it is desirable to reclaim space to expand existing records or to insert new records, use the <var>DELETE RECORD</var> statement. </p></li><br />
<br />
<li>The <var>DELETE ALL RECORDS</var> statement is supported in remote file and scattered group contexts.</li><br />
<br />
<li>For information about space recovered from deletions and about attempting to delete missing records, see [[#Deleting fields and records|Deleting fields and records]], below.</li><br />
</ul><br />
<br />
==Deleting fields and records==<br />
<p><br />
This section expands on the detail of use for the <var>DELETE</var> statements. Some general issues related to deleting fields and records are presented.</p><br />
<br />
===Reused space===<br />
<p><br />
Space recovered from both record and field deletions is always used to expand existing records that are near the deletions, regardless of which file option is selected.<br />
<var class="product">Model&nbsp;204</var> inserts new records in space recovered from deleted records only on unordered or hash files, or on sort files for which the <var>Reuse Record Number</var> option of the <var>[[FILEORG parameter|FILEORG]]</var> parameter is set active. </p><br />
<p><br />
If the <var>Reuse Record Number</var> option is active for an unordered, hash, or sort file, you must explicitly delete any <var>INVISIBLE</var> fields associated with a record in the file when deleting the record itself. If an <var>INVISIBLE</var> field is not deleted, it becomes part of any new record that is put into the old record's space. </p><br />
<br />
===Deleting from a record list===<br />
<p><br />
Error messages might be generated when a <var>FOR EACH RECORD</var> loop is performed on a list of records from which some of the records have been deleted from the file. For example:</p><br />
<p class="code">BEGIN<br />
<b></b>*<br />
<b></b>* FIND ALL STATE CONTROL RECORDS<br />
<b></b>*<br />
STATES: FIND ALL RECORDS FOR WHICH<br />
REC = STATE<br />
END FIND<br />
PLACE RECORDS IN STATES ON LIST FOUND<br />
<b></b>*<br />
<b></b>* EXCLUDE MASS. AND N.H. BECAUSE<br />
<b></b>* THEIR SURCHARGE RATE HAS NOT CHANGED<br />
<b></b>*<br />
REMOVE: FIND ALL RECORDS ON LIST FOUND FOR WHICH<br />
STATE CODE = MA OR NH<br />
END FIND<br />
<br />
FOR EACH RECORD IN REMOVE<br />
DELETE RECORD<br />
END FOR<br />
<b></b>*<br />
<b></b>* CHANGE SURCHARGE RATE FOR ALL OTHER STATES<br />
<b></b>*<br />
SURCHARGE: FOR EACH RECORD ON LIST FOUND<br />
CHANGE SURCHARGE RATE TO .50<br />
END FOR<br />
END<br />
</p><br />
<p><br />
This request would produce these messages:</p><br />
<p class="code"><b></b>*** M204.1266: NONEXISTENT RECORD REFERENCED - 23 IN FILE INSURE<br />
<b></b>*** M204.1266: NONEXISTENT RECORD REFERENCED - 24 IN FILE INSURE<br />
</p><br />
<p><br />
Depending upon the intent of the request, these messages may or may not indicate an error. </p><br />
<br />
==FILE RECORDS statement==<br />
<p><br />
The <var>FILE RECORDS</var> statement files a set of records that were retrieved by a <var>FIND</var> statement or that were collected on a list. You can reference the set of records in later requests. </p><br />
<br />
===Syntax===<br />
<p><br />
The forms of this statement are:</p><br />
<p class="syntax">FILE RECORDS IN <span class="term">label</span> UNDER <span class="term">fieldname</span> = <span class="term">value</span><br />
<br />
FILE RECORDS IN <span class="term">label</span> UNDER <span class="term">fieldname</span> = (<span class="term">expression</span>) <br />
<br />
FILE RECORDS ON [LIST] <span class="term">listname</span> UNDER <span class="term">fieldname</span> = <span class="term">value</span><br />
</p><br />
<br />
===Usage===<br />
<ul><br />
<li>The <var>FILE RECORDS</var> statement adds one of these pairs to the specified records:<br />
<p class="code"><i>fieldname</i> = <i>value</i><br />
<br />
<i>fieldname</i> = (<i>expression</i>)<br />
</p></li><br />
<br />
<li>The <var>FILE RECORDS</var> statement is supported in remote file and scattered group contexts.</li><br />
<br />
<li>The field used in a <var>FILE RECORDS</var> statement must have the <var>INVISIBLE KEY</var> or <var>INVISIBLE ORDERED</var> field attributes. Refer to [[Field attributes]] for more information. <br />
<p><br />
In addition, the <var class="term">fieldname</var> = <var class="term">value</var> pair should be unique in the file. If the pair has appeared previously in other records, either by explicit field creation or by a previous <var>FILE RECORDS</var> statement, inconsistencies in the file can occur. The <var>FILE RECORDS</var> statement creates new index entries for the<br />
<var class="term">fieldname</var> = <var class="term">value</var> pair, eliminating existing references.</p><br />
<p class="note"><b>Note:</b> The index update generated by a <var>FILE RECORDS UNDER</var> statement is never deferred.</p></li><br />
<br />
<li>The <var class="term">expression</var> in the syntax above is enclosed in parentheses and is one of following expression types: function call, string concatenation, arithmetic operation, SOUL construct, or Boolean expression.</li><br />
</ul><br />
<br />
====Example of using an expression====<br />
<p class="code">B<br />
%REC IS STRING LEN 3<br />
%CT IS FLOAT<br />
%VAL1 IS FLOAT<br />
%VAL2 IS FLOAT<br />
%REC = 'REC'<br />
FOR %CT FROM 1 TO 10<br />
IN EXPRESS STORE RECORD<br />
ORD1 = (%REC WITH %CT)<br />
ORD2 = (%CT * 2)<br />
ORD4 = (%CT * 4)<br />
END STORE<br />
COMMIT<br />
FD1:<br />
IN EXPRESS FD ORD1 EQ VALUE(%REC WITH %CT)<br />
END FIND<br />
FR FD1<br />
CHANGE ORD2 TO (%CT * 2.1)<br />
ADD ORD3 = (%CT * 3)<br />
CHANGE ORD4 = (%CT * 4 ) TO (%CT * 4.1)<br />
DELETE ORD3 = (%CT * 3)<br />
INSERT ORD4 = (%CT * 5)<br />
END FOR<br />
FILE RECORDS IN FD1 UNDER INVORD5 = (%REC WITH %CT)<br />
END FOR<br />
PRINT 'FRV1'<br />
FRV1:<br />
IN EXPRESS FRV INVORD5<br />
FD2:<br />
IN EXPRESS FD INVORD5 = VALUE IN FRV1<br />
END FIND<br />
CT2:<br />
CT FD2<br />
PRINT VALUE IN FRV1 AND COUNT IN CT2<br />
END FOR<br />
END<br />
</p><br />
<br />
====Locating filed record sets====<br />
<p><br />
<var>FIND</var> statements in later requests can locate the filed set of records by using the <var class="term">fieldname</var> = <var class="term">value</var> pair as the retrieval condition. For example, if a set of records were filed with the statement:</p><br />
<p class="code">SAVE.RECS: FILE RECORDS IN FIND.RECS UNDER SAVE = 1<br />
</p><br />
<p><br />
Then to locate the records again, you use the following statement in the same request or in a later one:</p><br />
<p class="code">GET.RECS: FIND ALL RECORDS FOR WHICH SAVE = 1<br />
</p><br />
<br />
====Using lists for filed record sets====<br />
<p><br />
Two sets of records retrieved by different <var>FIND</var> statements can be filed together under the same <var class="term">fieldname</var> = <var class="term">value</var> pair only if both sets are first placed on a list, and then the list is filed by one statement, as in the following: </p><br />
<p class="code">BEGIN<br />
FIND.RECS: FIND ALL RECORDS FOR WHICH<br />
STATE = VIRGINIA<br />
AGENT = DOYLE<br />
END FIND<br />
SAVE.DOYLE: PLACE RECORDS IN FIND.RECS ON LIST COMPLIST<br />
FIND.T3S: FIND ALL RECORDS FOR WHICH<br />
STATE = VIRGINIA<br />
INCIDENT = T3<br />
END FIND<br />
PLACE RECORDS IN FIND.T3S ON LIST COMPLIST<br />
SAVE.LIST: FILE RECORDS ON LIST COMPLIST UNDER SAVE = T3S<br />
END<br />
</p><br />
<p><br />
If the <code>SAVE.DOYLE</code> statement were replaced with:</p><br />
<p class="code">SAVE.DOYLE: FILE RECORDS IN FIND.RECS UNDER SAVE = T3S<br />
</p><br />
<p><br />
the original references to <code>SAVE = T3S</code> would be lost as soon as the <code>SAVE.LIST</code> was executed. Thus, a second use of the same <var class="term">fieldname</var> = <var class="term">value</var> pair replaces the previous one.</p><br />
<br />
====Simulating the FILE RECORDS UNDER statement====<br />
<p><br />
You can simulate the <var>FILE RECORDS</var> statement by explicitly adding a <var class="term">fieldname</var> = <var class="term">value</var> pair to a set of records. For example, if the <code>SAVE.LIST</code> statement in the previous example is replaced by:</p><br />
<p class="code">SAVE.LIST: FOR EACH RECORD ON LIST COMPLIST<br />
ADD SAVE = T3S<br />
END FOR<br />
</p><br />
<p><br />
Then the index references to existing records that contain that <var class="term">fieldname</var> = <var class="term">value</var> pair are not invalidated. You are responsible for deleting such references, if deletion is desired. </p><br />
<br />
==<b id="storec"></b>STORE RECORD statement==<br />
<p><br />
The <var>STORE RECORD</var> statement is used to add new records to a <var class="product">Model&nbsp;204</var> file. The <var class="term">fieldname</var>=<var class="term">value</var> pairs that constitute the new record must follow the <var>STORE RECORD</var> statement, one to a line, and must not be labeled. </p><br />
<br />
===Syntax===<br />
<p><br />
The format of the <var>STORE RECORD</var> statement is: </p><br />
<p class="syntax">[<span class="term">label:</span>] [IN <span class="term">filename</span>] STORE RECORD<br />
<span class="term">fieldname</span> =[<span class="term">value1</span> <span class="squareb">|</span> (<span class="term">expression1</span>)]<br />
[<span class="term">fieldname2</span>=[<span class="term">value2</span> <span class="squareb">|</span> (<span class="term">expression2</span>)]]<br />
...<br />
[THEN CONTINUE<br />
<span class="term">statement</span><br />
<span class="term">statement</span><br />
...]<br />
END STORE [<span class="term">label</span>]<br />
</p><br />
<p><br />
Where:</p><br />
<ul><br />
<li>(<var class="term">expression</var>) can be a function call, string concatenation, arithmetic operation, SOUL construct, or Boolean expression. The expression must be enclosed in parentheses to invoke the expression compiler; otherwise the value will be treated as a literal string.</li><br />
<br />
<li><var>THEN CONTINUE</var> maintains the record context of the <var>STORE RECORD</var> statement, while allowing additional work to happen on the record. <var>THEN CONTINUE</var> is useful for adding variable numbers of multiply occurring fields, and it is <em>required syntax</em> for adding fieldgroups inside a <var>STORE</var> statement.</li><br />
</ul><br />
<br />
===Examples===<br />
<p class="code">BEGIN<br />
STORE RECORD<br />
NAME = JEAN ANDERSON<br />
SALARY = 30000<br />
POSITION = CHEMIST<br />
END STORE<br />
END<br />
</p><br />
<br />
<b>Using the THEN CONTINUE statement</b><br />
<p class="code">%COLOR = 'BLUE'<br />
STORE RECORD<br />
MODEL = %MODEL<br />
THEN CONTINUE<br />
FR WHERE RECTYPE = 'TABLE' AND COLOR = %COLOR<br />
%CODE = COLOR_CODE<br />
END FOR<br />
ADD COLOR_CODE=%CODE<br />
PAI<br />
END STORE<br />
</p><br />
<br />
===Usage===<br />
<ul><br />
<li>Use an <var>END STORE</var> statement or another label to end the <var>STORE RECORD</var> statement. Do not end a <var>STORE RECORD</var> statement with an <var>END BLOCK</var> statement. </li><br />
<br />
<li>This form of the <var>STORE RECORD</var> statement is used to add new records to any file that does not have the sorted or hashed option.</li><br />
<br />
<li>The <var>STORE RECORD</var> statement is supported in remote file and scattered group contexts.</li><br />
<br />
<li>To store a field whose value you do not explicitly specify, see [[#Using VALUE IN to reference a NOTE value|Using VALUE IN to reference a NOTE value]], below. </li><br />
<br />
<li>The <var>THEN CONTINUE</var> statement allows for the conditional building of a <var class="product">Model&nbsp;204</var> record. You can use any intervening statements after <var>THEN CONTINUE</var> and before <var>END STORE</var>.<br />
<p><br />
The statements following the <var>THEN CONTINUE</var> statement of the <var>STORE RECORD</var> block operate as if they were coded within a <var>FRN $Currec</var> block, which immediately follows the <var>END STORE</var> statement. This is easier for coding because you do not need to repeat the file specification of the <var>STORE RECORD</var> statement. It is also more efficient because an actual <var>FRN</var> statement is not necessary.</p></li><br />
<br />
<li>As of version 7.4, the maximum number of fields that you can add in a STORE RECORD statement using a subscripted variable is 127. If you are currently adding more than 127 fields in this way, the following message will be issued: <br /><br />
<code>M204.2840: STATEMENT HAS TOO MANY INTERMEDIATE RESULTS</code><br />
<br />
<p>The best solution is to recode your application to add 127 or fewer fields initially, followed by a record update statement to add the additional fields.</p><br />
<br />
<p>Example:</p><br />
<p class="code">store:<br />
store record<br />
fieldx=%array(1)<br />
fieldx=%array(2)<br />
...<br />
fieldx=%array(127)<br />
end store<br />
<br />
frn in store<br />
for %x from 128 to 999<br />
add fieldx = %array(%x)<br />
end for<br />
end for</p><br />
</li><br />
</ul><br />
<br />
<div id="Lob fields"></div> <br />
====Large Object storage====<br />
<!--Caution: <div> above--><br />
<p><br />
[[Field design#BLOB, CLOB, and MINLOBE attributes|Binary Large Objects]] &mdash; fields defined with a <var>BLOB</var> or <var>CLOB</var> attribute (often referred to collectively as LOBs) &mdash; are stored in Table E, and they can hold content longer than the 255 limit of regular <var class="product">Model&nbsp;204</var> fields. They are useful for holding blocks of text, images, documents, etc. </p><br />
<br />
<p class="note"><b>Note:</b> Prior to the <var class="product">Model&nbsp;204</var> version 7.5 introduction of the [[FILEORG parameter|FILEORG X'100']] bit, LOB fields required a special <var>STORE</var> syntax referencing the "universal buffer." This pre-V7.5 syntax is documented in [[Large Object field processing for non-FILEORG X'100' files]].</p><br />
<p><br />
As of <var class="product">Model&nbsp;204</var> V7.5, LOB fields can be stored using normal <var>STORE</var> syntax, typically with a [[Longstrings|Longstring]] variable holding the content:</p><br />
<br />
<p class="code">B<br />
%REC IS STRING LEN 3<br />
%CT IS FLOAT<br />
%VAL1 IS FLOAT<br />
%VAL2 IS FLOAT<br />
%REC = 'REC'<br />
FOR %CT FROM 1 TO 10<br />
IN EXPRESS STORE RECORD<br />
ORD1 = (%REC WITH %CT)<br />
ORD2 = (%CT * 2)<br />
ORD4 = (%CT * 4)<br />
END STORE<br />
COMMIT<br />
FD1:<br />
IN EXPRESS FD ORD1 EQ VALUE(%REC WITH %CT)<br />
END FIND<br />
FR FD1<br />
CHANGE ORD2 TO (%CT * 2.1)<br />
ADD ORD3 = (%CT * 3)<br />
CHANGE ORD4 = (%CT * 4 ) TO (%CT * 4.1)<br />
DELETE ORD3 = (%CT * 3)<br />
INSERT ORD4 = (%CT * 5)<br />
END FOR<br />
END FOR<br />
END<br />
</p><br />
<p><br />
When you store an instance of a Large Object field, the value of the data is stored in the file's Table E. Additionally, a LOB descriptor containing a pointer to the value in Table E, as well as other items, are stored in the record data in a Table B entry. The LOB descriptor is 27 bytes in length, plus the 1-byte length and 2-byte field code that apply to all fields &mdash; unless the field is preallocated.<br />
See [[File Load utility#Building a Large Object descriptor|Building a Large Object descriptor]]<br />
for a description of how to build a Large Object data descriptor.</p><br />
<p><br />
The following compiler error is issued when the right side of the equal sign is expected to contain a <var>BUFFER</var> expression and it does not.</p><br />
<p class="code">M204.0037: INVALID SYNTAX<br />
</p><br />
<br />
<br />
====Sort or hash key files====<br />
<p><br />
If you are adding a record to a file that has the sort or hash option, the sort or hash key value follows the <var>STORE RECORD</var> on the same line, as shown below: </p><br />
<p class="syntax">STORE RECORD [<span class="term">sort-or-hash-key-value</span>]<br />
</p><br />
<p><br />
The sort or hash key must be provided if the <var>FILEORG</var> parameter was set to indicate that the sort or hash key is required in every record. </p><br />
<p><br />
For example, the request to store a record in a file that requires the vehicle identification number as the sort key can be written:</p><br />
<p class="code">BEGIN<br />
STORE RECORD A99999998E<br />
MAKE = FORD<br />
COLOR = GREEN<br />
YEAR = 98<br />
MODEL = FOCUS<br />
END STORE<br />
END<br />
</p><br />
<p><br />
When this record is stored, the field <code>VIN = A99999998E</code> is added to it. </p><br />
<p><br />
You can also specify the sort or hash key as an expression:</p><br />
<br />
<p class="syntax">IN TEST1 STORE RECORD (<span class="term">expression</span>)<br />
...<br />
END STORE<br />
</p><br />
<p><br />
Where: </p><br />
<p><br />
(<var class="term">expression</var>) is the sort or hash key. (<var class="term">expression</var>) can be a function call, string concatenation, arithmetic operation, User Language construct, or Boolean expression. The expression must be enclosed in parentheses to invoke the expression compiler; otherwise the value will be treated as a literal string.</p><br />
<br />
====Files with a UNIQUE field====<br />
<p><br />
If a record is added to the file that has a <var>UNIQUE</var> field, and a uniqueness conflict is detected during the <var>STORE RECORD</var> processing, the partially stored record is backed out. For files without the <var>Reuse Record Number</var> (<var>RRN</var>) option, this results in the use of a record number which cannot be reclaimed. </p><br />
<br />
====IN GROUP MEMBER clause====<br />
<p><br />
You can use the <var>IN GROUP MEMBER</var> clause to restrict the <var>STORE RECORD</var> statement to one member file in a group context. See [[Files, groups, and reference context#IN GROUP MEMBER clause|IN GROUP MEMBER clause]] for more information.</p><br />
<br />
====FIND ALL VALUES options====<br />
<p><br />
Like other <var>FIND</var> statements, you can specify a range of values for the <var>FIND ALL VALUES</var> statement by using the <var>FROM</var> and <var>TO</var> clauses. </p><br />
<p><br />
In addition, you can select values based upon a pattern by using the <var>LIKE</var> clause. </p><br />
<br />
====Storing field groups (FIELDGROUP)====<br />
<p><br />
Introduced with <var class="product">Model&nbsp;204</var> version 7.5, field groups add a formalized internal structure for sets of repeating fields &mdash; for instance, a set of children and their birthdays would automatically associate the second birthday with the second child. With regular repeating fields, the programmer must be very careful: If, for instance, an occurrence of a birthday field is deleted, the correct occurrence of the associated child must also be deleted, or else the repeating values become out-of-sync. Field groups take care of this housekeeping by associating a set of fields with an internal field group ID.</p><br />
<p><br />
Field groups can be added, changed, and deleted on a record after the record is created, but storing them on the initial <var>STORE RECORD</var> statement <em>requires</em> the use of <var>THEN CONTINUE</var>. The following example demonstrates this, both for fieldgroups and for <em>nested fieldgroups</em> (a fieldgroup contained inside another fieldgroup). Take this set of field definitions:</p><br />
<br />
<p class="code">IN FILE LIBRARY DEFINE FIELDGROUP BOOK <br />
IN FILE LIBRARY DEFINE FIELDGROUP CHAPTER WITH FG BOOK<br />
IN FILE LIBRARY DEFINE FIELD RECTYPE WITH ORD CHAR <br />
IN FILE LIBRARY DEFINE FIELD AUTHOR_FIRSTNAME WITH ORD CHAR <br />
IN FILE LIBRARY DEFINE FIELD AUTHOR_LASTNAME WITH ORD CHAR<br />
IN FILE LIBRARY DEFINE FIELD BOOK_TITLE WITH ORD CHAR EXACTLY-ONE FG BOOK<br />
IN FILE LIBRARY DEFINE FIELD BOOK_SUBTITLE WITH ORD CHAR EXACTLY-ONE FG BOOK<br />
IN FILE LIBRARY DEFINE FIELD BOOK_ISBN WITH ORD CHAR EXACTLY-ONE FG BOOK <br />
IN FILE LIBRARY DEFINE FIELD BOOK_PRICE WITH AT-MOST-ONE FG BOOK<br />
IN FILE LIBRARY DEFINE FIELD BOOK_READERCOMMENT WITH REPEATABLE FG BOOK<br />
IN FILE LIBRARY DEFINE FIELD CHAPTER_NO WITH REPEATABLE FG CHAPTER<br />
IN FILE LIBRARY DEFINE FIELD CHAPTER_TITLE WITH REPEATABLE FG CHAPTER<br />
</p><br />
<p><br />
Note that the fieldgroup <code>CHAPTER</code> is defined with an attribute of fieldgroup <code>BOOK</code>, which causes <code>CHAPTER</code> to be nested inside <code>BOOK</code>. To add records to this file, a <var>STORE RECORD</var> statement stores a base record, and then fieldgroups are added inside a <var>THEN CONTINUE</var> clause:</p><br />
<br />
<p class="code">in file library store record <br />
rectype = 'AUTHOR'<br />
author_firstname = 'Jane'<br />
author_lastname = 'Austen'<br />
then continue <br />
add fieldgroup book <br />
book_title = 'Sense and Sensibility' <br />
book_subtitle = <br />
book_isbn = %isbn(%x)<br />
book_price = %price(%x) <br />
book_readercomment = 'Loved it. Better than "Cats". Mom' <br />
book_readercomment = 'An inspired, blistering novel. The New York Times' <br />
book_readercomment = 'Excellent! GB Shaw'<br />
then continue <br />
add fieldgroup chapter <br />
chapter_no = 1 <br />
chapter_title = 'The Dashwoods of Sussex' <br />
end add <br />
add fieldgroup chapter <br />
chapter_no = 2<br />
chapter_title = 'Mrs. John Dashwood' <br />
end add <br />
add fieldgroup chapter <br />
chapter_no = 3 <br />
chapter_title = 'Freddy and Elinor' <br />
end add <br />
end add <br />
add fieldgroup book <br />
book_title = 'Pride and Prejudice' <br />
book_subtitle = <br />
book_isbn = %isbn(%y) <br />
book_price = %price(%y) <br />
book_readercomment = 'Brief. Encountery. Mom' <br />
book_readercomment = 'Would love to snap up the movie rights. H. Smidkin' <br />
then continue <br />
add fieldgroup chapter <br />
chapter_no = 1 <br />
chapter_title = 'A Truth Universally Acknowledged'<br />
end add <br />
add fieldgroup chapter <br />
chapter_no = 2<br />
chapter_title = 'Waiting on Mr. Bingley' <br />
end add <br />
end add <br />
end store <br />
</p><br />
<p class="note"><b>Note:</b><br />
In the above example there is no specific "end" statement for the <var>THEN CONTINUE</var> statements. Rather, the context for the continue ends when the containing context ends. In the case above, the context of the outermost <var>THEN CONTINUE</var> is the <var>STORE RECORD</var> statement, which is being continued in order to provide <var>ADD FIELDGROUP</var> statements for field group <code>BOOK</code>. The context for the inner <var>THEN CONTINUE</var> statements &mdash; used to add <code>CHAPTER</code> field groups &mdash; is the <var>ADD FIELDGROUP</var> statement above it. After adding <code>CHAPTER</code> information for a <code>BOOK</code>, that block is ended with <var>END ADD</var>, and <var>STORE RECORD</var> context returns, where if needed, another <code>BOOK</code> field group can be added.</p><br />
<br />
====Nested STORE RECORD statements====<br />
<p><br />
The <var>THEN CONTINUE</var> block allows for the coding of a nested <var>STORE..END STORE</var> block within the body of the outer <var>STORE</var>, so that related records may be built together. A nested <var>STORE</var> can refer to a different file context, without compromising the file context of the outer <var>STORE</var>. </p><br />
<p><br />
The following example stores an order header record along with an order line record:</p><br />
<p class="code">IN ORDHDR STORE RECORD<br />
ORDER_NUMBER = 1000568<br />
CUSTOMER_NUMBER = 111456<br />
THEN CONTINUE<br />
IN ORDLINE STORE RECORD<br />
ORDER_NUMBER = 1000568<br />
ITEM_ID = F004<br />
ITEM_QTY = 3<br />
END STORE<br />
ADD ORDER_STATUS = A<br />
END STORE<br />
...<br />
</p><br />
<p><br />
The results of this would be the following record stored in the <code>ORDHDR</code> file:</p><br />
<p class="output">ORDER_NUMBER = 1000568<br />
CUSTOMER_NUMBER = 111456<br />
ORDER_STATUS = A<br />
</p><br />
<p><br />
and the following record stored in the <code>ORDLINE</code> file:</p><br />
<p class="output">ORDER_NUMBER = 1000568<br />
ITEM_ID = F004<br />
ITEM_QTY = 3<br />
</p><br />
<br />
====Multiply occurring fields====<br />
<p><br />
In the following example, a <var>For Each Occurrence</var> loop is driven, based on occurrences of the field <code>SALES_MM</code> previously stored, to store occurrences of <code>MONTHLY_TOTAL</code>:</p><br />
<p class="code">B<br />
%MONTHLY_SALES IS FLOAT ARRAY (3)<br />
%MONTHLY_SALES(1) = 10<br />
%MONTHLY_SALES(2) = 15<br />
%MONTHLY_SALES(3) = 35<br />
IN SALES STORE RECORD<br />
RECTYPE = TOT_SALES<br />
SALES_MM = '01'<br />
SALES_MM = '02'<br />
SALES_MM = '03'<br />
THEN CONTINUE<br />
FEO_SALES:<br />
FEO SALES_MM<br />
ADD MONTHLY_TOTAL = %MONTHLY_SALES(OCCURRENCE IN FEO_SALES)<br />
END FOR<br />
END STORE<br />
END<br />
</p><br />
<p><br />
The resultant record in the <code>SALES</code> file is:</p><br />
<p class="output">RECTYPE = TOT_SALES<br />
SALES_MM = 01<br />
SALES_MM = 02<br />
SALES_MM = 03<br />
MONTHLY_TOTAL = 10<br />
MONTHLY_TOTAL = 15<br />
MONTHLY_TOTAL = 35<br />
</p><br />
<br />
====COMMIT and BACKOUT====<br />
<p><br />
The <var>COMMIT</var> and <var>BACKOUT</var> statements can be used following a <var>THEN CONTINUE</var> statement to save parts of a record as it is built, and to back out all of parts of a record conditionally. Consider the following example:</p><br />
<p class="code">%CUSTNO = '100639'<br />
IN ORDERS STORE RECORD<br />
RECTYPE = ORDER<br />
ORDER_NUMBER = 1000234<br />
CUSTOMER_NUMBER = %CUSTNO<br />
THEN CONTINUE<br />
COMMIT /? save the order header ?/<br />
FIND_CUST:<br />
IN CLIENTS FD RECTYPE = POLICYHOLDER<br />
POLICY NO = %CUSTNO<br />
END FIND<br />
FOR 1 RECORD IN FIND_CUST<br />
%ADDRESS = ADDRESS<br />
%CITY = CITY<br />
END FOR<br />
ADD ADDRESS = %ADDRESS<br />
ADD CITY = %CITY<br />
<br />
COMMIT /? Save the customer address ?/<br />
ADD DELIV_DATE = ($datechg('YYYYMMDD',$DATE(1,&apos;&apos;),10))<br />
IF %ORDER_DELAYED = 'Y' THEN<br />
BACKOUT /? Back out deliv date if delay detected ?/<br />
END IF<br />
END STORE<br />
</p><br />
<p><br />
If <code>%ORDER_DELAYED</code> is not <code>Y</code>, the record is stored as follows:</p><br />
<p class="output">RECTYPE = ORDER<br />
ORDER_NUMBER = 1000234<br />
CUSTOMER_NUMBER = 100639<br />
ADDRESS = 0880 HANCOCK STREET<br />
CITY = LANCASTER<br />
DELIV_DATE = 20111228<br />
</p><br />
<p><br />
Otherwise, the <code>DELIV_DATE</code> <var class="term">fieldname</var>=<var class="term">value</var> pair is backed out.</p><br />
<br />
====Known restrictions or limitations====<br />
<ul><br />
<li>Be cautious of using the <var>JUMP TO</var> statement following <var>THEN CONTINUE</var> to jump to a label outside the <var>STORE..END STORE</var> block, as this may lead to the storing of a partial record.</li><br />
<br />
<li>It is possible to call a subroutine after the <var>THEN CONTINUE</var> statement, as you might in a <var>FOR RECORD NUMBER</var> loop. Additional update statements to the current record are allowed in the subroutine but only in a <var>FRN $Currec</var> loop. Otherwise, record context is not established and any additional updating statements within the subroutine would be rejected with the following compilation error: <br />
<p class="code">M204.0229: INVALID STATEMENT<br />
</p></li><br />
<br />
<li>A <var>DELETE RECORD</var> statement following <var>THEN CONTINUE</var>, but before <var>END STORE</var>, causes the current record context to be lost. Any further update statements cause the request to be cancelled with one of the following messages: <br />
<p class="code">M204.1233: DFAV, BAD RECORD NUMBER <i>n</i> FOR FILE <i>filename</i> <br />
M204.1266: NONEXISTENT RECORD REFERENCED - <i>n</i> IN FILE DSNLIST<br />
</p></li><br />
</ul><br />
<p class="note"><b>Note:</b> When using <var>THEN CONTINUE</var>, keep in mind standard considerations for coding any update unit. Be aware that creating longer update units has implications for resource sharing, checkpoints, and recovery requirements.</p><br />
<br />
==UPDATE RECORD statement==<br />
<p><br />
The <var>UPDATE RECORD</var> statement improve performances in remote context by using only one network call to perform all of a group of field-level updates (<var>ADD</var>, <var>CHANGE</var>, <var>DELETE</var>) against the current record in a record loop.</p><br />
<br />
===Syntax===<br />
<p><br />
The syntax of the <var>UPDATE RECORD</var> statement is as follows:</p><br />
<p class="syntax">UPDATE RECORD<br />
<span class="term">update-statement-1</span><br />
<span class="term">update-statement-2</span><br />
.<br />
.<br />
.<br />
<span class="term">update-statement-N</span><br />
END UPDATE<br />
</p><br />
Where:<br />
<p><br />
An <var class="term">update-statement</var> is one of the following:</p><br />
<ul><br />
<li><var>ADD</var></li><br />
<br />
<li><var>DELETE</var></li><br />
<br />
<li><var>CHANGE</var></li><br />
<br />
<li><var>INSERT</var></li><br />
</ul><br />
<br />
===Usage===<br />
<ul><br />
<li>The <var>UPDATE RECORD</var> statement, while supported in all reference contexts, is intended for use with <var class="product">Parallel Query Option/204</var>.</li><br />
<br />
<li>If a series of update statements is executed individually, each one requires a separate network call.</li><br />
<br />
<li>All forms of the update statements are supported. Except, a <var>DELETE EACH</var> statement is not allowed within an <var>UPDATE RECORD</var> statement.</li><br />
<br />
<li>If a field constraint violation occurs, the entire <var>UPDATE</var> statement is backed out.</li><br />
<br />
<li>If an <var>ON</var> unit invoked during the processing of an <var>UPDATE RECORD</var> statement is run with a <var>BYPASS</var> statement, the processing of the request continues with the statement that follows the <var>END UPDATE</var> statement.</li><br />
<br />
<li>If no updates are found between <var>UPDATE RECORD</var> and <var>END UPDATE</var>, the statement is ignored.</li><br />
</ul><br />
<br />
==Using VALUE IN to reference a NOTE value==<br />
<br />
===VALUE IN label clause===<br />
<p><br />
The clause <var>VALUE IN <i>label</i></var> can replace an explicit field value in the <var>ADD</var>, <var>CHANGE</var>, and <var>STORE RECORD</var> statements. This also applies to the special forms of these statements that are discussed in [[Processing multiply occurring fields and field groups]].</p><br />
<p><br />
The forms of the <var>VALUE IN</var> statement are:</p><br />
<p class="syntax">ADD <span class="term">fieldname</span> = VALUE IN <span class="term">label</span><br />
<br />
CHANGE <span class="term">fieldname</span> TO VALUE IN <span class="term">label</span><br />
<br />
STORE RECORD <span class="term">fieldname</span> = VALUE IN <span class="term">label</span><br />
</p><br />
<br />
===Example===<br />
<p><br />
The following request finds all records in the <code>CLIENTS</code> file that are registered in Alexandria and insured by agent Casola. The policy number for each record found is noted and a corresponding policy number is located on the <code>VEHICLES</code> file. The vehicle premium for the policy on the <code>VEHICLES</code> file is then changed to the total premium amount noted for the policy on the <code>CLIENTS</code> file. </p><br />
<p class="code">BEGIN<br />
FIND.RECS: IN CLIENTS FIND ALL RECORDS FOR WHICH<br />
AGENT = CASOLA<br />
CITY = ALEXANDRIA<br />
END FIND<br />
FOR EACH RECORD IN FIND.RECS<br />
KEEP.POL: NOTE POLICY NO<br />
KEEP.PREM: NOTE TOTAL PREMIUM<br />
FIND.MATCH: IN VEHICLES FIND ALL RECORDS FOR WHICH<br />
OWNER POLICY = VALUE IN KEEP.POL<br />
END FIND<br />
FOR EACH RECORD IN FIND.MATCH<br />
CHANGE VEHICLE PREMIUM TO VALUE -<br />
IN KEEP.PREM<br />
END FOR<br />
END FOR<br />
END<br />
</p><br />
<br />
==Storing data in fields==<br />
<br />
===Storing null values===<br />
<p><br />
If the new value in an <var>ADD</var>, <var>CHANGE</var>, or <var>STORE</var> statement is left blank, no field is added to or stored with the record. If a field containing a null value must be added, you specify the value as an explicit null string (two single quotes with no space between them). For example: </p><br />
<p class="code">ADD VEHICLE PREMIUM = &apos;&apos;<br />
CHANGE AGENT TO &apos;&apos;<br />
</p><br />
<p><br />
Note that this statement:</p><br />
<p class="code">CHANGE FULLNAME TO<br />
</p><br />
<p><br />
is equivalent to:</p><br />
<p class="code">DELETE FULLNAME<br />
</p><br />
<p><br />
because the old value of <code>FULLNAME</code> is deleted, but no new value is added.</p><br />
<br />
===Using the FIND statement to select fields with null values===<br />
<p><br />
You can use the <var>FIND</var> statement to select records that have a field whose value is the null string, as illustrated below:</p><br />
<p class="code">FIND.RECS: IN CLIENTS FIND ALL RECORDS FOR WHICH<br />
FULLNAME = &apos;&apos;<br />
END FIND<br />
</p><br />
<p><br />
However, the <var>FIND</var> statement does not select records for a particular field that is missing altogether from the record. See [[Record retrievals#IS PRESENT condition|IS PRESENT condition]] and [[Value loops#Locating records missing a particular field|Locating records missing a particular field]] for examples of finding records without a particular field. </p><br />
<br />
===Storing values in preallocated fields===<br />
<p><br />
The file manager can indicate in a field definition the length of the field (<var>LENGTH</var> attribute) and/or the number of times that field can occur in a record (<var>OCCURS</var> attribute). Space for fields with the <var>LENGTH</var> and <var>OCCURS</var> attributes is preallocated in each record in a file, and this space cannot be expanded. </p><br />
<p><br />
If you attempt to store more values (an <var>OCCURS</var> violation) or longer values (a <var>LENGTH</var> violation) than a field's definition permits, an error message is displayed or the request is cancelled. </p><br />
<br />
====LENGTH violations====<br />
<p><br />
If a field is defined as having a particular length (<var>LENGTH</var> <i>m</i>), that field can store only values that are between one and <var class="term">m</var> bytes long. Other values are rejected. If you explicitly specify a field name and value in a SOUL statement, as in this request: </p><br />
<p class="code">ADD YEAR = 90<br />
</p><br />
<p><br />
<var class="product">Model&nbsp;204</var> checks the length of the value during the compilation phase. A length violation detected in an update statement (<var>ADD</var>, <var>CHANGE</var>, <var>FILE</var>, or <var>STORE</var>) results in a compilation error. A length violation also can be detected for a <var>STORE</var> statement for a sort or hash key defined with <var>LENGTH</var> <i>m</i>. </p><br />
<p><br />
If field name variables or %variables are used in an update statement, length validity checks are deferred until the request is evaluated. If an error is detected at this point, the request is cancelled. Request cancellation can be avoided by using <var>[[$FldLen#$FldLen|$FldLen]]</var>. Specifying a field value that is too long for a <var>LENGTH</var> field in a retrieval context always causes the retrieval to fail, because the value could not have been stored. </p><br />
<p><br />
Attempts to locate invalid values are treated as references to a nonexistent value. For example, a selection criterion in a <code>FIND <i>fieldname</i> = <i>value</i></code> fails to locate any records. </p><br />
<br />
====OCCURS violations====<br />
<p><br />
If a field is defined as occurring a particular number of times (<var>OCCURS</var> <i>n</i>), it can be stored up to n times in any record. An attempt to add (using <var>ADD</var> or <var>STORE RECORD</var> statement) an additional occurrence to a record containing the maximum number causes the request to be cancelled. To protect SOUL requests from cancellations due to occurrence violations refer to:</p><br />
<ul><br />
<li>[[Processing multiply occurring fields and field groups#COUNT OCCURRENCES OF statement|COUNT OCCURRENCES OF statement]] </li><br />
<br />
<li><var>[[$Occurs|$Occurs]]</var> <br />
</li><br />
</ul><br />
<br />
===Storing values in FLOAT fields===<br />
<br />
====Exponent notation====<br />
<p><br />
If a new value is to be stored in a field defined with the FLOAT attribute, the value can be defined in exponent notation. See [[Record retrievals#Exponent notation|Exponent notation]] for information. </p><br />
<p><br />
An invalid value is stored as an unconverted string.</p><br />
<br />
====String values====<br />
<p><br />
When you supply a string as the value to be stored, <var class="product">Model&nbsp;204</var> attempts to convert the string to floating point representation according to the floating point conversion rules (see [[Record retrievals#Equality retrievals|Equality retrievals]]). If the value to be stored cannot be converted, one of two things happens:</p><br />
<ul><br />
<li>If the field is preallocated, the request is cancelled.</li><br />
<br />
<li>If the field is not preallocated, the unconverted value is stored. <br />
</li><br />
</ul><br />
<br />
====Floating point values====<br />
<p><br />
When you supply a floating point value as the value to be stored, the value is not altered if its length is the same as the floating point field's defined length. Values of different lengths are truncated or rounded according to the rules described in. </p><br />
<br />
===Storing values in BINARY fields===<br />
<br />
====Compressed values====<br />
<p><br />
Fields defined as having the <var>BINARY</var>, <var>OCCURS</var>, and <var>NON-CODED</var> attributes can store only compressible values because only a small amount of space is preallocated for such a field. A compressible value is a decimal integer of up to nine digits with no plus sign, leading zeros, embedded blanks (following a minus sign), or decimal point.<br />
Refer to [[Field design#Data_typing|Data typing]] for additional information on such values. </p><br />
<br />
====Value checking====<br />
<p><br />
Values to be stored in <var>BINARY</var> fields are not checked until the request is evaluated. If you attempt to store an incompressible value in a <var>BINARY</var>, <var>OCCURS</var>, and <var>NON-CODED</var> field, the request is cancelled. </p><br />
<br />
==Updating field groups==<br />
<p class="note"><b>Note: </b>[[Field group (File architecture)|Field groups]] are supported as of Model 204 version 7.5.</p><br />
<p><br />
When a field group is added, a field group ID is assigned to the field group. This field group ID is unique among all field groups in the record, whether or not they have the same field group name. The ID is a number between 1 (zero is not used as an ID) and 2**32-1. The field group ID is an unsigned 32-bit integer, though only a length byte and trailing non-zero bytes are stored.</p><br />
<br />
Field group IDs from 1-255 require two bytes for the field group ID in Table B, IDs 256-65535 require three bytes, and so on. Once assigned, a field group ID is not reused regardless of whether the field group associated with the ID is deleted. That is, if you add a field group and it is assigned ID 6, and then you delete the field group, ID 6 will not be reused.<br />
<br />
The one exception when field group ID reuse is allowed is on transaction back out. If field group ID 6 is assigned to an added field group, but then the addition is backed out, field group ID 6 can be assigned to a subsequent <var>ADD</var> or <var>INSERT FIELDGROUP</var>.<br />
<br />
The following subsections provide an overview of the basic operations with field groups. For additional details, see [[Processing multiply occurring fields and field groups]].<br />
<br />
===Adding a field group===<br />
To add a field group, issue an ADD FIELDGROUP statement in a record context:<br />
<p class="syntax">FR IN LABELX<br />
ADD FIELDGROUP <span class="term">fieldgroupname</span><br />
field1 = (<span class="term">value1</span> <span class="squareb">|</span> <span class="term">expression</span>)<br />
[field2 = (<span class="term">value2</span> <span class="squareb">|</span> <span class="term">expression</span>)<br />
...]<br />
END ADD<br />
END FOR<br />
</p><br />
The syntax of the <var class="term">fieldname=value</var> pairs inside an <var>ADD FIELDGROUP</var> statement is identical to that of a <var>STORE RECORD</var> statement. See also [[#Inserting a field group|Inserting a field group]].<br />
<br />
In place of a value in the <var class="term">fieldname=value</var> pair, you can enter an expression. See [[#Expressions as field name values|Expressions as field name values]] for details.<br />
<br />
===Inserting a field group===<br />
In addition to the ADD FIELDGROUP statement, you can also issue an <var>INSERT FIELDGROUP</var> statement:<br />
<p class="code">FR WHERE ...<br />
INSERT FIELDGROUP <var class="term">name</var>(<var class="term">subscript</var>)<br />
FIELDA = &#x2019;ABC&#x2019;<br />
FIELDB = &#x2019;DEF&#x2019;<br />
...<br />
END INSERT<br />
END FOR<br />
</p><br />
<br />
The <var>INSERT FIELDGROUP</var> statement has the same semantics as an <var>INSERT FIELD</var> statement. If the indicated occurrence of the field group is found, the new occurrence is inserted immediately before that occurrence. If it is not found, the new occurrence is added at the end of the record.<br />
<br />
The inside of the <var>INSERT</var> block has the identical format to the <var>STORE RECORD</var> and <var>ADD FIELDGROUP</var> statements.<br />
<br />
===Deleting a field group===<br />
You can delete a field group several ways.<br />
<br />
====Delete first field group occurrence in each record====<br />
<p class="code">BEGIN<br />
A: IN TEST1 FD<br />
END FIND<br />
B: FR A<br />
DELETE FIELDGROUP BIRDS<br />
END FOR<br />
</p><br />
<br />
====Delete all field group occurrences, if present, in one record====<br />
<p class="code">BEGIN<br />
A: IN TEST1 FD<br />
END FIND<br />
B: FR A<br />
DELETE EACH FIELDGROUP PESTS<br />
END FOR<br />
</p><br />
<br />
====Delete a field group without the name or ID reference====<br />
<p class="code">BEGIN<br />
A: IN TEST1 FD<br />
END FIND<br />
B: FR A<br />
FOR EACH OCCURRENCE OF FIELDGROUP TRANSLATIONS<br />
IF LANGUAGE = &#x2019;INDIAN&#x2019; THEN<br />
%X = $FIELDGROUPID<br />
DELETE FIELDGROUP<br />
PRINT &#x2019;DELETING ID: &#x2019; WITH %X<br />
END IF<br />
END FOR<br />
END FOR<br />
</p><br />
<br />
====Delete a field group with a subscript====<br />
<p><br />
To delete the third occurrence of field group <code>PITCHERS</code>, you would issue the following statement:</p><br />
<p class="code">FR IN LABELX<br />
DELETE FIELDGROUP PITCHERS(3)<br />
END FOR<br />
</p><br />
When you delete a field group occurrence, all fields within the field group occurrence are deleted, as well as the indices for those fields. Or, you can delete a field group with a simple <var>DELETE</var> statement while in a field group context:<br />
<p class="code">FR IN LABELX<br />
FAO FIELDGROUP PITCHERS<br />
DELETE FIELDGROUP<br />
END FOR<br />
END FOR<br />
</p><br />
<br />
===Displaying field groups and their fields===<br />
After you add a field group to a record, you can display the field groups and their fields by issuing a <var>PAI</var> statement, output as follows:<br />
<p class="code">BEGIN<br />
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100095<br />
PAI<br />
END<br />
<br />
POLICY_NUMBER = 100095<br />
POLICY_RESTRICTIONS = POLICY IS INVALID IF ...<br />
... OTHER POLICY FIELDS<br />
\DRIVER = 1<br />
DRIVER_NAME = ALTON, BARBARA W<br />
...OTHER DRIVER FIELDS<br />
/DRIVER = 1<br />
\DRIVER = 2<br />
DRIVER_NAME = ALTON, CARRIE Y<br />
...OTHER DRIVER FIELDS<br />
/DRIVER = 2<br />
\VEHICLE = 6<br />
MAKE = VOLKSWAGEN<br />
MODEL = NEW BEETLE<br />
...OTHER VEHICLE FIELDS<br />
/VEHICLE = 6<br />
\VEHICLE = 7<br />
MAKE = MITSUBISHI<br />
MODEL = ECLIPSE<br />
...OTHER VEHICLE FIELDS<br />
\CLAIM = 9<br />
CLAIM_NUMBER = 100059<br />
WEATHER = RAIN<br />
...OTHER CLAIM FIELDS<br />
/CLAIM = 9<br />
\CLAIM = 10<br />
CLAIM_NUMBER = 100064<br />
WEATHER = FOG<br />
...OTHER CLAIM FIELDS<br />
/CLAIM = 10<br />
/VEHICLE = 7<br />
\VEHICLE = 8<br />
MAKE = CHEVROLET<br />
MODEL = SUBURBAN<br />
...OTHER VEHICLE FIELDS<br />
/VEHICLE = 8<br />
</p><br />
The lines that begin with a backslash (<tt>\</tt>) identify the start of a field group and the lines that begin with a forward slash (<tt>/</tt>) identify the end of the field group. The field group ID of the field group occurrence is indicated after the field group name on both the field group beginning and ending lines.<br />
<br />
The field group IDs are not necessarily in ascending order in a record. The previous example was created by issuing <var>INSERT</var> statements, so the IDs are out of order.<br />
<br />
See also:<br />
<ul><br />
<li>The <var>[[Basic SOUL statements and commands#Print All Fieldgroup Information (PAFGI) statement|PAFGI]]</var> statement to display a field group's content. </li><br />
<br />
<li>The function <var>[[$FieldgroupId]]</var> to show the field group ID. </li><br />
</ul><br />
<br />
===Support for field group name variables===<br />
<p><br />
Field group name variables are supported; for example:</p><br />
<p class="code"><nowiki>IN POLICIES FRN %RECNO<br />
%FIELD = &#x2019;SURCHARGE%&#x2019;<br />
ADD FIELDGROUP VEHICLE<br />
MAKE = &#x2019;FORD&#x2019;<br />
MODEL = &#x2019;MUSTANG&#x2019;<br />
%%FIELD = 15<br />
* and so on<br />
END ADD FIELDGROUP VEHICLE<br />
END FOR</nowiki></p><br />
<br />
Field name variables that evaluate to something in an invalid field group context result in request cancellation. For example, if <code>BARD</code> is a field in field group <code>PITCHERS</code> and you issue the following statement:<br />
<p class="code">IN FILE REDSOCKS FRN %RECNO<br />
%FIELD = &#x2019;BARD&#x2019;<br />
ADD %%FIELD = &#x2019;Knuckle ball&#x2019;<br />
</p><br />
A request cancellation is generated, because you tried to add an occurrence of field <code>BARD</code> outside its appropriate field group context.<br />
</div> <!-- ends toclimit div --><br />
<br />
[[Category:SOUL]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Statement_syntax&diff=115013Statement syntax2018-04-25T21:00:25Z<p>Admin: /* Change */ link repair</p>
<hr />
<div>This page summarizes SOUL syntax and conventions, which are discussed in more detail throughout this wiki. The SOUL statements are listed in alphabetical order. Many of the section titles or syntax blocks contain links to the wiki page describing the statement or syntax phrase. A [[#Other syntax|later section]] provides other SOUL syntax information, including links to [[#tokens|information about the "tokens"]] of SOUL, such as names in SOUL.<br />
<p><br />
All SOUL statements can be used between a <var>[[BEGIN command|Begin]]</var> (or <var>[[MORE command|More]]</var>) command and an <var>[[End statement|End]]</var> statement. </p><br />
<p>External Call Facility (ECF) statements are listed under <var>[[#External|External]]</var>.</p><br />
<p><br />
Various other [[List of Model 204 commands|Model 204 commands]] also have effects on the results of a SOUL request. </p><br />
<br />
The following unusual notations are used in the presentation of the SOUL syntax:<br />
<p class="code"><nowiki>*<br />
**<br />
+<br />
++<br />
C<br />
</nowiki></p><br />
<br />
See the [[#Notation conventions|notation conventions]] section for an explanation of these usages, as well as other general comments about understanding the syntax of SOUL.<br />
<br />
<div id="User Language statements"></div> <!-- In case there are links (as if) --><br />
<div id="SOUL statements"></div> <div id="SOUL syntax"></div><br />
<!--To make above link targets go to toc:--><br />
&nbsp;<br />
<!--==SOUL statements in alphabetical order==--><br />
<br />
===[[Data_maintenance#ADD_statement|ADD]]===<br />
<p class="syntaxUL"><b><sup>(**)</sup></b>ADD <span class="term">fieldname</span> = <span class="squareb">{</span><span class="term">value</span> <span class="squareb">|</span> (<span class="term">expression</span>)<span class="squareb">}</span><br />
<br />
[[Large_Object_field_processing_for_non-FILEORG_X%27100%27_files#Adding_Large_Object_fields|ADD]] <span class="term">lob-name</span>=BUFFER,<span class="term">position</span>,<span class="term">length</span><span class="squareb">[</span>RESERVE <span class="term">n</span> <span class="squareb">[</span>BYTES<span class="squareb">]</span><span class="squareb">]</span><br />
</p><br />
<br />
===ARRAY===<br />
<br />
<p class="syntaxUL">ARRAY <span class="squareb">[</span><span class="term">arrayname</span><span class="squareb">]</span> OCCURS <span class="squareb">{</span><span class="term">n</span> <span class="squareb">|</span> UNKNOWN<span class="squareb">}</span><br />
DEPENDING ON <span class="squareb">{</span><span class="term">itemname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
<span class="squareb">[</span>AFTER <span class="squareb">{</span><span class="term">itemname</span> <span class="squareb">|</span> <span class="term">arrayname</span><span class="squareb">}</span><br />
<span class="squareb">|</span> AT <span class="squareb">{</span><span class="term">position</span> <span class="squareb">|</span> <span class="term">itemname</span> <span class="squareb">|</span> <span class="term">imagename1</span> <span class="squareb">|</span> <span class="term">arrayname</span><span class="squareb">}</span><span class="squareb">]</span><br />
</p><br />
<br />
===[[Assert statement|Assert]]===<br />
<br />
{{Template:Assert statement syntax}}<br />
<br />
===[[Report_generation#AUDIT_statement|AUDIT]]===<br />
<br />
<p class="syntaxUL">AUDIT <span class="term">[[#Print specification syntax|print-specifications]]</span><br />
</p><br />
<br />
===[[Audit All Fieldgroup Information statement|Audit All Fieldgroup Information]] (AAFGI)===<br />
<br />
{{Template:AAFGI statement syntax}}<br />
<br />
===AUDIT ALL INFORMATION===<br />
<br />
<p class="syntaxUL"><span class="squareb">{</span>[[Basic SOUL statements and commands#AUDIT ALL INFORMATION statement|AUDIT ALL INFORMATION]] <span class="squareb">|</span> AAI<span class="squareb">}</span> <span class="squareb">[</span>CTOFIELDS<span class="squareb">]</span><br />
</p><br />
<br />
===BACKOUT===<br />
<br />
<p class="syntaxUL"><b><sup>(C)</sup></b>[[Data recovery#Manual backout|BACKOUT]]</p><br />
<br />
===BYPASS===<br />
<br />
<p class="syntaxUL">BYPASS <span class="squareb">[</span>PENDING STATEMENT<span class="squareb">]</span> </p><br />
<br />
===CALL===<br />
<br />
<p class="syntaxUL">CALL <span class="squareb">{</span><span class="term">label</span> <span class="squareb">|</span> <span class="term">subname</span><br />
<span class="squareb">[</span>(<span class="squareb">[</span><span class="term">expression</span> <span class="squareb">|</span> <span class="term">%variable</span> <span class="squareb">|</span> <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">]</span> <span class="squareb">[</span>,...<span class="squareb">]</span>)<span class="squareb">]</span><span class="squareb">}</span><br />
</p><br />
<br />
===[[Data maintenance#Change statement|Change]]===<br />
<br />
{{Template:Change fieldname statement syntax (basic)}}<br />
<br />
{{Template:Change lob-fieldname statement syntax}}<br />
<br />
===[[Global_features#Using_the_CLEAR_statement|CLEAR]]===<br />
<br />
{{Template:Clear statement syntax}}<br />
<br />
===CLEAR LIST===<br />
<br />
<p class="syntaxUL"><b><sup>(*)</sup></b>[[Lists#Clearing a list|CLEAR LIST]] <span class="term">listname</span> </p><br />
<br />
===CLEAR ON===<br />
<br />
{{Template:Clear On statement syntax}}<br />
<br />
===CLEAR TAG===<br />
<br />
<p class="syntaxUL">CLEAR TAG <span class="squareb">{</span><span class="term">screenname</span> <span class="squareb">|</span> <span class="term">%screenname</span>:<span class="term">inputname</span><span class="squareb">}</span><br />
</p><br />
<br />
===CLOSE===<br />
<br />
<p class="syntaxUL">CLOSE<br />
<span class="squareb">{</span>DATASET <span class="squareb">{</span><span class="term">ext-filename</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
<span class="squareb">|</span> <span class="squareb">[</span>EXTERNAL<span class="squareb">]</span> <span class="squareb">{</span><span class="term">ext-filename</span> <span class="squareb">|</span> TERMINAL <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><span class="squareb">}</span><br />
</p><br />
<br />
===CLOSE PROCESS===<br />
<br />
<p class="syntaxUL"><b><sup>(+C)</sup></b>CLOSE PROCESS<br />
<span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> <span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
<span class="squareb">[</span>SYNCLEVEL <span class="squareb">|</span> FLUSH <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">]</span><br />
<br />
CLOSE PROCESS<br />
<span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> <span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
<span class="squareb">[</span>SYNCLEVEL <span class="squareb">|</span> CONFIRM <span class="squareb">|</span> FLUSH <span class="squareb">|</span> ERROR <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">]</span><br />
</p><br />
<br />
===[[Commit statement|Commit]]===<br />
<br />
{{Template:Commit statement syntax}}<br />
<br />
===[[Horizon SOUL interface#Confirm statement|Confirm]]===<br />
<br />
{{Template:Confirm statement syntax}}<br />
<br />
===[[Horizon SOUL interface#Confirmed statement|Confirmed]]===<br />
<br />
{{Template:Confirmed statement syntax}}<br />
<br />
===CONTINUE===<br />
<br />
<p class="syntaxUL">CONTINUE</p><br />
<br />
===COUNT OCCURRENCES OF===<br />
<br />
<p class="syntaxUL"><b><sup>(**)</sup></b>COUNT OCCURRENCES OF <span class="term">fieldname</span></p><br />
<br />
===COUNT RECORDS===<br />
<br />
<p class="syntaxUL">COUNT RECORDS <span class="squareb">{</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">}</span></p><br />
<br />
===<b id="declare"></b>DECLARE===<br />
<br />
<p class="syntaxUL"><span class="squareb">[</span>DECLARE<span class="squareb">]</span> <span class="term">declaration</span><br />
</p><br />
<br />
<p><br />
where <var class="term">declaration</var> is one of the following: </p><br />
<br />
<div style="margin-left: 20px; background-color: #fBfBfB;"><br />
<ul style="font-family: Consolas,monospace"><br />
<li>LABEL <i>labelname</i> <span class="squareb">[</span>GLOBAL <span class="squareb">|</span> COMMON<span class="squareb">]</span><br />
<br />
<li>[[Lists#DECLARE LIST syntax|LIST]] listname <span class="squareb">[</span>IN <span class="squareb">[</span>FILE <span class="squareb">|</span> <span class="squareb">[</span>PERM <span class="squareb">|</span> TEMP<span class="squareb">]</span> GROUP<span class="squareb">]</span><span class="squareb">]</span> <i>name</i><span class="squareb">]</span> <span class="squareb">[</span>GLOBAL <span class="squareb">|</span> COMMON<span class="squareb">]</span><br />
<br />
<li>IMAGE <i>imagename</i><span class="squareb">[</span>AT <span class="squareb">{</span><i>itemname</i> <span class="squareb">|</span> <i>imagename1</i> <span class="squareb">|</span> <i>arrayname</i><span class="squareb">}</span> <br><br />
<span class="squareb">|</span> GLOBAL <span class="squareb">[</span>PERMANENT <span class="squareb">|</span> TEMPORARY<span class="squareb">]</span> <br><br />
<span class="squareb">|</span> <span class="squareb">[</span>PERMANENT <span class="squareb">|</span> TEMPORARY<span class="squareb">]</span> GLOBAL <span class="squareb">|</span> COMMON<span class="squareb">]</span><br />
<br />
<li>MENU <i>menuname</i> <span class="squareb">[</span>GLOBAL <span class="squareb">[</span>PERMANENT <span class="squareb">|</span> TEMPORARY<span class="squareb">]</span> <br><br />
<span class="squareb">|</span> <span class="squareb">[</span>PERMANENT <span class="squareb">|</span> TEMPORARY<span class="squareb">]</span> GLOBAL <span class="squareb">|</span> COMMON<span class="squareb">]</span><br />
<br />
<li>SCREEN <i>screenname</i> <span class="squareb">[</span>GLOBAL <span class="squareb">[</span>PERMANENT <span class="squareb">|</span> TEMPORARY<span class="squareb">]</span> <br><br />
<span class="squareb">|</span> <span class="squareb">[</span>PERMANENT <span class="squareb">|</span> TEMPORARY<span class="squareb">]</span> GLOBAL <span class="squareb">|</span> COMMON<span class="squareb">]</span><br />
<br />
<li><i>%variable</i> <span class="squareb">[</span>IS<span class="squareb">]</span> <span class="squareb">{</span>FIXED <span class="squareb">[</span>DP <i>n</i><span class="squareb">]</span> <span class="squareb">|</span> FLOAT<span class="squareb">}</span> <span class="squareb">[</span>ARRAY (<i>d1</i> <span class="squareb">[</span>,<i>d2</i> <span class="squareb">[</span>,<i>d3</i><span class="squareb">]</span><span class="squareb">]</span>)<span class="squareb">]</span> <br><br />
<span class="squareb">[</span>[[Initial clause in %variable declaration|Initial]](<i>numeric-expression</i>)<span class="squareb">]</span> <span class="squareb">[</span>STATIC<span class="squareb">]</span> <span class="squareb">[</span>COMMON<span class="squareb">]</span><br />
<br />
<li><i>%variable</i> <span class="squareb">[</span>IS<span class="squareb">]</span> STRING <span class="squareb">[</span>LEN <i>n</i><span class="squareb">]</span> <span class="squareb">[</span>DP <span class="squareb">{</span><i>n</i> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span>ARRAY (<i>d1</i> <span class="squareb">[</span>,<i>d2</i><span class="squareb">[</span>,<i>d3</i><span class="squareb">]</span><span class="squareb">]</span>)<span class="squareb">]</span> <br><br />
<span class="squareb">[</span>NO FIELD SAVE<span class="squareb">]</span> <span class="squareb">[</span>COMMON<span class="squareb">]</span> <br><br />
<span class="squareb">[</span>[[Initial clause in %variable declaration|Initial]]('<i>EBCDIC-string</i>' <span class="squareb">|</span> <i>expression</i>)<span class="squareb">]</span> <span class="squareb">[</span>STATIC<span class="squareb">]</span><br />
<br />
<li>SUBROUTINE <i>subname</i> <span class="squareb">[</span>(<i>type</i> <span class="squareb">[</span>INPUT <span class="squareb">|</span> OUTPUT <span class="squareb">|</span> INPUT OUTPUT<span class="squareb">]</span> <span class="squareb">[</span>,...<span class="squareb">]</span>)<span class="squareb">]</span><br />
</ul><br />
</div> <!-- declare indent/background --> <br />
<br />
<div style="margin-left: 20px;><br />
<p><br />
and where <var class="term">type</var> is one of the following:</p><br />
</div><br />
<br />
<div style="margin-left: 40px; background-color: #fBfBfB;"><br />
<ul><br />
<li>Scalar %variable of the following format:<br />
<ul style="font-family: Consolas,monospace"><br />
<li><span class="squareb">{</span>STRING <span class="squareb">[</span>LEN<span class="squareb">]</span> <i>n</i> <span class="squareb">[</span>DP <span class="squareb">{</span><i>n</i> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">|</span> <span class="squareb">[</span>FIXED <span class="squareb">[</span>DP <i>n</i><span class="squareb">]</span> <span class="squareb">|</span> FLOAT<span class="squareb">]</span><span class="squareb">}</span> </li></ul><br />
</li><br />
<br />
<li>Array %variable of the following format:<br />
<ul style="font-family: Consolas,monospace"><br />
<li><span class="squareb">{</span>STRING <span class="squareb">[</span>LEN <i>n</i><span class="squareb">]</span> <span class="squareb">[</span>DP <span class="squareb">[</span><i>n</i> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span>ARRAY (* <span class="squareb">[</span>,*<span class="squareb">[</span>,*<span class="squareb">]</span><span class="squareb">]</span>) <span class="squareb">[</span>NO FIELD SAVE<span class="squareb">]</span><span class="squareb">]</span> <br><br />
<span class="squareb">|</span> <span class="squareb">[</span>FIXED <span class="squareb">[</span>DP <i>n</i><span class="squareb">]</span> <span class="squareb">|</span> FLOAT<span class="squareb">]</span> <span class="squareb">[</span>ARRAY (* <span class="squareb">[</span>,*<span class="squareb">[</span>,*<span class="squareb">]</span><span class="squareb">]</span>)<span class="squareb">]</span><span class="squareb">}</span> </li></ul><br />
</li><br />
<br />
<li>A list of records of the following format:<br />
<ul style="font-family: Consolas,monospace"><br />
<li><span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="squareb">[</span>IN <span class="squareb">{</span>FILE <span class="squareb">|</span> <span class="squareb">[</span>PERM <span class="squareb">|</span> TEMP<span class="squareb">]</span> GROUP<span class="squareb">}</span> <i>name</i><span class="squareb">]</span> </li></ul><br />
</li><br />
</ul><br />
<br />
</div> <!-- type indentation/background --><br />
<br />
====See also====<br />
<br />
<ul><br />
<li>[[Using variables and values in computation]]<br />
</ul><br />
<br />
===DEFAULT CURSOR===<br />
<br />
<p class="syntaxUL">DEFAULT CURSOR <span class="squareb">[</span>READ <span class="squareb">|</span> REREAD <span class="squareb">|</span> PRINT<span class="squareb">]</span><br />
<span class="squareb">{</span>ITEMID <span class="term">n</span> <span class="squareb">|</span> <span class="term">itemname</span> <span class="squareb">|</span> ROW <span class="term">n</span> COLUMN <span class="term">m</span><span class="squareb">}</span><br />
</p><br />
<br />
===DEFAULT===<br />
<br />
<p class="syntaxUL">DEFAULT <span class="squareb">{</span>TITLE<br />
<span class="squareb">|</span> PROMPT<br />
<span class="squareb">|</span> INPUT <span class="squareb">[</span>DEBLANK <span class="squareb">|</span> NODEBLANK<span class="squareb">]</span> <span class="squareb">[</span>PAD WITH '<span class="term">c</span>'<span class="squareb">]</span> <span class="squareb">[</span>LEN <span class="term">m</span> <span class="squareb">[</span>DP <span class="squareb">[</span><span class="term">k</span> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span><span class="squareb">]</span> <span class="squareb">[</span>UPCASE <span class="squareb">|</span> NOCASE<span class="squareb">]</span><br />
<span class="squareb">|</span> <span class="squareb">[</span>TAG <span class="squareb">[</span><span class="term">attributes</span><span class="squareb">]</span> <span class="squareb">[</span>WITH '<span class="term">c</span>'<span class="squareb">]</span><span class="squareb">}</span><br />
<span class="squareb">[</span><span class="squareb">[</span>READ<span class="squareb">]</span> <span class="term">attributes</span><span class="squareb">]</span> <span class="squareb">[</span>REREAD <span class="term">attributes</span><span class="squareb">]</span> <span class="squareb">[</span>PRINT <span class="term">attributes</span><span class="squareb">]</span><br />
<br />
DEFAULT SKIP <span class="term">n</span> POSITIONS<span class="squareb">[</span>S<span class="squareb">]</span><br />
<span class="squareb">[</span>INITIAL <span class="squareb">{</span>NULL <span class="squareb">|</span> <span class="term">character</span> <span class="squareb">|</span> BLANK<span class="squareb">}</span><span class="squareb">]</span><br />
<br />
DEFAULT <span class="squareb">[</span>TYPE<span class="squareb">]</span><br />
<span class="squareb">{</span>STRING <span class="squareb">|</span> BINARY <span class="squareb">|</span> PACKED <span class="squareb">|</span> ZONED <span class="squareb">|</span> FLOAT <span class="squareb">|</span> EFORMAT<span class="squareb">}</span><br />
<span class="squareb">{</span>LEN <span class="squareb">{</span><span class="term">n</span> <span class="squareb">|</span> UNKNOWN<span class="squareb">}</span> <span class="squareb">|</span> BITS <span class="term">n</span> <span class="squareb">|</span> DIGITS <span class="term">n</span><span class="squareb">}</span><br />
<span class="squareb">[</span>DP <span class="squareb">{</span><span class="term">k</span> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span>BP <span class="term">n</span><span class="squareb">]</span><br />
<span class="squareb">[</span>SIGNED <span class="squareb">|</span> UNSIGNED<span class="squareb">]</span> <span class="squareb">[</span>PAD <span class="squareb">{</span>BLANK <span class="squareb">|</span> <span class="term">character</span> <span class="squareb">|</span> NULL<span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">[</span>STRIP <span class="squareb">|</span> NOSTRIP<span class="squareb">]</span> <span class="squareb">[</span>JUSTIFY <span class="squareb">{</span>LEFT <span class="squareb">|</span> RIGHT<span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">[</span>INITIAL <span class="squareb">{</span>BLANK <span class="squareb">|</span> ZERO <span class="squareb">|</span> NULL <span class="squareb">|</span> <span class="term">literal</span><span class="squareb">}</span><span class="squareb">]</span><br />
</p><br />
<br />
===DELETE===<br />
<br />
<p class="syntaxUL"><b><sup>(**)</sup></b>[[Data_maintenance#DELETE_statement|DELETE]] <span class="term">fieldname</span> <span class="squareb">[</span>(<span class="term">[[Processing_multiply_occurring_fields_and_field_groups#DELETE_statement_rules|subscript]]</span>)<span class="squareb">]</span> <span class="squareb">[</span><b></b>= <span class="term">value</span> <span class="squareb">|</span> (<span class="term">expression</span>)<span class="squareb">]</span><br />
</p><br />
<br />
<p class="syntaxUL"><b><sup>(**)</sup></b>[[Data_maintenance#Deleting_a_field_group|DELETE FIELDGROUP]] <span class="squareb">[</span><span class="term">fieldgroupname</span><span class="squareb">]</span> <span class="squareb">[</span>(<span class="term">[[Processing_multiply_occurring_fields_and_field_groups#DELETE_statement_rules|subscript]]</span>)<span class="squareb">]</span> <span class="squareb">[</span><b></b>= <span class="term">value</span> <span class="squareb">|</span> (<span class="term">expression</span>)<span class="squareb">]</span><br />
</p><br />
<br />
===DELETE EACH===<br />
<br />
<p class="syntaxUL"><b><sup>(**)</sup></b>DELETE EACH <span class="term">fieldname</span></p><br />
<br />
===[[Data_maintenance#DELETE_RECORD_statement|DELETE RECORD]]===<br />
<br />
<p class="syntaxUL"><b><sup>(**)</sup></b>DELETE RECORD </p><br />
<br />
===DELETE RECORDS===<br />
<br />
<p class="syntaxUL">DELETE <span class="squareb">[</span>ALL<span class="squareb">]</span> RECORDS <span class="squareb">{</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">}</span><br />
</p><br />
<br />
===END BLOCK===<br />
<br />
<p class="syntaxUL">END BLOCK <span class="term">label</span> </p><br />
<br />
===End===<br />
<br />
<p class="syntaxUL">END <span class="squareb">{</span>FIND <span class="squareb">|</span> IF <span class="squareb">|</span> FOR <span class="squareb">|</span> ON <span class="squareb">|</span> REPEAT <span class="squareb">|</span> STORE <span class="squareb">|</span> SUBROUTINE<span class="squareb">}</span> [<span class="term">label</span><span class="squareb">]</span><br />
<br />
END <span class="squareb">{</span>ARRAY <span class="squareb">|</span> IMAGE <span class="squareb">|</span> MENU <span class="squareb">|</span> SCREEN<span class="squareb">}</span><br />
<br />
[[End statement|End]] <span class="squareb">[</span>MORE <span class="squareb">|</span> NORUN <span class="squareb">|</span> USE<span class="squareb">]</span>...</p><br />
<br />
===END UPDATE===<br />
<br />
<p class="syntaxUL">END UPDATE</p><br />
<br />
===[[External statement|External]]===<br />
<br />
{{Template:External statement syntax}}<br />
<br />
===FILE RECORDS===<br />
<br />
<p class="syntaxUL">FILE RECORDS <span class="squareb">{</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">}</span><br />
UNDER <span class="term">fieldname</span> = <span class="squareb">{</span><span class="term">value</span> <span class="squareb">|</span> (<span class="term">expression</span>)<span class="squareb">}</span><br />
</p><br />
<br />
===[[Find Records statement|Find Records]]===<br />
<br />
<p class="syntaxUL"><b><sup>(*)</sup></b><span class="squareb">{</span>FIND <span class="squareb">[</span><span class="squareb">[</span>ALL<span class="squareb">]</span> RECORDS<span class="squareb">]</span> <span class="squareb">|</span> FD <span class="squareb">}</span><br />
<span class="squareb">[</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">]</span><br />
<span class="squareb">[</span>FOR WHICH <span class="squareb">|</span> WITH<span class="squareb">]</span> <span class="term">[[#Retrieval condition syntax|retrieval-conditions]]</span></p><br />
<br />
===[[Find And Reserve statement|Find And Reserve]]===<br />
<br />
<p class="syntaxUL"><b><sup>(*)</sup></b><span class="squareb">{</span>FIND AND RESERVE <span class="squareb">[</span><span class="squareb">[</span>ALL<span class="squareb">]</span> RECORDS<span class="squareb">]</span> <span class="squareb">|</span> FDR<span class="squareb">}</span> <br />
<span class="squareb">[</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">]</span><br />
<span class="squareb">[</span>FOR WHICH <span class="squareb">|</span> WITH<span class="squareb">]</span> <span class="term">[[#Retrieval condition syntax|retrieval-conditions]]</span></p><br />
<br />
===[[Value loops#Find All Values statement|Find Values Of (FDV)]]===<br />
{{Template: Find Values Of statement syntax}}<br />
<br />
===FIND AND PRINT COUNT===<br />
<br />
<p class="syntaxUL"><b><sup>(*)</sup></b><span class="squareb">{</span>FIND AND PRINT COUNT <span class="squareb">|</span> FPC<span class="squareb">}</span><br />
<span class="squareb">[</span><span class="term">[[#Retrieval condition syntax|retrieval-conditions]]</span><span class="squareb">]</span><br />
</p><br />
<br />
===[[Find Records statement|Find Without Locks]]===<br />
<br />
<p class="syntaxUL"><b><sup>(*)</sup></b><span class="squareb">{</span>Find Without Locks <span class="squareb">[</span><span class="squareb">[</span>ALL<span class="squareb">]</span> Records<span class="squareb">]</span> <span class="squareb">|</span> FDWOL<span class="squareb">}</span><br />
<span class="squareb">[</span>In <span class="term">label</span> <span class="squareb">|</span> On <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">]</span><br />
<span class="squareb">[</span>For Which <span class="squareb">|</span> With<span class="squareb">]</span> <span class="term">[[#Retrieval condition syntax|retrieval-conditions]]</span><br />
</p><br />
<br />
===FLUSH PROCESS===<br />
<br />
<p class="syntaxUL">FLUSH PROCESS <span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> <span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span></p><br />
<br />
===FOR EACH OCCURRENCE===<br />
<br />
<p class="syntaxUL"><b><sup>(**)</sup></b>FOR <span class="squareb">{</span>EACH <span class="squareb">|</span> <span class="term">k</span><span class="squareb">}</span> <span class="squareb">{</span>OCCURRENCE <span class="squareb">|</span> OCCURRENCES<span class="squareb">}</span> <span class="term">OF fieldname</span><br />
</p><br />
<br />
===FOR EACH RECORD===<br />
<br />
<p class="syntaxUL"><b><sup>(*)</sup></b>FOR <span class="squareb">{</span>EACH <span class="squareb">|</span> <span class="term">k</span><span class="squareb">}</span> <span class="squareb">{</span>RECORD <span class="squareb">|</span> RECORDS<span class="squareb">}</span><br />
<span class="squareb">[</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">]</span><br />
IN <span class="squareb">[</span>ASCENDING <span class="squareb">|</span> DESCENDING<span class="squareb">]</span> <span class="squareb">[</span>SORTKEY<span class="squareb">]</span> ORDER <span class="squareb">[</span>BY <span class="squareb">[</span>EACH<span class="squareb">]</span> <span class="term">fieldname</span><span class="squareb">]</span><br />
<span class="squareb">[</span>FROM <span class="squareb">{</span><span class="term">value1</span> <span class="squareb">|</span> (<span class="term">expression1</span>)<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span>TO <span class="squareb">{</span><span class="term">value2</span> <span class="squareb">|</span> (<span class="term">expression2</span>)<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span>BY <span class="squareb">{</span><span class="term">%variable</span> <span class="squareb">|</span> <span class="term">literal</span><span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">[</span>OPTIMIZING FNV<span class="squareb">]</span><br />
[<span class="squareb">{</span>WHERE <span class="squareb">|</span> WITH<span class="squareb">}</span> <span class="term">[[#Retrieval condition syntax|retrieval-conditions]]</span><br />
</p><br />
<br />
===FOR EACH VALUE OF===<br />
<br />
<p class="syntaxUL"><b><sup>(*)</sup></b>FOR <span class="squareb">{</span>EACH <span class="squareb">|</span> <span class="term">k</span><span class="squareb">}</span> <span class="squareb">{</span>VALUE <span class="squareb">|</span> VALUES<span class="squareb">}</span> <span class="term">OF fieldname</span><br />
<span class="squareb">[</span>FROM <span class="squareb">{</span><span class="term">value1</span> <span class="squareb">|</span> (<span class="term">expression1</span>)<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span>TO <span class="squareb">{</span><span class="term">value2</span> <span class="squareb">|</span> (<span class="term">expression2</span>)<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span><span class="squareb">[</span>NOT<span class="squareb">]</span> LIKE <span class="term">pattern</span><span class="squareb">]</span><br />
<span class="squareb">[</span>IN <span class="squareb">[</span>ASCENDING <span class="squareb">|</span> DESCENDING<span class="squareb">]</span> <span class="squareb">[</span>CHARACTER <span class="squareb">|</span> NUMERICAL<span class="squareb">]</span> <span class="squareb">[</span>RIGHT-ADJUSTED<span class="squareb">]</span> ORDER<span class="squareb">]</span><br />
</p><br />
<br />
===FOR EACH VALUE IN===<br />
<br />
<p class="syntaxUL">FOR <span class="squareb">{</span>EACH <span class="squareb">|</span> <span class="term">k</span><span class="squareb">}</span> <span class="squareb">{</span>VALUE <span class="squareb">|</span> VALUES<span class="squareb">}</span> IN <span class="term">label</span> </p><br />
<br />
===FOR RECORD NUMBER===<br />
<br />
<p class="syntaxUL"><b><sup>(*)</sup></b>FOR RECORD NUMBER <span class="squareb">{</span><span class="term">value</span> <span class="squareb">|</span> (<span class="term">expression</span>)<span class="squareb">}</span><br />
</p><br />
<br />
===FOR RECORD NUMBER IN===<br />
<br />
<p class="syntaxUL">FOR RECORD NUMBER <span class="squareb">{</span><span class="term">value</span> <span class="squareb">|</span> IN <span class="term">label</span><span class="squareb">}</span> <span class="squareb">[</span>OPTIMIZING FNV<span class="squareb">]</span><br />
</p><br />
<br />
===[[For %i statement|For %var From %exp1 To %exp2 By %exp3]]===<br />
<br />
{{Template:For %i statement syntax}}<br />
<br />
<p class="note"><b>Note:</b> The BY clause, when omitted, defaults to a value of 1.</p><br />
<br />
===IDENTIFY===<br />
<br />
<p class="syntaxUL">IDENTIFY<br />
<span class="squareb">{</span><span class="squareb">[</span>IMAGE<span class="squareb">]</span> <span class="term">imagename</span><br />
<span class="squareb">|</span> <span class="term">%imagename</span>:<span class="term">itemname</span> LEN <span class="squareb">{</span><span class="term">n</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
<span class="squareb">|</span> <span class="term">%imagename</span>:<span class="term">arrayname</span> OCCURS <span class="squareb">{</span><span class="term">n</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><span class="squareb">}</span><br />
</p><br />
<br />
===<b id="IF...THEN...ELSE"></b>[[If statement|If]]...Then...ElseIf...Else===<br />
<br />
<p class="syntaxUL"><b><sup>(C)</sup></b>IF <span class="term">expression</span> THEN <span class="term">statements</span><br />
<span class="squareb">[</span>ELSE <span class="term">statements</span> <span class="squareb">|</span> ELSEIF <span class="term">expression</span> THEN <span class="term">statements</span><span class="squareb">]</span><br />
</p><br />
<br />
===IMAGE===<br />
<br />
<p class="syntaxUL"><span class="squareb">[</span>DECLARE<span class="squareb">]</span> IMAGE <span class="term">imagename</span><br />
<span class="squareb">[</span>GLOBAL <span class="squareb">[</span>PERMANENT <span class="squareb">|</span> TEMPORARY<span class="squareb">]</span><br />
<span class="squareb">|</span> <span class="squareb">[</span>PERMANENT <span class="squareb">|</span> TEMPORARY<span class="squareb">]</span> GLOBAL<br />
<span class="squareb">|</span> COMMON <span class="squareb">[</span>AT <span class="squareb">[</span><span class="term">itemname</span> <span class="squareb">|</span> <span class="term">imagename1</span> <span class="squareb">|</span> <span class="term">arrayname</span><span class="squareb">}</span><span class="squareb">]</span><span class="squareb">]</span><br />
</p><br />
<br />
===INCLUDE===<br />
<br />
<p class="syntaxUL"><b><sup>(*)</sup></b>INCLUDE <span class="term">procedurename</span> </p><br />
<br />
===INPUT===<br />
<br />
<p class="syntaxUL">INPUT <span class="term">inputname</span> <span class="squareb">[</span>AT <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">n</span><span class="squareb">]</span><br />
<span class="squareb">[</span>TO <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">m</span> <span class="squareb">|</span> <span class="squareb">[</span>LEN <span class="term">m</span><span class="squareb">]</span> DP <span class="squareb">{</span><span class="term">k</span> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span><span class="squareb">]</span><br />
<span class="squareb">[</span>UPCASE <span class="squareb">|</span> NOCASE<span class="squareb">]</span> <span class="squareb">[</span>DEFAULT '<span class="term">value</span>'<span class="squareb">]</span><br />
<span class="squareb">[</span>DEBLANK <span class="squareb">|</span> NODEBLANK<span class="squareb">]</span> <span class="squareb">[</span>PAD WITH '<span class="term">c</span>'<span class="squareb">]</span><br />
<span class="squareb">[</span>REQUIRED <span class="squareb">|</span> ALPHA <span class="squareb">|</span> ALPHANUM <span class="squareb">|</span> MUSTFILL<br />
<span class="squareb">|</span> ONEOF <span class="term">literal</span> <span class="squareb">[</span>, <span class="term">literal</span><span class="squareb">]</span>...<br />
<span class="squareb">|</span> <span class="squareb">[</span>NUMERIC<span class="squareb">]</span> <span class="squareb">[</span>RANGE <span class="term">lo</span> <span class="squareb">[</span>TO<span class="squareb">]</span> <span class="term">hi</span> <span class="squareb">[</span>AND <span class="term">lo</span> <span class="squareb">[</span>TO<span class="squareb">]</span> <span class="term">hi</span><span class="squareb">]</span> ...<span class="squareb">]</span><br />
<span class="squareb">|</span> VERIFY '<span class="term">characters</span>'<span class="squareb">]</span>...<br />
<span class="squareb">[</span><span class="squareb">[</span>READ<span class="squareb">]</span> <span class="term">attributes</span><span class="squareb">]</span> <span class="squareb">[</span>REREAD <span class="term">attributes</span><span class="squareb">]</span> <span class="squareb">[</span>PRINT <span class="term">attributes</span><span class="squareb">]</span><br />
<span class="squareb">[</span>TAG <span class="squareb">[</span><span class="term">attributes</span><span class="squareb">]</span> <span class="squareb">[</span>WITH '<span class="term">c</span>'<span class="squareb">]</span><span class="squareb">]</span> <span class="squareb">[</span>ITEMID <span class="term">n</span><span class="squareb">]</span><br />
</p><br />
<br />
===INSERT===<br />
<br />
<p class="syntaxUL">INSERT <span class="term">fieldname</span> <span class="squareb">[</span>(<span class="term">subscript</span>)<span class="squareb">]</span> = <span class="squareb">{</span><span class="term">value</span> <span class="squareb">|</span> (<span class="term">expression</span>)<span class="squareb">}</span><br />
</p><br />
<br />
===[[Horizon SOUL interface#Invite statement|Invite]]===<br />
<br />
{{Template:Invite statement syntax}}<br />
<br />
===IS===<br />
<br />
<p class="syntaxUL"><span class="term">itemname</span> IS <span class="squareb">[</span>TYPE<span class="squareb">]</span><br />
<span class="squareb">{</span>STRING <span class="squareb">|</span> BINARY <span class="squareb">|</span> PACKED <span class="squareb">|</span> ZONED <span class="squareb">|</span> FLOAT <span class="squareb">|</span> EFORMAT<span class="squareb">}</span><br />
<span class="squareb">{</span>LEN <span class="squareb">{</span><span class="term">n</span> <span class="squareb">|</span> UNKNOWN<span class="squareb">}</span> <span class="squareb">|</span> BITS <span class="term">n</span> <span class="squareb">|</span> DIGITS <span class="term">n</span><br />
<span class="squareb">|</span> TO <span class="term">position</span><span class="squareb">}</span><br />
<span class="squareb">[</span>DP <span class="squareb">{</span><span class="term">k</span> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span>BP <span class="term">n</span><span class="squareb">]</span> <span class="squareb">[</span>SIGNED <span class="squareb">|</span> UNSIGNED<span class="squareb">]</span><br />
<span class="squareb">[</span>PAD <span class="squareb">{</span>BLANK <span class="squareb">|</span> <span class="term">character</span> <span class="squareb">|</span> NULL<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span>STRIP <span class="squareb">|</span> NOSTRIP<span class="squareb">]</span><br />
<span class="squareb">[</span>ALIGN<span class="squareb">]</span><br />
<span class="squareb">[</span>JUSTIFY <span class="squareb">{</span>LEFT <span class="squareb">|</span> RIGHT<span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">[</span>INITIAL <span class="squareb">{</span>BLANK <span class="squareb">|</span> ZERO <span class="squareb">|</span> NULL <span class="squareb">|</span> <span class="term">value</span><span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">[</span>AFTER <span class="squareb">{</span><span class="term">itemname</span> <span class="squareb">|</span> <span class="term">arrayname</span><span class="squareb">}</span><br />
<span class="squareb">|</span> AT <span class="squareb">{</span><span class="term">position</span> <span class="squareb">|</span> <span class="term">itemname</span> <span class="squareb">|</span> <span class="term">imagename1</span> <span class="squareb">|</span> <span class="term">arrayname</span><span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">[</span>OCCURS <span class="squareb">{</span><span class="term">n</span> <span class="squareb">[</span>DEPENDING ON <span class="squareb">{</span><span class="term">itemname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">|</span> UNKNOWN<span class="squareb">}</span><span class="squareb">]</span><br />
</p><br />
<br />
===JUMP TO===<br />
<br />
<p class="syntaxUL">JUMP TO <span class="term">label</span><br />
<br />
JUMP TO (<span class="term">label1</span> <span class="squareb">[</span>, <span class="term">label2</span><span class="squareb">]</span> ...) <span class="term">expression</span></p><br />
<br />
===[[Flow_of_control_in_User_Language#LOOP_END_statement|Loop End]]===<br />
<br />
<p class="syntaxUL">Loop End </p><br />
<br />
===[[Loop Next statement|Loop Next]]===<br />
<br />
<p class="syntaxUL">Loop Next</p><br />
<br />
===MAX PFKEY===<br />
<br />
<p class="syntaxUL">MAX PFKEY <span class="term">n</span> </p><br />
<br />
===<b id="MENU"></b>[[Menu statement or block|Menu]]===<br />
<br />
{{Template: Menu statement syntax}}<br />
<br />
===MODIFY===<br />
<br />
<p class="syntaxUL">MODIFY <span class="squareb">{</span><span class="term">%menuname</span>:<span class="term">itemname</span> <span class="squareb">|</span> <span class="term">%screenname</span>:<span class="term">itemname</span><span class="squareb">}</span><br />
<span class="squareb">[</span>TO<span class="squareb">]</span> <span class="term">attributes</span> <span class="squareb">[</span><span class="squareb">[</span>FOR<span class="squareb">]</span> <span class="squareb">{</span>ALL <span class="squareb">|</span> READ <span class="squareb">|</span> REREAD <span class="squareb">|</span> TAB<br />
<span class="squareb">|</span> PRINT<span class="squareb">}</span><span class="squareb">]</span><br />
</p><br />
<br />
===MODIFY BUFFER===<br />
<br />
<p class="syntaxUL">MODIFY BUFFER <span class="squareb">[</span>SIZE=<span class="term">n</span><br />
<span class="squareb">|</span> <span class="term">%variable</span> <span class="squareb">[</span>PRESERVE <span class="squareb">|</span> NOPRESERVE<span class="squareb">]</span><span class="squareb">]</span><br />
<span class="squareb">[</span>FILL <span class="squareb">[</span>X'<span class="term">nn</span>'<span class="squareb">]</span> <span class="squareb">|</span> CLEAR<span class="squareb">]</span><br />
</p><br />
<br />
===NEW PAGE===<br />
<br />
<p class="syntaxUL"><b><sup>(C)</sup></b>NEW PAGE </p><br />
<br />
===[[Note statement|Note]]===<br />
<br />
<p class="syntaxUL"><b><sup>(**)</sup></b>Note <span class="squareb">{</span><span class="term">fieldname</span> <span class="squareb">[</span>(<span class="term">subscript</span>)<span class="squareb">]</span><span class="squareb">}</span><br />
<br />
Note '<span class="term">string</span>' </p><br />
<br />
===[[On statement|On]]===<br />
<br />
<p class="syntaxUL">[[On statement|On]] <span class="squareb">{</span>Attention <span class="squareb">|</span> Error <span class="squareb">|</span> Field Constraint Conflict<br />
<span class="squareb">|</span> Find Conflict <span class="squareb">|</span> Missing File <span class="squareb">|</span> Missing Member<br />
<span class="squareb">|</span> Record Locking Conflict<span class="squareb">}</span><br />
<span class="term">statements</span><br />
End On <span class="squareb">[</span><span class="term">label</span><span class="squareb">]</span><br />
</p><br />
<br />
===Open===<br />
<br />
{{Template:Open (External I/O) statement syntax}}<br />
<br />
<p></p> <!--Don't ask me why!--><br />
<br />
{{Template:Open and OpenC statements syntax}}<br />
<br />
===OPEN PROCESS===<br />
<br />
<p class="syntaxUL">OPEN PROCESS <span class="squareb">{</span><span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
<span class="squareb">[</span>CID <span class="squareb">{</span><span class="term">name</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><span class="squareb">]</span><br />
<br />
<b><sup>(+)</sup></b>OPEN PROCESS <span class="squareb">{</span><span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
<span class="squareb">[</span>CID <span class="squareb">{</span><span class="term">name</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">{</span><span class="term">outbound-options</span> <span class="squareb">|</span> <span class="term">inbound-options</span><span class="squareb">}</span><br />
</p><br />
<br />
<div style="margin-left: 20px; background-color: #fBfBfB;"><br />
<p><br />
where <var class="term">outbound-options</var> are:</p><br />
<ul style="font-family: Consolas,monospace"><br />
<li><span class="squareb">[</span>AT DESTINATION<span class="squareb">]</span> <span class="squareb">[</span>WITH<span class="squareb">]</span> <span class="squareb">[</span>USERID <span class="squareb">{</span><i>%variable</i> <span class="squareb">|</span> '<i>string</i>'<span class="squareb">}</span><span class="squareb">]</span><br />
<br />
<li><span class="squareb">[</span>PASSWORD <span class="squareb">{</span><i>%variable</i> <span class="squareb">|</span> '<i>string</i>'<span class="squareb">}</span><span class="squareb">]</span><br />
<br />
<li>[<span class="squareb">{</span>ACCOUNT <span class="squareb">|</span> PROFILE <span class="squareb">{</span>%<i>%variable</i> <span class="squareb">|</span> '<i>string</i>'<span class="squareb">}</span><span class="squareb">]</span><br />
<br />
<li><span class="squareb">[</span>INITIAL <span class="squareb">{</span>DATA '<i>string</i>' <span class="squareb">|</span> DATA <i>%variable</i> <span class="squareb">|</span> IMAGE <i>imagename</i><span class="squareb">]</span> ...<span class="squareb">]</span><br />
</ul><br />
<br />
<p><br />
and <var class="term">inbound-options</var> are:</p><br />
<br />
<ul style="font-family: Consolas,monospace"><br />
<li>ACCEPT <span class="squareb">[</span>INITIAL <span class="squareb">{</span>DATA <i>%variable</i> <span class="squareb">|</span> IMAGE <i>image</i><span class="squareb">}</span> ...<span class="squareb">]</span> </li><br />
</ul><br />
<br />
</div> <!-- end indent of options --><br />
<br />
===[[Pause statement|Pause]]===<br />
<br />
{{Template:Pause statement syntax}}<br />
<br />
===PLACE RECORD ON===<br />
<br />
<p class="syntaxUL"><b><sup>(**)</sup></b>[[Lists#PLACE RECORD and REMOVE RECORD statements|PLACE RECORD ON]] <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><br />
</p><br />
<br />
===PLACE RECORDS===<br />
<br />
<p class="syntaxUL">PLACE RECORDS <span class="squareb">{</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname1</span><span class="squareb">}</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname2</span><br />
</p><br />
<br />
===POSITION===<br />
<br />
<p class="syntaxUL">POSITION <span class="squareb">{</span>FOUNDSET <span class="term">foundsortset_name</span> <span class="squareb">|</span> LIST <span class="term">list_name</span><span class="squareb">}</span> <span class="squareb">[</span>AT<span class="squareb">]</span> <span class="term">position_name</span></p><br />
<br />
<p class="note"><b>Note:</b> Use this form of the POSITION statement with FOR loop processing; see [[Global features#POSITION statement|POSITION statement]].</p><br />
<br />
<p class="syntaxUL">POSITION <span class="squareb">{</span><span class="term">ext-filename</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
AT KEY <span class="term">operator</span><span class="squareb">{</span><span class="term">value</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span></p><br />
<br />
<p class="note"><b>Note:</b> Use this form of the POSITION statement with external file processing using images; see [[Images#POSITION statement|POSITION statement]].</p><br />
<br />
===[[Full-screen feature|PREPARE]]===<br />
<br />
<p class="syntaxUL">PREPARE<br />
<span class="squareb">{</span><span class="squareb">[</span>[[Images#PrepareStmtImage|IMAGE]]<span class="squareb">]</span> <span class="term">imagename</span> <span class="squareb">|</span> <span class="squareb">[</span>[[Full-screen feature#PrepareStmtMenu|MENU]]<span class="squareb">]</span> <span class="term">menuname</span><br />
<span class="squareb">|</span> <span class="squareb">[</span>[[Full-screen feature#PrepareStmtScrn|SCREEN]]<span class="squareb">]</span> <span class="term">screenname</span><span class="squareb">}</span><br />
</p><br />
<br />
===Print===<br />
<br />
<p class="syntaxUL">Print <span class="term">[[#Print specification syntax|printSpecifications]]</span> </p><br />
<br />
===Print All Fieldgroup Information (PAFGI)===<br />
{{Template:PAFGI statement syntax}} <br />
<br />
===[[Print All Information statement|Print All Information]] or [[PAI statement|PAI]]===<br />
<br />
{{Template:PAI statement syntax}}<br />
<br />
===PRINT MENU===<br />
<br />
<p class="syntaxUL">PRINT <span class="squareb">[</span>MENU<span class="squareb">]</span> <span class="term">menuname</span> <span class="squareb">[</span>ALERT<span class="squareb">]</span><br />
<span class="squareb">[</span>TITLE <span class="squareb">{</span>'<span class="term">text</span>' <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> <span class="squareb">[</span>AT <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">n</span><span class="squareb">]</span><br />
<span class="squareb">[</span>TO <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">m</span> <span class="squareb">|</span> LEN <span class="term">m</span><span class="squareb">]</span> <span class="squareb">[</span><span class="term">attributes</span><span class="squareb">]</span><span class="squareb">]</span><br />
</p><br />
<br />
===PRINT SCREEN===<br />
<br />
<p class="syntaxUL">PRINT SCREEN <span class="term">screenname</span> <span class="squareb">[</span>ALERT<span class="squareb">]</span> <span class="squareb">[</span><span class="squareb">[</span>WITH<span class="squareb">]</span> CURSOR<span class="squareb">]</span><br />
<span class="squareb">[</span>TITLE <span class="squareb">{</span>'<span class="term">text</span>' <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> <span class="squareb">[</span>AT <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">n</span><span class="squareb">]</span><br />
<span class="squareb">[</span>TO <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">m</span> <span class="squareb">|</span> LEN <span class="term">m</span><span class="squareb">]</span> <span class="squareb">[</span><span class="term">attributes</span><span class="squareb">]</span><span class="squareb">]</span><br />
</p><br />
<br />
===[[Horizon SOUL interface#Query Process statement|Query Process]]===<br />
<br />
{{Template:Query Process statement syntax}}<br />
<br />
===<b id="READ"></b>[[Read Image statement|Read Image]]===<br />
<br />
{{Template:Read Image statement syntax}}<br />
<br />
===READ <i>menuname</i>===<br />
<br />
<p class="syntaxUL">READ <span class="squareb">[</span>MENU<span class="squareb">]</span> <span class="term">menuname</span> <span class="squareb">[</span>ALERT<span class="squareb">]</span><br />
<span class="squareb">[</span>TITLE <span class="squareb">[</span>'<span class="term">text</span>' <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> <span class="squareb">[</span>AT <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">n</span><span class="squareb">]</span><br />
<span class="squareb">[</span>TO <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">m</span> <span class="squareb">|</span> LEN <span class="term">m</span><span class="squareb">]</span> <span class="squareb">[</span><span class="term">attributes</span><span class="squareb">]</span><span class="squareb">]</span><br />
</p><br />
<br />
===READ <i>screenname</i>===<br />
<br />
<p class="syntaxUL">READ <span class="squareb">[</span>SCREEN<span class="squareb">]</span> <span class="term">screenname</span> <span class="squareb">[</span>ALERT<span class="squareb">]</span> <span class="squareb">[</span>NO REREAD<span class="squareb">]</span> <span class="squareb">[</span> <span class="squareb">[</span>WITH<span class="squareb">]</span> CURSOR<span class="squareb">]</span><br />
<span class="squareb">[</span>TITLE <span class="squareb">{</span>'<span class="term">text</span>' <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> <span class="squareb">[</span>AT <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">n</span><span class="squareb">]</span><br />
<span class="squareb">[</span>TO <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">m</span> <span class="squareb">|</span> LEN <span class="term">m</span><span class="squareb">]</span> <span class="squareb">[</span><span class="term">attributes</span><span class="squareb">]</span><span class="squareb">]</span><br />
</p><br />
<br />
===RECEIVE IMAGE===<br />
<br />
<p class="syntaxUL">RECEIVE <span class="squareb">{</span>IMAGE <span class="term">imagename</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
FROM <span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> <span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> <span class="squareb">[</span>RESULT <span class="term">%variable</span><span class="squareb">]</span><br />
<br />
<b><sup>(+)</sup></b>RECEIVE <span class="squareb">{</span>IMAGE <span class="term">imagename</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
FROM <span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> <span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
RESULT <span class="term">%variable</span><br />
</p><br />
<br />
===[[Release All Records statement|Release All Records]]===<br />
<br />
{{Template:Release All Records statement syntax}}<br />
<br />
===RELEASE POSITION===<br />
<br />
<p class="syntaxUL">RELEASE POSITION <span class="squareb">{</span><span class="term">ext-filename</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
</p><br />
<br />
===[[Release Records statement|Release Records]]===<br />
<br />
{{Template:Release Records statement syntax}}<br />
<br />
===REMEMBER===<br />
<br />
<p class="syntaxUL"><b><sup>(**)</sup></b>REMEMBER <span class="squareb">[</span>GLOBAL<span class="squareb">]</span> <span class="term">position_name</span><br />
<span class="squareb">[</span>IN <span class="term">foundsortset_name</span> <span class="squareb">|</span> ON <span class="term">list_name</span><span class="squareb">]</span><br />
</p><br />
<br />
===REMOVE RECORD FROM===<br />
<br />
<p class="syntaxUL"><b><sup>(**)</sup></b>[[Lists#PLACE RECORD and REMOVE RECORD statements|REMOVE RECORD FROM]] <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><br />
</p><br />
<br />
===REMOVE RECORDS===<br />
<br />
<p class="syntaxUL">REMOVE RECORDS <span class="squareb">{</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">}</span><br />
FROM <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname2</span><br />
</p><br />
<br />
===REPEAT===<br />
<br />
<p class="syntaxUL">REPEAT <span class="squareb">[</span>FOREVER <span class="squareb">|</span> <span class="term">n</span> TIMES <span class="squareb">|</span> WHILE <span class="term">expression</span><span class="squareb">]</span><br />
</p><br />
<br />
===REREAD===<br />
<br />
<p class="syntaxUL">REREAD <span class="squareb">[</span>SCREEN<span class="squareb">]</span> <span class="term">screenname</span> <span class="squareb">[</span>ALERT<span class="squareb">]</span> <span class="squareb">[</span><span class="squareb">[</span>WITH<span class="squareb">]</span> CURSOR<span class="squareb">]</span><br />
<span class="squareb">[</span>TITLE <span class="squareb">{</span>'<span class="term">text</span>' <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> <span class="squareb">[</span>AT <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">n</span><span class="squareb">]</span><br />
<span class="squareb">[</span>TO <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">m</span> <span class="squareb">|</span> LEN <span class="term">m</span><span class="squareb">]</span> <span class="squareb">[</span><span class="term">attributes</span><span class="squareb">]</span><span class="squareb">]</span><br />
</p><br />
<br />
===RESET===<br />
<br />
<p class="syntaxUL">RESET <span class="squareb">{</span>HEADER <span class="squareb">|</span> TRAILER<span class="squareb">}</span> <span class="term">m</span><br />
</p><br />
<br />
===RETRY===<br />
<br />
<p class="syntaxUL">RETRY <span class="squareb">[</span>PENDING STATEMENT<span class="squareb">]</span><br />
</p><br />
<br />
===RETURN===<br />
<br />
<p class="syntaxUL">RETURN<br />
</p><br />
<br />
===<b id="SCREEN"></b>[[Screen statement or block|Screen]]===<br />
<br />
{{Template:Screen statement syntax}}<br />
<br />
===SEND===<br />
<br />
<p class="syntaxUL">SEND <span class="squareb">{</span>IMAGE <span class="term">imagename</span> <span class="squareb">|</span> '<span class="term">string</span>' <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
TO <span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> <span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
<span class="squareb">[</span>REQSEND <span class="term">%variable</span><span class="squareb">]</span><br />
<span class="squareb">[</span>FLUSH<span class="squareb">]</span><br />
<br />
<br />
<b><sup>(+)</sup></b>SEND <span class="squareb">{</span>IMAGE <span class="term">imagename</span> <span class="squareb">|</span> '<span class="term">string</span>' <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
TO <span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> <span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
<span class="squareb">[</span>FLUSH <span class="squareb">|</span> CONFIRM<span class="squareb">]</span><br />
<span class="squareb">[</span>REQSEND <span class="term">%variable</span><span class="squareb">]</span><br />
</p><br />
<br />
===[[Horizon SOUL interface#Send Error statement|Send Error]]===<br />
<br />
{{Template:Send Error statement syntax}}<br />
<br />
===SET===<br />
<br />
<p class="syntaxUL">SET <span class="squareb">{</span>HEADER <span class="squareb">|</span> TRAILER<span class="squareb">}</span> <span class="term">m</span> <span class="term">[[#Print specification syntax|print-specifications]]</span><br />
</p><br />
<br />
===[[SetText statement|SetText]]===<br />
<br />
{{Template:SetText statement syntax}}<br />
<br />
===SIGNAL PROCESS===<br />
<br />
<p class="syntaxUL">SIGNAL PROCESS<br />
<span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> [<span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> <span class="squareb">{</span><span class="term">nnn</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
<br />
<b><sup>(+)</sup></b>SIGNAL PROCESS<br />
<span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> [<span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
</p><br />
<br />
===SKIP LINES===<br />
<br />
<p class="syntaxUL">SKIP <span class="term">n</span> LINE<span class="squareb">[</span>S<span class="squareb">]</span><br />
</p><br />
<br />
===SKIP POSITIONS===<br />
<br />
<p class="syntaxUL">[<span class="term">itemname</span> IS<span class="squareb">]</span> SKIP <span class="term">n</span> POSITION<span class="squareb">[</span>S<span class="squareb">]</span><br />
<span class="squareb">[</span>INITIAL <span class="squareb">{</span>NULL <span class="squareb">|</span> <span class="term">character</span> <span class="squareb">|</span> BLANK<span class="squareb">}</span><span class="squareb">]</span><br />
</p><br />
<br />
===SORT RECORDS===<br />
<br />
<p class="syntaxUL">SORT [<span class="term">k</span><span class="squareb">]</span> RECORDS <span class="squareb">{</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">}</span><br />
BY <span class="term">key</span> <span class="squareb">[</span>AND <span class="term">key</span><span class="squareb">]</span> ...<br />
</p><br />
<br />
<div style="margin-left: 20px; background-color: #fBfBfB;"><br />
<p><br />
where <var class="term">key</var> is:</p><br />
<ul style="font-family: Consolas,monospace"><br />
<li><i>key</i> = <i>fieldname</i> <br><br />
<span class="squareb">[</span>VALUE <span class="squareb">{</span><span class="squareb">[</span>ASCENDING <span class="squareb">|</span> DESCENDING<span class="squareb">]</span> <br><br />
<span class="squareb">[</span>CHARACTER <span class="squareb">|</span> NUMERICAL<span class="squareb">]</span> <span class="squareb">|</span> RIGHT-ADJUSTED<span class="squareb">]</span><span class="squareb">}</span> ...<span class="squareb">]</span> </li><br />
</ul><br />
<br />
</div> <!--end key indent --><br />
<br />
===SORT RECORD KEYS===<br />
<br />
<p class="syntaxUL">SORT [<span class="term">k</span><span class="squareb">]</span> RECORD KEYS<br />
<span class="squareb">{</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="squareb">[</span>LIST<span class="squareb">]</span> <span class="term">listname</span><span class="squareb">}</span><br />
BY <span class="term">key</span> <span class="squareb">[</span>AND <span class="term">key</span><span class="squareb">]</span> ...<br />
</p><br />
<br />
<div style="margin-left: 20px; background-color: #fBfBfB;"><br />
<p><br />
where <var class="term">key</var> is:</p><br />
<ul style="font-family: Consolas,monospace"><br />
<li><i>key</i> = <i>fieldname</i> <br><br />
<span class="squareb">[</span>VALUE <span class="squareb">{</span><span class="squareb">[</span>ASCENDING <span class="squareb">|</span> DESCENDING<span class="squareb">]</span> <br><br />
<span class="squareb">[</span>CHARACTER <span class="squareb">|</span> NUMERICAL<span class="squareb">]</span> <span class="squareb">|</span> <span class="squareb">[</span>RIGHT-ADJUSTED<span class="squareb">]</span><span class="squareb">}</span> ...<span class="squareb">]</span> </li><br />
</ul><br />
<br />
</div><br />
<br />
===SORT VALUE IN===<br />
<br />
<p class="syntaxUL">SORT VALUE IN <span class="term">label</span> <span class="squareb">[</span>IN <span class="squareb">[</span>ASCENDING <span class="squareb">|</span> DESCENDING<span class="squareb">]</span><br />
[<u>CHARACTER</u> <span class="squareb">|</span> NUMERICAL<span class="squareb">]</span> <span class="squareb">|</span> <span class="squareb">[</span>RIGHT-ADJUSTED<span class="squareb">]</span> ORDER<span class="squareb">]</span><br />
</p><br />
<br />
===STOP===<br />
<br />
<p class="syntaxUL">STOP <span class="squareb">[</span>IF COUNT IN <span class="term">label</span> EXCEEDS <span class="term">n</span><span class="squareb">]</span><br />
</p><br />
<br />
===STORE RECORD===<br />
<br />
<p class="syntaxUL"><b><sup>(*)</sup></b>STORE RECORD [<span class="term">sort or hash key value</span><span class="squareb">]</span><br />
<span class="term">fieldname1</span>=[<span class="term">value1</span> <span class="squareb">|</span> (<span class="term">expression1</span>)<span class="squareb">]</span><br />
[<span class="term">fieldname2</span>=(<span class="term">expression</span>)<span class="squareb">]</span><br />
...<br />
<span class="squareb">[</span>THEN CONTINUE<br />
<span class="term">statement</span><br />
<span class="term">statement</span><br />
...<span class="squareb">]</span><br />
END STORE<br />
</p><br />
<br />
===SUBROUTINE===<br />
<br />
<p class="syntaxUL">SUBROUTINE<br />
<br />
SUBROUTINE <span class="term">subname</span><br />
<span class="squareb">[</span>(<span class="term">formal-parameter</span> <span class="squareb">[</span>INPUT <span class="squareb">|</span> OUTPUT <span class="squareb">|</span> INPUT OUTPUT<span class="squareb">]</span> <span class="squareb">[</span>,...<span class="squareb">]</span>)<span class="squareb">]</span><br />
</p><br />
<br />
<div style="margin-left: 20px; background-color: #fBfBfB;"><br />
<p><br />
where <var class="term">formal-parameter</var> is one of the following:</p><br />
<ul style="font-family: Consolas,monospace"><br />
<li><i>%variable</i> <span class="squareb">[</span>IS STRING <span class="squareb">[</span>LEN <i>n</i><span class="squareb">]</span> <span class="squareb">[</span>DP <span class="squareb">{</span><i>n</i> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span>ARRAY (*<span class="squareb">[</span>,*<span class="squareb">[</span>,*<span class="squareb">]</span><span class="squareb">]</span>) <span class="squareb">[</span>NO FS<span class="squareb">]</span><span class="squareb">]</span> <br><br />
<span class="squareb">|</span> IS <span class="squareb">{</span>FIXED <span class="squareb">[</span>DP <i>n</i><span class="squareb">]</span> <span class="squareb">|</span> FLOAT<span class="squareb">}</span> <span class="squareb">[</span>ARRAY (*<span class="squareb">[</span>,*<span class="squareb">[</span>,*<span class="squareb">]</span><span class="squareb">]</span>)<span class="squareb">]</span><span class="squareb">]</span><br />
<br />
<li>LIST <i>listname</i> <span class="squareb">[</span>IN <span class="squareb">[</span>FILE <span class="squareb">|</span> <span class="squareb">[</span>PERM <span class="squareb">|</span> TEMP<span class="squareb">]</span> GROUP<span class="squareb">]</span> <i>name</i><span class="squareb">]</span><br />
</ul><br />
</div><br />
<br />
===TAG===<br />
<br />
<p class="syntaxUL">TAG <span class="term">%screenname</span>:<span class="term">inputname</span> <span class="squareb">[</span><span class="term">attributes</span><span class="squareb">]</span> <span class="squareb">[</span>WITH 'c'<span class="squareb">]</span><br />
</p><br />
<br />
===[[Horizon SOUL interface#Test Receipt statement|Test Receipt]]===<br />
<br />
{{Template:Test Receipt statement syntax}}<br />
<br />
===TITLE===<br />
<br />
<p class="syntaxUL">TITLE <span class="squareb">{</span>'<span class="term">text</span>' <span class="squareb">|</span> <span class="term">promptname</span><span class="squareb">}</span><br />
<span class="squareb">[</span>AT <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">n</span><span class="squareb">]</span> <span class="squareb">[</span>TO <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">m</span> <span class="squareb">|</span> <span class="squareb">[</span>LEN <span class="term">m</span><span class="squareb">]</span><br />
<span class="squareb">[</span>DP <span class="squareb">{</span><span class="term">k</span> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span><span class="squareb">]</span><br />
<span class="squareb">[</span>DEFAULT '<span class="term">value</span>'<span class="squareb">]</span><br />
<span class="squareb">[</span><span class="squareb">[</span>READ<span class="squareb">]</span> <span class="term">attributes</span><span class="squareb">]</span> <span class="squareb">[</span>REREAD <span class="term">attributes</span><span class="squareb">]</span> <span class="squareb">[</span>PRINT <span class="term">attributes</span><span class="squareb">]</span><br />
</p><br />
<br />
===<b id="trace"></b>[[Trace statement|Trace]]===<br />
<br />
{{Template:Trace statement syntax}}<br />
<br />
<p class="note"><b>Note:</b> The output of the <var>Trace</var> statement is controlled by the <var>[[ULTRACE parameter|ULTRACE]]</var> parameter.</p><br />
<br />
===TRANSFER===<br />
<br />
<p class="syntaxUL">TRANSFER <span class="squareb">[</span>CONTROL<span class="squareb">]</span> TO PROCESS <span class="squareb">{</span><span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
<span class="squareb">[</span>WITH<span class="squareb">]</span> <span class="squareb">[</span>USERID <span class="squareb">{</span><span class="term">string</span> <span class="squareb">|</span> '<span class="term">%variable</span>'<span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">[</span>PASSWORD <span class="squareb">{</span><span class="term">variable</span> <span class="squareb">|</span> '<span class="term">string</span>'<span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">[</span>ACCOUNT <span class="squareb">{</span><span class="term">%variable</span> <span class="squareb">|</span> '<span class="term">string</span>'<span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">[</span>PASSING <span class="squareb">{</span>IMAGE <span class="term">imagename</span> <span class="squareb">|</span> '<span class="term">string</span>' <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><span class="squareb">]</span><br />
</p><br />
<br />
===UPDATE RECORD===<br />
<br />
<p class="syntaxUL">UPDATE RECORD</p><br />
<br />
===VARIABLES ARE===<br />
<br />
<p class="syntaxUL">VARIABLES ARE<br />
<span class="squareb">{</span>FIXED <span class="squareb">[</span>DP <span class="term">n</span><span class="squareb">]</span> <span class="squareb">|</span> FLOAT<br />
<span class="squareb">|</span> STRING <span class="squareb">[</span>LEN <span class="term">n</span><span class="squareb">]</span> <span class="squareb">[</span>DP <span class="squareb">{</span><span class="term">n</span> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">|</span> UNDEFINED<span class="squareb">}</span><br />
</p><br />
<br />
===Declare <i>%variable</i>===<br />
<br />
<p class="syntaxUL"><span class="squareb">[</span>DECLARE<span class="squareb">]</span> <span class="term">%variable</span> <span class="squareb">[</span>IS<span class="squareb">]</span><br />
<span class="squareb">{</span>FIXED <span class="squareb">[</span>DP <span class="term">n</span><span class="squareb">]</span> <span class="squareb">|</span> FLOAT<span class="squareb">}</span> <span class="squareb">[</span>ARRAY (<span class="term">d1</span><span class="squareb">[</span>,<span class="term">d2</span><span class="squareb">[</span>,<span class="term">d3</span><span class="squareb">]</span><span class="squareb">]</span>)<span class="squareb">]</span><br />
<span class="squareb">[</span>COMMON<span class="squareb">]</span><br />
<br />
<span class="squareb">[</span>DECLARE<span class="squareb">]</span> <span class="term">%variable</span> <span class="squareb">[</span>IS<span class="squareb">]</span><br />
STRING <span class="squareb">[</span>LEN <span class="term">n</span><span class="squareb">]</span> <span class="squareb">[</span>DP <span class="squareb">{</span><span class="term">n</span> <span class="squareb">|</span> *<span class="squareb">}</span><span class="squareb">]</span> <span class="squareb">[</span>ARRAY (<span class="term">d1</span><span class="squareb">[</span>,<span class="term">d2</span>[<span class="term">d3</span><span class="squareb">]</span><span class="squareb">]</span>)<span class="squareb">]</span><br />
<span class="squareb">[</span>NO FIELD SAVE<span class="squareb">]</span> <span class="squareb">[</span>COMMON<span class="squareb">]</span><br />
<span class="term">%variable</span> <span class="squareb">[</span>(<span class="term">subscript</span>)<span class="squareb">]</span> = <span class="term">expression</span><br />
</p><br />
<br />
===WAIT===<br />
<br />
<p class="syntaxUL"><b><sup>(+)</sup></b>WAIT [<span class="squareb">{</span><span class="term">n</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span> SEC<span class="squareb">[</span>S<span class="squareb">]</span><span class="squareb">]</span> <span class="squareb">[</span>FOR<span class="squareb">]</span><br />
<span class="squareb">{</span>ANY RECEIPT RETURN <span class="term">%variable</span><br />
<span class="squareb">|</span> RECEIPT <span class="squareb">{</span><span class="term">cid</span> <span class="squareb">|</span> <span class="term">processname</span> <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><span class="squareb">}</span><br />
</p><br />
<br />
===WRITE===<br />
<br />
<p class="syntaxUL">WRITE <span class="squareb">[</span>IMAGE<span class="squareb">]</span> <span class="term">imagename</span><br />
ON <span class="squareb">{</span><span class="term">seq-filename</span> <span class="squareb">|</span> TERMINAL <span class="squareb">|</span> <span class="term">%variable</span><span class="squareb">}</span><br />
</p><br />
<br />
===WRITE IMAGE===<br />
<br />
<p class="syntaxUL">WRITE IMAGE <span class="term">imagename</span> ON BUFFER<br />
<span class="squareb">[</span>POSITION=<span class="term">%pvariable</span> <span class="squareb">|</span> <span class="term">n</span><span class="squareb">]</span> <span class="squareb">[</span>MAXLEN=<span class="squareb">{</span><span class="term">%lvariable</span> <span class="squareb">|</span> <span class="term">n</span><span class="squareb">}</span><span class="squareb">]</span><br />
</p><br />
<br />
==Other syntax==<br />
<br />
===<b id="tokens"></b>Names, numbers, literals, comments===<br />
<br />
<ul><br />
<li>Names (for example, %variables, labels): see [[Model 204 naming conventions]]<br />
<li>Other constructs: see [[Basic request structure]] (which also discusses some rules for statement labels)<br />
</ul><br />
<br />
===Value specification syntax===<br />
<p><br />
For all User Language statements and retrieval conditions, wherever the term <var class="term">value</var> appears in the syntax, it can be any of these:</p><br />
<ul><br />
<li>Literal number or string </li><br />
<li><var>VALUE IN</var> clause of the form:<br />
<p class="syntax">VALUE <span class="squareb">[</span>IN<span class="squareb">]</span> <span class="term">label</span><br />
</p><br />
</li><br />
<li>%variable</li><br />
</ul><br />
<br />
===Retrieval condition syntax===<br />
<p><br />
A <var>FIND</var> statement can be followed by any number of retrieval conditions separated by an end of line or [[LINEND parameter]] character.</p><br />
<p><br />
Conditions can be constructed as follows: </p><br />
<br />
=====Syntax=====<br />
<p class="syntax">[NOT] <span class="term">phrase</span> [<span class="squareb">{</span>AND <span class="squareb">|</span> OR <span class="squareb">|</span> NOR<span class="squareb">}</span> [NOT] <span class="term">phrase</span>] ...<br />
</p><br />
Where:<br />
<p><br />
<var class="term">phrase</var> can be constructed as follows:</p><br />
<ul style="font-family: Consolas,monospace"><br />
<li><i>fieldname</i> = <span class="squareb">[</span>NOT<span class="squareb">]</span> <i>value</i><br />
<br />
<li><i>fieldname</i> LIKE <i>pattern</i><br />
<br />
<li><i>fieldname</i> IS [NOT] <span class="squareb">{</span>PRESENT <span class="squareb">|</span> LIKE '<i>pattern</i>'<span class="squareb">}</span><br />
<br />
<li><i>fieldname</i> IS [NOT] <span class="squareb">{</span>[NUMERICALLY <span class="squareb">|</span> ALPHABETICALLY] <br><br />
[EQ <span class="squareb">|</span> = <span class="squareb">|</span> NE <span class="squareb">|</span> ,= <span class="squareb">|</span> GREATER THAN <span class="squareb">|</span> GT <span class="squareb">|</span> > <br><br />
<span class="squareb">|</span> LESS THAN <span class="squareb">|</span> LT < <span class="squareb">|</span> <= <span class="squareb">|</span> GE <span class="squareb">|</span> >= <span class="squareb">|</span> BEFORE <span class="squareb">|</span> AFTER] <i>value</i><span class="squareb">}</span><br />
<br />
<li><i>fieldname</i> IS [NOT] <span class="squareb">{</span>[NUMERICALLY <span class="squareb">|</span> ALPHABETICALLY] <br><br />
<span class="squareb">{</span>IN RANGE [FROM <span class="squareb">|</span> AFTER] <i>value1</i> <span class="squareb">{</span>TO <span class="squareb">|</span> [AND] BEFORE<span class="squareb">}</span> <br><br />
<i>value2</i> <span class="squareb">|</span> BETWEEN <i>value1</i> AND <i>value2</i><span class="squareb">}</span><br />
<br />
<li>FILES <i>filename</i><br />
<br />
<li>FIND$ <i>label</i><br />
<br />
<li>LISTS$ <i>listname</i><br />
<br />
<li>LOCATION <span class="squareb">{</span><i>location</i> <span class="squareb">|</span> =<span class="squareb">}</span><br />
<br />
<li>POINT$ <i>value</i><br />
<br />
<li>SFGE$ <i>value</i><br />
<br />
<li>SFL$ <i>value</i><br />
<p><br />
where <i>value</i> can be:</p><br />
<ul><br />
<li>A literal number or string</li><br />
<li>VALUE <span class="squareb">{</span>[IN] <i>label</i><span class="squareb">}</span> <span class="squareb">|</span> (<i>expression</i>)</li><br />
<li>A %variable </li><br />
</ul><br />
</ul><br />
<br />
<p><b>Notes:</b></p><br />
<ul><br />
<li>The first character (<code>,</code>) of the inequality test (<code>,=</code>) in the fourth of the items in the list above is the EBCDIC "not sign," which has the hexadecimal value <code>5f</code>.<br />
<br />
<li>For a description of the pattern in the <code>[IS] LIKE</code> and <code>IS NOT</code> clauses, see the syntax of [[Is Like pattern matching#likeSyntax|Is Like patterns]].<br />
</ul><br />
<br />
====Omitting repeated first words====<br />
<p><br />
If a sequence of phrases in a particular retrieval condition all have the same first word, that word can be omitted from the latter phrases. For example:</p><br />
<p class="code">LIST$ A AND NOT LIST$ B<br />
</p><br />
<p><br />
can be written:</p><br />
<p class="code">LIST$ A AND NOT B<br />
</p><br />
<p><br />
And:</p><br />
<p class="code">X IS 13 OR X IS LESS THAN 7<br />
</p><br />
<p><br />
can be written:</p><br />
<p class="code">X IS 13 OR IS LESS THAN 7<br />
</p><br />
<br />
====Omitting duplicated equal signs====<br />
<p><br />
Duplicated equal signs can be omitted. For example, the expression:</p><br />
<p class="code">A = 3 OR A = 5 OR A = 40<br />
</p><br />
<p><br />
is equivalent to:</p><br />
<p class="code">A = 3 OR 5 OR 40<br />
</p><br />
<br />
====Use of parentheses====<br />
<p><br />
Parentheses can be placed around any sequence of phrases to clarify the condition or force the evaluation to occur in a particular order. For example:</p><br />
<p class="code">NOT (A = 2 OR LIST$ Y)<br />
A = 1 AND (B = 2 OR C = 3)<br />
</p><br />
<br />
====Use of expressions====<br />
<p><br />
Expressions can be used in <var>FIND</var> statements to provide the retrieval condition for the <var>POINT$</var>, <var>SFL$</var>, and <var>SFGE$</var> conditions, as well as for the <var>EQ VALUE</var> clause.</p><br />
<br />
=====POINT$=====<br />
<br />
======Syntax======<br />
<p class="syntax">POINT$ VALUE(<span class="term">expression</span>)<br />
</p><br />
Where:<br />
<p><br />
<var class="term">expression</var> is a function call, string concatenation, arithmetic operation, User Language construct, or Boolean expression. It is preceded by the keyword <var>VALUE</var>.</p><br />
<br />
======Example======<br />
<p><br />
This example finds the first <code>MA</code> record on file, and then counts the number of records from this point in the file:</p><br />
<p class="code">FD1:<br />
<br />
IN ICSCUST FPC STATE = MA<br />
END FIND<br />
FOR 1 RECORD IN FD1<br />
PRINT 'CURREC = ' WITH $CURREC<br />
PRINT '>= POINT$'<br />
FD2:<br />
IN ICSCUST FPC POINT$ VALUE($CURREC)<br />
END FIND<br />
END FOR<br />
</p><br />
<br />
=====SFL$ and SFGE$=====<br />
<br />
======Syntax======<br />
<p class="syntax">SFL$ VALUE(<span class="term">expression</span>)<br />
</p><br />
<p><br />
or</p><br />
<p class="syntax">SFGE$ VALUE(<span class="term">expression</span>)<br />
</p><br />
Where:<br />
<p><br />
<var class="term">expression</var> is a function call, string concatenation, arithmetic operation, User Language construct, or Boolean expression. It is preceded by the keyword <var>VALUE</var>.</p><br />
<br />
======Example======<br />
<p class="code">FOR %CT FROM 1 TO 10<br />
IN EXPRESS STORE RECORD ($EDITN(%CT,'999'))<br />
ORD1 = (%REC WITH %CT)<br />
ORD2 = (%CT * 2)<br />
ORD4 = (%CT * 4)<br />
END STORE<br />
END FOR<br />
COMMIT<br />
FOR %CT FROM 1 TO 5<br />
PRINT 'LESS THAN ' WITH %CT<br />
FD1:<br />
IN EXPRESS FPC SFL$ VALUE($EDITN(%CT,'999'))<br />
END FIND<br />
PRINT 'GREATER THAN OR EQUAL TO ' WITH %CT<br />
FD2:<br />
IN EXPRESS FPC SFGE$ VALUE($EDITN(%CT,'999'))<br />
END FIND<br />
END FOR<br />
</p><br />
<br />
=====EQ VALUE=====<br />
<br />
======Syntax======<br />
<p class="syntax"><span class="term">fieldname</span> EQ VALUE(<span class="term">expression</span>)<br />
</p><br />
Where:<br />
<p><br />
<var class="term">expression</var> is a function call, string concatenation, arithmetic operation, User Language construct, or Boolean expression.</p><br />
<br />
======Example======<br />
<p class="code">FD: IN FILE PEOPLE FD<br />
LAST EQ VALUE($READ('LAST NAME?') )<br />
END FIND<br />
</p><br />
<br />
===Print specification syntax===<br />
<p><br />
A <var>Print</var>, <var>Set</var>, <var>Audit</var>, or <var>Trace</var> statement contains print specifications of the following form:</p><br />
<br />
=====Syntax=====<br />
<p class="syntax">[<span class="term">term</span>] <span class="squareb">[</span>And <span class="squareb">|</span> Tab <span class="squareb">|</span> With]...[[<span class="term">term</span>] [And <span class="squareb">|</span> Tab <span class="squareb">|</span> With] ...] ... [...]<br />
</p><br />
Where:<br />
<p><br />
<var class="term">term</var> can be constructed as follows:</p><br />
<p class="syntax"><span class="squareb">{</span>'<span class="term">string</span>' <span class="squareb">|</span> <span class="term">%variable</span> <span class="squareb">|</span> COUNT IN <span class="term">label</span> <span class="squareb">|</span> OCCURRENCE IN <span class="term">label</span> <span class="squareb">|</span> VALUE IN <span class="label">term</span> <span class="squareb">|</span> <span class="term">function</span><span class="squareb">}</span><br />
<span class="squareb">[</span>AT <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">m</span><span class="squareb">]</span> <span class="squareb">[</span>TO <span class="squareb">[</span>COLUMN<span class="squareb">]</span> <span class="term">n</span><span class="squareb">]</span><br />
</p><br />
<p><br />
or, if the statement is within a record loop:<br />
</p><br />
<p class="syntax"><span class="squareb">{</span><span class="squareb">{</span>EACH <span class="squareb">|</span> <span class="n">term</span><span class="squareb">}</span> <span class="term">fieldname</span> <span class="squareb">|</span> *RECORD <span class="squareb">|</span> *ID<span class="squareb">}</span><br />
[AT [COLUMN] <span class="term">m</span>] [TO [COLUMN] <span class="term">n</span><span class="squareb">}</span><br />
</p><br />
<br />
<p class="note"><b>Note:</b> For additional <var>Print</var> statement details regarding multiply occurring fields and field groups, see [[Processing multiply occurring fields and field groups#PRINT and PRINT n statements|Print and Print <i>n</i>]] statements for fields. </p><br />
<br />
===Expression syntax===<br />
<p><br />
The following syntax can be used in: </p><br />
<ul><br />
<li>Assignment statements </li><br />
<li>Conditional <var>IF</var> statements and <var>ELSEIF</var> clauses</li><br />
</ul><br />
<p><br />
In the simplified syntax for an <var>IF</var> statement, which is:</p><br />
<p class="syntax">IF <span class="term">condition</span> THEN <span class="term">statements</span><br />
</p><br />
<p><br />
<var class="term">condition</var> expands to the syntax described in this section. Be sure to enclose an expression with parentheses. </p><br />
<ul><br />
<li>Computed <var>JUMP TO</var> statements </li><br />
<li>Subscripts </li><br />
<li>Function arguments </li><br />
</ul><br />
<br />
=====Syntax=====<br />
<p class="syntax"><span class="squareb">{</span>operand |(expression)<span class="squareb">}</span> [operator <span class="squareb">{</span>operand <span class="squareb">|</span> (expression)<span class="squareb">}</span>] ...<br />
</p><br />
Where:<br />
<p><br />
<var class="term">operand</var> can be constructed as follows:</p><br />
<p class="syntax">[+ <span class="squareb">|</span> - <span class="squareb">|</span> Not]<br />
<span class="squareb">{</span>'<span class="term">string</span>' <span class="squareb">|</span> <span class="term">%variable</span> <span class="squareb">|</span> <span class="term">number</span><br />
<span class="squareb">|</span> <span class="term">fieldname</span> <span class="squareb">[</span>(subscript)<span class="squareb">]</span> Is <span class="squareb">[</span>Not<span class="squareb">]</span> Present<br />
<span class="squareb">|</span> Count In <span class="term">label</span> <span class="squareb">|</span> Occurrence In <span class="term">label</span><br />
<span class="squareb">|</span> Value In <span class="term">label</span><br />
<span class="squareb">|</span> <span class="term">function</span><span class="squareb">}</span><br />
</p><br />
<p><br />
and <var class="term">operator</var> may be one of the following:</p><br />
<table style="table-layout: fixed"><br />
<tr><br />
<td width="4em"><b>+</b></td><br />
<td width="4em"><b>=</b></td><br />
<td width="4em">EQ</td><br />
<td>And</td><br />
</tr><br />
<tr><br />
<td><b>-</b></td><br />
<td><b>,=</b></td><br />
<td>NE</td><br />
<td>Or</td><br />
</tr><br />
<tr><br />
<td><b>*</b></td><br />
<td><b>></b></td><br />
<td>GT</td><br />
<td>With (Note: this can also be achieved via [[Implicit concatenation]])</td><br />
</tr><br />
<tr><br />
<td><b>/</b></td><br />
<td><b><</b></td><br />
<td>LT</td><br />
<td>Is [Not] Present (Note: applied either to a field or to an [[Methods#optionalParams|optional or default method parameter]])</td><br />
</tr><br />
<tr><br />
<td>&nbsp;</td><br />
<td><b>>=</b></td><br />
<td>GE</td><br />
<td>Is [Not] Like</td><br />
</tr><br />
<tr><br />
<td>&nbsp;</td><br />
<td><b><=</b></td><br />
<td>LE</td><br />
<td></td><br />
</tr><br />
<tr><br />
<td>&nbsp;</td><br />
<td>&nbsp;</td><br />
<td>&nbsp;</td><br />
<td></td><br />
</tr><br />
</table><br />
<p><br />
</p><br />
<blockquote class="note"><b>Notes:</b><br />
<ul><br />
<li>The first character (<code>,</code>) of the inequality test above is the EBCDIC "not sign", which has the hexadecimal value <code>5f</code>.<br />
<li>For a description of the <code>IS LIKE</code> and <code>IS NOT</code> clauses, see the syntax of [[Is Like pattern matching|Is Like patterns]].<br />
</ul><br />
</blockquote ><br />
<br />
===IN clause syntax===<br />
<p><br />
The SOUL statements on this page whose syntax display is preceded by an asterisk (<tt>*</tt>) support an <var>IN</var> clause. </p><br />
<p><br />
The three basic forms of the <var>IN</var> clause are: </p><br />
<br />
<p class="syntax">IN [PERMANENT <span class="squareb">|</span> TEMPORARY ] GROUP <span class="term">groupname</span><br />
MEMBER [<span class="term">%member</span> <span class="squareb">|</span> [<span class="term">filename</span> [AT <span class="squareb">{</span>location <span class="squareb">|</span> =<span class="squareb">}</span>]]</p><br />
<br />
<p class="syntax">IN <span class="term">file1</span> [,<span class="term">file2</span>] ...</p><br />
<br />
<p class="syntax">IN <span class="squareb">{</span>$CURFILE <span class="squareb">|</span> $UPDATE<span class="squareb">}</span></p><br />
<p>The form IN <var>$CURFILE</var> can be used only within a record loop.</p><br />
<br />
====IN GROUP MEMBER limitations====<br />
<p><br />
In addition to the three basic forms of the IN clause shown above the IN GROUP MEMBER clause restricts the following statements to one member file in a group context:</p><br />
<ul><br />
<li><var>CLEAR LIST</var></li><br />
<br />
<li><var>FIND ALL RECORDS</var> (and its variants)</li><br />
<br />
<li><var>FIND ALL VALUES</var></li><br />
<br />
<li><var>FOR RECORD NUMBER</var> (or <var>FRN</var>)</li><br />
<br />
<li><var>STORE RECORD</var><br />
</li><br />
</ul><br />
<p><br />
You cannot use an <var>IN GROUP MEMBER</var> clause with a <var>FOR EACH RECORD</var> statement or with an <var>ADD</var>, <var>CHANGE</var>, or <var>DELETE RECORD</var> statement. Only the previously listed statements call accept an <var>IN GROUP MEMBER</var> clause.</p><br />
<br />
====Using an IN clause in a BEGIN...END block====<br />
<p><br />
The file name in the <var>IN</var> clause used within a <var>BEGIN...END</var> block is resolved by the compiler. You can either hard code a file name or use some type of dummy string for the file name. The use of a %variable for the file name is not allowed.</p><br />
<br />
===Subscript syntax===<br />
<p><br />
A subscript has the format: </p><br />
<br />
=====Syntax=====<br />
<p class="syntax">(<span class="term">subscript1</span> [,<span class="term">subscript2</span> [,<span class="term">subscript3</span>]] )<br />
</p><br />
Where:<br />
<p><br />
<var class="term">subscript1</var>, <var class="term">subscript2</var>, and <var class="term">subscript3</var> can be any expression. </p><br />
<br />
==Terminal display attributes==<br />
<p><br />
One or more of the following terminal display attributes can replace the term attribute in a full-screen formatting statement, if the display attribute is supported by the installation:</p><br />
<br />
<table><br />
<caption>List of attributes</caption><br />
<tr><br />
<td>BLINK</td><br />
</tr><br />
<tr><br />
<td>BLUE</td><br />
</tr><br />
<tr><br />
<td>BRIGHT</td><br />
</tr><br />
<tr><br />
<td>DIM</td><br />
</tr><br />
<tr><br />
<td>GREEN</td><br />
</tr><br />
<tr><br />
<td>INV[IS[BLE]] </td><br />
</tr><br />
<tr><br />
<td>NOBLINK</td><br />
</tr><br />
<tr><br />
<td>NOREV[ERSE]</td><br />
</tr><br />
<tr><br />
<td>NOU[NDER]SCORE</td><br />
</tr><br />
<tr><br />
<td>PINK</td><br />
</tr><br />
<tr><br />
<td>PROT[ECTED]</td><br />
</tr><br />
<tr><br />
<td>RED</td><br />
</tr><br />
<tr><br />
<td>REV[ERSE]</td><br />
</tr><br />
<tr><br />
<td>TURQUOISE</td><br />
</tr><br />
<tr><br />
<td>[UNDER]SCORE</td><br />
</tr><br />
<tr><br />
<td>UNPROT[ECTED]</td><br />
</tr><br />
<tr><br />
<td>VIS[IBLE]</td><br />
</tr><br />
<tr><br />
<td>WHITE</td><br />
</tr><br />
<tr><br />
<td>YELLOW </td><br />
</tr><br />
</table><br />
<br />
==Notation conventions==<br />
<p><br />
This page uses the following syntax notation conventions: </p><br />
<br />
<table><br />
<tr class="head"><br />
<th>Syntax notation </th><br />
<th>Indicates that...</th><br />
</tr><br />
<br />
<tr><br />
<td>Single asterisk (*) </td><br />
<td>Statements can be preceded by an IN clause, if there is no reference to a previous set (label or list). See [[#IN clause syntax|IN clause syntax]] for more discussion.</td><br />
</tr><br />
<br />
<tr><br />
<td>Two asterisks (**) </td><br />
<td>Construct can appear only within a record loop.</td><br />
</tr><br />
<br />
<tr><br />
<td>Plus sign (+) </td><br />
<td>Construct requires the optional Horizon feature.</td><br />
</tr><br />
<br />
<tr><br />
<td nowrap>Two plus signs (++) </td><br />
<td>Construct requires the optional User Language to Database 2 feature.</td><br />
</tr><br />
<br />
<tr><br />
<td>C</td><br />
<td>The syntax applies to a <var class="product">Model&nbsp;204</var> command as well as a User Language statement, except any %variable options or clauses.<br />
<p><br />
<var class="product">Model&nbsp;204</var> commands are listed alphabetically and documented in [[List of Model 204 commands]]. </p></td><br />
</tr><br />
<br />
<tr><br />
<td>Lowercase italic </td><br />
<td>Constructs are replaced with variable information.</td><br />
</tr><br />
</table><br />
<br />
<ul><br />
<li>A field name (%%) variable can be used anywhere fieldname appears. The %%variable can contain its own subscript, separate from the field name subscript.<br />
<p class="note"><b>Note: </b><br />
The subscript of an array element must be specified before a field name subscript.</p> </li><br />
<br />
<li>The lowercase constructs &mdash; retrieval-conditions, print-specifications, expression, subscript, attribute, and type &mdash; are discussed separately following the syntax summaries, beginning with [[#Value specification syntax|Value specification syntax]]. </li><br />
<br />
<li>For more Model 204 notation conventions, see [[Notation conventions]].</li><br />
</ul><br />
<br />
<br />
[[Category:SOUL]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Template:Change_fieldname_statement_syntax_(basic)&diff=115012Template:Change fieldname statement syntax (basic)2018-04-25T20:59:27Z<p>Admin: Admin moved page Template:Change non-lob-fieldname statement syntax to Template:Change fieldname statement syntax (basic) without leaving a redirect: syntax might apply to lob or non-lob</p>
<hr />
<div><p class="syntax"><b><sup>(**)</sup></b>[[Data maintenance#Change statement|Change]] <span class="term">fieldname</span> [(<span class="term">subscript</span>)] [= <span class="term">value</span> |(<span class="term">expression</span>)] To (<span class="term">newvalue</span> |(<span class="term">expression</span>))<br />
</p></div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Template:Sir2000_topic_list&diff=105111Template:Sir2000 topic list2018-02-08T22:03:18Z<p>Admin: Created page with "<ul> <li>Sir2000 User Language Tools </li> <li>The Sir2000 APPDATE command </li> <li>Sir2000 User Language Tools $functions </li> <li>Sir2000 datetime processing..."</p>
<hr />
<div><ul><br />
<li>[[Sir2000 User Language Tools]] </li><br />
<li>[[The Sir2000 APPDATE command]] </li><br />
<li>[[Sir2000 User Language Tools $functions]] </li><br />
<li>[[Sir2000 datetime processing considerations]] </li><br />
<li>[[Assembler language subroutines for FUNU]] </li><br />
</ul></div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Category:Sir2000_User_Language_Tools&diff=105110Category:Sir2000 User Language Tools2018-02-08T22:00:53Z<p>Admin: 1 revision imported</p>
<hr />
<div>The topics linked on this page contain the primary documentation for the Model&nbsp;204 add-on product, [[Sir2000 User Language Tools]].</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=The_Sir2000_APPDATE_command&diff=105108The Sir2000 APPDATE command2018-02-08T22:00:52Z<p>Admin: 1 revision imported</p>
<hr />
<div>==Overview==<br />
The <var>APPDATE</var> command provides control over the operation of date and time oriented SOUL $functions. It supports a system-wide or user-level clock that is used to obtain date and time values. It can be used to control the default handling of errors detected by datetime $functions, allowing the logging of error messages and request cancellation. The <var>APPDATE</var> command allows you to control these defaults at a user and system level, significantly reducing your effort to detect some date errors.<br />
<br />
For application testing, the <var>APPDATE</var> clocks are preferred to the Model&nbsp;204 <var>[[SYSDATE parameter|SYSDATE]]</var> parameter, which is much less flexible and which greatly complicates the ability to do things such as share procedure files or read-only data files in the testing environment.<br />
<br />
See [[#Values affected by the APPDATE clocks|Values affected by the APPDATE clocks]] for a list of the values that are affected by the <var>APPDATE</var> command. See [[#APPDATE command usage notes|APPDATE command usage notes]] for descriptions of several common testing scenarios and how to use <var>APPDATE</var> to handle them, including testing the effect of changing the date into the future for any of the following:<br />
<br />
<ul><br />
<li>A single user's session </li><br />
<li>All users' sessions </li><br />
<li>All users' sessions except selected ones </li><br />
<li>All users of a given [[APSY]] </li><br />
<li>All users of all APSYs, except selected APSYs </li><br />
</ul><br />
<br />
In most contexts when describing <var>APPDATE</var>, these Sir2000 User Language Tools pages speak of a "date and time" or simply of a "time" (which is the same thing). Generally, for Y2K testing, you are only concerned about setting a "date," that is, setting the clock to a particular day.<br />
<br />
<var>APPDATE</var> addresses many of the needs to test a SOUL application at some<br />
date in the future, notably beyond the end of the 1900s. <var>APPDATE</var> lets you make these tests with your current version of Model&nbsp;204, and without modifying the Model&nbsp;204 internal date-related data structures, such as the File Parameter List, page trailers, and the Procedure Dictionary. <var>APPDATE</var> does not affect any file level operations such as recovery or DUMP, or the ability to open a file with different application date settings.<br />
<br />
The system-wide and user-level clocks specified by the <var>APPDATE</var> command are called <b>APPDATE clocks</b>. In order to use these clocks, you must set the date (and optionally the time) of the system level or the user level clock. The syntax associated with setting these APPDATE clocks is described in [[#Setting the clocks with the APPDATE command|Setting the clocks with the APPDATE command]].<br />
<br />
Another important component in a testing environment, or indeed in a production<br />
environment, is the ability to detect unanticipated errors. The <var>APPDATE</var> command with a <var>DATE_ERR</var> clause and the <var>$Sir_Date_Err</var> function allow you to change the default error handling of arguments to date and time oriented $functions. The syntax associated with <var>DATE_ERR</var> is described in [[#Error handling control with DATE_ERR|Error handling control with DATE_ERR]].<br />
<br />
A single invocation of the <var>APPDATE</var> command can set <var>APPDATE</var> values or display <var>APPDATE</var> values. If you want to examine the <var>APPDATE</var> values in effect, use the syntax described in [[#Examining the APPDATE information|Examining the APPDATE information]]. The detailed explanation of setting <var>APPDATE</var> values is described separately for clock values<br />
and datetime argument error handling, but for a single level you can specify both clock values and error handling, in that order, in a single command. <br />
<br />
The complete syntax of the <var>APPDATE</var> command is shown in [[#Complete syntax of the APPDATE command|Complete syntax of the APPDATE command]].<br />
<br />
==Setting clocks with the APPDATE command==<br />
<p><br />
The two <var>APPDATE</var> clocks (user and system) effectively run in parallel with the internal clock, that is, the time that Model&nbsp;204 obtains from the CPU. <br />
</p><br />
<p class="note"><b>Note:</b> The <var>SYSDATE</var> parameter cannot be specified if the <var>APPDATE</var> command is used. </p><br />
<p><br />
When you set either of the clocks, you are actually setting the amount that the clock runs ahead of the internal clock. You do that by specifying either of these: </p><br />
<ul> <br />
<li>The current time of the clock being set </li><br />
<br />
<li>The time that would be current when the internal clock is at some specific reference time </li><br />
</ul><br />
<p><br />
In addition to the time setting of the clocks, you control which clock an application uses. This is determined primarily by the "state" of the <var>USER</var> clock: <br />
</p><br />
<table class="thJustBold"><br />
<tr class="head"><th>State</th><th>Meaning</th></tr><br />
<br />
<tr><th>INTERNAL</th> <br />
<td>Applications use the <var>INTERNAL</var> clock. </td></tr><br />
<br />
<tr><th>ON</th><br />
<td>Applications use the <var>USER</var> clock. </td></tr><br />
<br />
<tr><th nowrap>OFF (the default) </th><br />
<td>Applications use the <var>INTERNAL</var> clock unless the<br />
<var>SYSTEM</var> clock is on (the default <var>SYSTEM</var> clock is off). </td></tr><br />
</table><br />
<p><br />
The clock used to satisfy an application request for date or time is determined as shown in the following figure: <br />
</p><br />
<p class="caption" style="margin-right:12em">Source of date returned to $function</p><br />
<p class="code"> *----------------------------------------------------------*<br />
* Application code requests date *<br />
* (datetime $functions) *<br />
*----------------------------------------------------------*<br />
|<br />
|-> Gets date/time from the USER clock if it is ON <br />
| (example: APPDATE USER ON 2001/01/01)<br />
|<br />
|-> Else from SYSTEM clock if it is ON and USER clock is OFF<br />
| example: APPDATE USER OFF (default)<br />
| and APPDATE SYSTEM ON 1999/12/31<br />
|<br />
|-> Else from INTERNAL clock:<br />
example: APPDATE USER INTERNAL<br />
or<br />
APPDATE USER OFF<br />
and APPDATE SYSTEM OFF<br />
or<br />
APPDATE USER OFF<br />
and APPDATE SYSTEM INTERNAL </p><br />
<br />
===APPDATE syntax to set USER or SYSTEM clock===<br />
<p><br />
The time of the <var>USER</var> or <var>SYSTEM</var> clock may be set by the <var>APPDATE</var> command: <br />
</p><br />
<p class="syntax">APPDATE [USER|SYSTEM] [ON|OFF|INTERNAL] -<br />
<span class="term">targdate</span> [<span class="term">targtime</span>] -<br />
[AT <span class="term">refdate</span> [<span class="term">reftime</span>]] </p><br />
<br />
===APPDATE syntax to change state of USER or SYSTEM clock===<br />
<p><br />
Whether or not a particular clock is used can be controlled by the <var>APPDATE</var> command, without changing the time of the <var>USER</var> or <var>SYSTEM</var> clock: <br />
</p><br />
<p class="code">APPDATE <span class="squareb">[</span>USER<span class="squareb">|</span>SYSTEM<span class="squareb">]</span> <span class="squareb">{</span> ON<span class="squareb">|</span>OFF<span class="squareb">|</span>INTERNAL <span class="squareb">}</span> </p><br />
<br />
===Syntax terms===<br />
<table class="thJustBold"><br />
<tr><th>USER | SYSTEM</th><br />
<td>Optional specification of which clock is being modified. Defaults to <var>USER</var>. The <var>USER</var> clock specifies the running user's <var>APPDATE</var> clock. The <var>SYSTEM</var> clock specifies the <var>APPDATE</var> clock used for any user with an <var>APPDATE</var> <var>USER</var> clock that is <var>OFF</var>. </td></tr><br />
<br />
<tr><th>ON | OFF | INTERNAL</th><br />
<td>Optional. <code>APPDATE USER ON</code> indicates that the user clock is used by the current user. <code>APPDATE SYSTEM ON</code> indicates that the system clock is used by all users whose user clock is <var>OFF</var>. <var>OFF</var> and <var>INTERNAL</var> both indicate that the specified clock is not visible. <br />
<p><br />
If the user-level clock is set to <var>ON</var>, SOUL $function values are obtained from the user-level clock. </p><br />
<p><br />
If the user-level clock is set to <var>INTERNAL</var>, SOUL $function values are obtained from the internal clock. </p><br />
<p><br />
If the user-level clock is set to <var>OFF</var>, SOUL $function values depend on the setting of the system-wide clock: if it is <var>ON</var>, they are obtained from the system-wide clock; otherwise (it is <var>OFF</var> or <var>INTERNAL</var>) they are obtained from the internal clock. </p><br />
<p><br />
If this phrase is omitted in an <var>APPDATE</var> command that sets the time of a<br />
clock, the state of that clock is set to <var>ON</var>. </p><br />
<p><br />
You can specify <var>ON</var>, <var>OFF</var>, or <var>INTERNAL</var> without a date, in which case the date/time in a clock is not changed, but the visibility of the corresponding clock is affected. </p></td></tr><br />
<br />
<tr><th nowrap><i>targdate</i> [<i>targtime</i>] <br>[AT <i>refdate</i> [<i>reftime</i>]]</th><br />
<td><var class="term">targdate</var> is required;, the rest are optional. These phrases allow you to specify the date and time of the application clock. The dates are specified in YYYY/MM/DD format, and the times are specified in HH:MI:SS format. <p><br />
The application clocks continue to run so that they are a constant difference from<br />
the internal date and time. This difference is the difference between the target datetime, as specified by <var class="term">targdate</var> and the optional <var class="term">targtime</var>, and the reference datetime. The reference datetime can be omitted, in which case the reference datetime is the datetime when the <var>APPDATE</var> command is issued. </p><br />
<p><br />
If <var class="term">reftime</var> is specified, <var class="term">targtime</var> must also be. If <var class="term">targtime</var> is specified, then either <var class="term">refdate</var> must be omitted or <var class="term">reftime</var> must be specified. If <var class="term">targtime</var> is omitted, the clock is shifted the number of days between <var class="term">targdate</var> and <var class="term">refdate</var>. </p></td></tr><br />
</table><br />
<p><br />
A successful <code>APPDATE SYSTEM</code> command has an immediate effect upon the date/time returned by SOUL $functions for all threads that have user-level clocks set or defaulted to the <var>OFF</var> state. </p><br />
<p><br />
The default value of the system-wide clock and all user-level clocks is <var>OFF</var>, with the same datetime as the internal clock. Hence, if the only command you issue is <code>APPDATE SYSTEM yyyy/mm/dd</code>, you will immediately shift the value returned as the current date by SOUL $functions. The <var>APPDATE</var> <var>USER</var> clock is reset to <var>OFF</var>, with the same time as the <var>INTERNAL</var> clock, when a user logs off. </p><br />
<br />
==Error handling control with DATE_ERR==<br />
The <var>APPDATE</var> command with the <var>DATE_ERR</var> keyword and the <var>[[$Sir_Date_Err]]</var> function let you decide what default action the system takes if an error is detected by a datetime $function. This lets you control validation of dates in your applications, significantly reducing your effort to detect and correct date errors.<br />
<br />
<var>APPDATE DATE_ERR</var> and <var>$Sir_Date_Err<var> detect the following errors:<br />
<ul><br />
<li>Invalid datetime format specification </li><br />
<li>Datetime string not matching format </li><br />
<li>Datetime out of range for the format </li><br />
<li>Invalid CENTSPAN value </li><br />
<li>Datetime out of range for CENTSPAN/SPANSIZE combination </li><br />
</ul><br />
<p><br />
You can set the default error handling for all $functions in the system with an <code>APPDATE SYSTEM DATE_ERR</code> command. You can override this setting for an individual user with<br />
an <code>APPDATE USER DATE_ERR</code> command. You can override both settings for the duration of a SOUL request with the <var>$Sir_Date_Err</var> function. If you are using the Sirius datetime $functions, you can also supply a parameter on the individual<br />
function call to control error handling, overriding the default set by <var>$Sir_Date_Err</var> or <var>APPDATE</var>. </p><br />
<p><br />
The processing performed when a datetime function encounters an error is determined<br />
using the precedence indicated in the following figure: <br />
</p><br />
<p class="caption" style="margin-right:12em">Datetime $function argument error handling </p><br />
<p class="code"> *----------------------------------------*<br />
* Datetime $function argument error *<br />
*----------------------------------------*<br />
|<br />
|-> IGNORE is error handling handling arg:<br />
| return error value<br />
|<br />
|-> REPORT is error handling arg:<br />
| issue message, return error value<br />
|<br />
|-> Error handling supplied, and not OFF:<br />
| issue message, cancel request<br />
|<br />
++ Else OFF is error handling arg, or none:<br />
|<br />
|-> $SIR_DATE_ERR('REPORT') last invoked:<br />
| issue message, return error value<br />
|<br />
|-> $SIR_DATE_ERR('IGNORE') last invoked:<br />
| return error value<br />
|<br />
|-> $SIR_DATE_ERR('CANCEL') last invoked:<br />
| issue message, cancel request<br />
|<br />
++ Else error handling controlled by APPDATE:<br />
|<br />
|-> USER DATE_ERR REPORT:<br />
| issue message, return error value<br />
|<br />
|-> USER DATE_ERR IGNORE:<br />
| return error value<br />
|<br />
|-> USER DATE_ERR CANCEL:<br />
| issue message, cancel request<br />
|<br />
|-> USER DATE_ERR OFF (default) and<br />
| SYSTEM DATE_ERR REPORT<br />
| issue message, return error value<br />
|<br />
|-> USER DATE_ERR OFF (default) and<br />
| SYSTEM DATE_ERR IGNORE<br />
| return error value<br />
|<br />
|-> USER DATE_ERR OFF (default) and<br />
| SYSTEM DATE_ERR CANCEL<br />
| issue message, cancel request<br />
|<br />
++ Else error handling not affected<br />
| by Sir2000 User Language Tools:<br />
|<br />
+---> return error value </p><br />
<br />
===Setting default error handling with the APPDATE command===<br />
The <var>APPDATE</var> command may be used to set and change the default for processing performed when a datetime $function detects an error.<br />
<p class="code">APPDATE [USER|SYSTEM] DATE_ERR -<br />
[OFF | CANCEL | REPORT | IGNORE] -<br />
[DEBUG | NODEBUG] <br />
</p><br />
<table class="thJustBold"><br />
<tr><th>USER | SYSTEM</th><br />
<td>Optional specification of the scope for the current command, defaults to USER. The USER error handling overrides the SYSTEM error handling. Both USER and SYSTEM error handling are initially OFF. </td></tr><br />
<br />
<tr><th>OFF | CANCEL | REPORT | IGNORE</th><br />
<td>This is optional. OFF indicates that there is no default error handling at the<br />
given level. CANCEL indicates that the default error handling at the given level is issuing an error message describing the error and cancelling the User Language request. REPORT indicates that the default error handling at the given level is issuing an error message describing the error and returning an error indicator. IGNORE indicates that the default error handling at the given level is returning an error indicator. </td></tr><br />
<br />
<tr><th nowrap>DEBUG | NODEBUG</th><br />
<td>If DEBUG is specified, any datetime error message produced at the given level (user or system) will include the name of the procedure file, the procedure name, and the line number within the procedure for the affected $function invocation. <br />
<p><br />
If neither DEBUG nor NODEBUG is specified, then OFF, CANCEL, REPORT, or IGNORE must be specified, in which case the default DEBUG/NODEBUG setting is determined from the following table: </p><br />
<table class="thJustBold"><br />
<tr><th>CANCEL</th><br />
<td>DEBUG </td></tr><br />
<br />
<tr><th>REPORT</th><br />
<td>DEBUG</td></tr><br />
<br />
<tr><th>IGNORE</th><br />
<td>NODEBUG</td></tr><br />
<br />
<tr><th>OFF</th><br />
<td>There is no DEBUG/NODEBUG setting at the level.</td></tr><br />
</table><br />
<p><br />
Since the initial DATE_ERR setting is OFF, there is no DEBUG/NODEBUG<br />
setting, at both SYSTEM and USER levels. </p></td></tr><br />
</table><br />
<p><br />
Both the USER and SYSTEM level defaults can be overridden by the setting of the<br />
<var>$Sir_Date_Err</var> function, which in turn is overridden by supplying a non-default value<br />
for the error handling argument, if a $Sir_Date<i>xxx</i> $function is in use. The<br />
<var>$Sir_Date_Err</var> error handling is initially OFF. If <code>$Sir_Date_Err('OFF')</code> is in effect,<br />
the USER level handling controls default error handling, unless it is OFF, in which case the SYSTEM level controls the default. </p><br />
<p class="note"><b>Note:</b> The <var>APPDATE</var> command and <var>$Sir_Date_Err</var> set only the default datetime argument error handling. This will affect the standard SOUL date $functions, and it will affect the $Sir_Date<i>xxx</i> and Sir2000 $functions if they are coded without the error handling argument. </p><br />
<br />
===Setting default error handling with the $Sir_Date_Err function===<br />
<var>[[$Sir_Date_Err]]</var> provides the ability to set or override default datetime $function error handling at the request level:<br />
<p class="code">%s string len 8<br />
%s = $sir_date_er('REPORT') </p><br />
<p><br />
The effect of a <var>$Sir_Date_Err</var> invocation persists until the end of the SOUL request, at which time its setting is reset to <var>OFF</var>. Note that <var>$Sir_Date_Err</var> only sets<br />
the default datetime argument error handling. It will affect the standard SOUL date $functions, and<br />
it will affect the $Sir_Date<i>xxx</i> $functions if they are coded without the error handling argument. </p><br />
<br />
==Examining the APPDATE information==<br />
The Sir2000 User Language Tools provide mechanisms for displaying and saving the<br />
state of the <var>APPDATE</var> clocks and various DATE_ERR switches. Thus, it is possible for applications to retrieve the current states, temporarily change the states and then restore the previous states.<br />
<br />
===APPDATE DISPLAY command===<br />
The following form of the <var>APPDATE</var> command allows you to view the setting of either the USER or SYSTEM clock, and to view the error handling setting:<br />
<p class="code">APPDATE DISPLAY [ALL|USER|SYSTEM] <br />
</p><br />
<br />
<table class="thJustBold"><br />
<tr><th nowrap>ALL | USER | SYSTEM</th><br />
<td>This is optional. It specifies to display the current time and error handling setting for all levels, or to display either the USER or SYSTEM level in a form that is equivalent to the <var>APPDATE</var> command which set it.<br />
<p><br />
ALL is the default and prints the current internal time, the<br />
clock ON|OFF|INTERNAL settings for both USER and<br />
SYSTEM, the DATE_ERR settings of both USER and<br />
SYSTEM, what the current times would be for the clocks if<br />
they were in effect, and an indication of which clock and<br />
which error handling setting is active for the current user.<br />
Following this is the display of the USER and SYSTEM levels<br />
in the "command setting" form, that is, the command that was<br />
issued to set the level. </p></td></tr><br />
</table><br />
<p><br />
<code>APPDATE DISPLAY ALL</code> is not suitable for placing in a global and re-invoking; you should use <code>APPDATE DISPLAY {USER | SYSTEM}</code> for that purpose. The display<br />
format of <code>APPDATE DISPLAY ALL</code> is shown in the following example: <br />
</p><br />
<p class="code"> LEVEL CLOCK STATE/DATE_ERR CURRENT CLOCK<br />
-------- ----------------------- ------------------------<br />
INTERNAL 1997/05/14 11:27:51<br />
SYSTEM ON/OFF 2000/01/02 11:27:51 (@)<br />
USER OFF/CANCEL DEBUG 1997/05/14 11:27:51 (*)<br />
SYSTEM CLOCK ACTIVE (@); USER LEVEL IS ERROR HANDLING DEFAULT (*)<br />
COMMAND SETTINGS:<br />
APPDATE SYSTEM ON 2000/01/01 AT 1997/05/13 DATE_ERR OFF<br />
APPDATE USER OFF 1997/05/13 AT 1997/05/13 DATE_ERR CANCEL DEBUG </p><br />
<p><br />
The <code>APPDATE DISPLAY {USER | SYSTEM}</code> forms of the command produce results in the form of a legal <var>APPDATE</var> command that would set the levels to their current<br />
values. For example, the following lines would result from invocations of the <code>APPDATE DISPLAY USER</code> and <code>APPDATE DISPLAY SYSTEM</code> commands in the same context as above: <br />
</p><br />
<p class="code">APPDATE SYSTEM ON 2000/01/01 AT 1997/05/13 DATE_ERR OFF<br />
APPDATE USER OFF 1997/05/13 AT 1997/05/13 DATE_ERR CANCEL DEBUG </p><br />
<br />
===Retrieving last non-null $Sir_Date_Err setting===<br />
<p><br />
You can call <var>$Sir_Date_Err</var> with no argument or with the null string, and it will return a character string indicating the most recent valid and non-null value specified in a call to <var>$Sir_Date_Err</var> during the current request. </p><br />
<p><br />
For example: <br />
</p><br />
<p class="code">%s string len 8<br />
%s = $sir_date_err( <no argument> | &apos;&apos; ) </p><br />
<p><br />
Such a call will return one of the following strings: </p><br />
<ul><br />
<li>'OFF' </li><br />
<li>'CANCEL' </li><br />
<li>'REPORT' </li><br />
<li>'IGNORE' </li><br />
</ul><br />
<br />
==Privileges, disabling, and pre-User 0 APPDATE command==<br />
The <code>APPDATE SYSTEM</code> form of the command can be issued only by User&nbsp;0 (user zero, that is, in the CCAIN input stream) or by a user with system manager privileges;<br />
<code>APPDATE USER</code> and <code>APPDATE DISPLAY</code> can be issued by any user. <code>APPDATE SYSTEM</code> can also be used in the CCAIN input stream before the User&nbsp;0 parameter line,<br />
so that the system-wide <var>APPDATE</var> clock and error handling can be set prior to any calculations performed by an IODEV 3 thread. Neither <code>APPDATE USER</code> nor <code>APPDATE DISPLAY</code> may be used before the User&nbsp;0 parameter line.<br />
<p><br />
An <code>APPDATE RESTRICT</code> command can be used to prohibit any issuance of the<br />
<var>APPDATE</var> command except prior to the User&nbsp;0 parameter line. This could be used if you do not want anyone to change the <var>APPDATE</var> settings after initialization of the Model&nbsp;204 run. The <code>APPDATE RESTRICT</code> command itself can only be issued before the User&nbsp;0 parameter line. </p><br />
<p><br />
You can also disable or restrict the <var>APPDATE</var> command by applying a customization zap. You might use a customization zap like the following if, for example, you wanted to disallow the use of the <var>APPDATE</var> command in a production load module: </p><br />
<p class="code"> * If you apply the following zap, any APPDATE<br />
* command will cause an error message to be<br />
* issued and the command otherwise is ignored.<br />
*<br />
* Note: this example assumes you have no other<br />
* customization zaps; if you do, include those<br />
* bits in the VER and REP data.<br />
*<br />
NAME ONLINE SIRK$<br />
VER 070E 00<br />
REP 070E 80<br />
* ------------- End of zap -------------------- </p><br />
<p><br />
Or a zap like the following, if you want to only allow one system-wide <var>APPDATE</var> setting for the entire Model&nbsp;204 run: <br />
</p> <br />
<p class="code"> * If you apply the following zap, the APPDATE<br />
* command is only allowed prior to the user zero<br />
* parameter line, and any other use of APPDATE<br />
* will cause an error message to be issued and<br />
* the command otherwise is ignored.<br />
*<br />
* Note: this example assumes you have no other<br />
* customization zaps; if you do, include those<br />
* bits in the VER and REP data.<br />
*<br />
NAME ONLINE SIRK$<br />
VER 070E 00<br />
REP 070E 40<br />
* ------------- End of zap --------------------<br />
</p><br />
<p class="note"><b>Note:</b> Lines are not sent to the Model&nbsp;204 audit trail for commands (and subsequent error messages) issued prior to the User&nbsp;0 parameter line. Output <i>is</i> sent to CCAPRINT for such commands, however. </p><br />
<br />
==Complete syntax of the APPDATE command==<br />
The detailed explanation of setting <var>APPDATE</var> values is described separately for clock values (see [[#Setting clocks with the APPDATE command|Setting clocks with the APPDATE comman]]) and<br />
datetime argument error handling (see [[#Error handling control with DATE_ERR|Error handling control with DATE_ERR]]). However, for the USER or SYSTEM level you can specify both clock values and error handling, in that order, in a single command. <br />
<br />
===Syntax===<br />
<p><br />
The complete syntax of the <var>APPDATE</var> command is shown below: </p><br />
<br />
<p class="syntax">APPDATE <span class="squareb">{</span> <span class="term">Level</span> <span class="term">Clock_set</span> [<span class="term">Err_set</span>] <span class="squareb">|</span> <span class="term">Level Err_set</span> <span class="squareb">|</span> <span class="term">Display</span> <span class="squareb">|</span> RESTRICT <span class="squareb">}</span> </p><br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th><p>Level</p></th> <br />
<td><p class="codeInTable">USER | SYSTEM </p></td></tr><br />
<br />
<tr><th><p>Clock_set</p></th> <br />
<td><p class="codeInTable"><var class="term">Clock_state</var> | [<var class="term">Clock_state</var>] <var class="term">Date_times</var> </p></td></tr><br />
<br />
<tr><th><p>Clock_state</p></th> <br />
<td><p class="codeInTable">ON | OFF | INTERNAL </p></td></tr><br />
<br />
<tr><th><p>Date_times</p></th> <br />
<td><p class="codeInTable">{ <var class="term">targdate</var> [AT <var class="term">refdate</var>] <br />
| <var class="term">targdate targtime</var> [AT <var class="term">refdate reftime</var>] } </p></td></tr><br />
<br />
<tr><th><p>Err_set</p> </th> <br />
<td><p class="codeInTable">DATE_ERR <span class="squareb">{</span> [OFF|CANCEL|REPORT|IGNORE] <span class="squareb">|</span> [DEBUG|NODEBUG] <span class="squareb">}</span> </p><br />
<p class="note"><b>Note:</b> {<var>OFF|CANCEL|REPORT|IGNORE</var>} or {<var>DEBUG|NODEBUG</var>} must be specified with <var>DATE_ERR</var>.</p></td></tr><br />
<br />
<tr><th><p>Display </p></th> <br />
<td><p class="codeInTable">DISPLAY [ALL | USER | SYSTEM] </p></td></tr><br />
</table><br />
<p><br />
As discussed in [[#Privileges, disabling, and pre-User 0 APPDATE command|Privileges, disabling, and pre-User 0 APPDATE command]]: </p><br />
<ul><br />
<li>An <code>APPDATE SYSTEM</code> command must be issued in the User&nbsp;0 input stream or by a system manager; an error message is produced if <code>APPDATE SYSTEM</code> is processed in other contexts. </li><br />
<br />
<li>An <code>APPDATE RESTRICT</code> command must be issued in the User&nbsp;0 input stream; an error message is produced if <code>APPDATE RESTRICT</code> is processed in other contexts. </li><br />
<br />
<li>The <var>APPDATE</var> command can also be completely disabled, or restricted to the User&nbsp;0 input stream before the User&nbsp;0 parameter line, by using a customization zap. </li><br />
<br />
<li>Issuing an <var>APPDATE</var> command in a disabled or restricted context produces an error message but does no checking or processing of the command. </li><br />
</ul><br />
<br />
==Values affected by the APPDATE clocks==<br />
The active <var>APPDATE</var> clock affects the value returned by the following SOUL $functions:<br />
<ul><br />
<li><var>$Date</var>, <var>$DateJ</var>, <var>$DateP</var> </li><br />
<br />
<li><var>$DateDif</var>, <var>$DateCnv</var>, and <var>$DayI</var> (when obtaining the year for handling the <var>CENTSPLT</var> argument) </li><br />
<br />
<li><var>$Time</var> </li><br />
<br />
<li><var>$Sir_Date</var>, <var>$Sir_DateN</var>, <var>$Sir_DateND</var>, <var>$Sir_DateNM</var>, <var>$Sir_DateS</var>, <var>$SirTime</var>, and <var>$Web_Date</var> </li><br />
<br />
<li><var>$Web_Last_Modified</var> (when ensuring last-modified date isn't future) </li><br />
<br />
<li><var>$Sir_DateChg</var>, <var>$Sir_DateChk</var>, <var>$Sir_DateCnv</var>, <var>$Sir_DateDif</var>, <var>$Sir_Date2N</var>, <var>$Sir_Date2ND</var>, <var>$Sir_Date2NM</var>, <var>$Sir_Date2NS</var>, <var>$Db_RpcParam</var>, <var>$Srv_Bind</var>, and <var>$Srv_Parmset</var> (when obtaining the year for relative <var>CENTSPAN</var> handling) </li><br />
</ul><br />
<p><br />
The only Model&nbsp;204 command affected by the <var>APPDATE</var> clock is the <var>RESET</var> command for changing the <var>CENTSPLT</var> user parameter. In this case, the <var>BASECENT</var> parameter, which is calculated using the current time, obtains the current time from the active<br />
<var>APPDATE</var> clock. The resulting value of <var>BASECENT</var> can be used to interpret 2-digit years passed to the following SOUL $functions: </p><br />
<ul><br />
<li><var>$DateDif</var>, <var>$DateCnv</var>, and <var>$DayI</var>, if neither the <var>CENTSPLT</var> nor <var>DEFCENT</var> arguments are provided </li><br />
<br />
<li><var>$DateChg</var> and <var>$DateChk</var> </li><br />
</ul><br />
<p><br />
Finally, the default value of <var>DEFCENT</var> is taken from the active <var>APPDATE</var> clock if the <var>APPDATE</var> command is issued before the User&nbsp;0 parameter line.<br />
</p><br />
<br />
==APPDATE command usage notes==<br />
<ol><br />
<li>One kind of application testing is simply to see what happens when dates into the<br />
21st century are returned by SOUL $functions. This can be done in<br />
isolation by issuing a command such as the following:<br />
<p class="code">APPDATE USER 2000/01/01 </p><br />
<p><br />
This can be simply issued by the user before entering the application, or it can be<br />
issued in the startup or logon proc of the application.</p></li><br />
<br />
<li>If your application stores results that are retrieved later by the application, you should probably put a command such as the following into the startup proc:<br />
<p class="code">APPDATE USER 2000/01/01 AT 1997/05/01 </p><br />
<p><br />
This indicates that the application clock will run ahead of the internal date and time so that on the 1st of May, 1997, the application clock will show the 1st of January, 2000. Your application can thus run as if it were "shifted" ahead in time, and the shift amount will be consistent, even if you bring down the online and bring it up again. It is recommended that you place it in the startup procedure in case any dates are referenced in it.</p></li><br />
<br />
<li>If you want all applications (except those "shielded" as in item 5, below) to use the same clock, you need not change any applications but simply code before the User&nbsp;0 parameter line:<br />
<p class="code">APPDATE SYSTEM 2000/01/01 AT 1997/05/01 </p><br />
<p><br />
Note that this also changes the default <var>DEFCENT</var>; see item 6, below. </p></li><br />
<br />
<li>If you have an application that must use the internal date and time, even if the system-wide application clock is ON, you should enter a command such as the<br />
following in the startup procedure:<br />
<p class="code">APPDATE USER INTERNAL </p><br />
<p><br />
This could be needed by an application that examines internal datetime values,<br />
such as those found in the audit trail. A robust application will preserve the<br />
<var>APPDATE</var> value and can do this using the <var>[[$CommndL]]</var> function, since an [[Sdaemons|sdaemon]] thread initiated with $COMM<i>xxx</i> copies the application clock of its invoker. </p></li><br />
<br />
<li>A good date for <var>APPDATE</var> testing might be <code>2000/02/29</code>, since that is a valid date, but <code>1900/02/29</code> is <em>not</em>. </li><br />
<br />
<li>The use of the <var>APPDATE</var> command is to establish a clock for all application-level operations. It does not affect static values that had been established prior to the <var>APPDATE</var> command. This is relevant to the value of the <var>BASECENT</var> parameter and the default value of the <var>DEFCENT</var> user parameter, as follows:<br />
<ul><br />
<li>If the <var>DEFCENT</var> parameter has not been set, its value is the first two digits of the year during Model&nbsp;204 initialization. An <code>APPDATE SYSTEM ON ...</code> command issued before the User&nbsp;0 parameter line affects the default value of <var>DEFCENT</var>. All other invocations of the <var>APPDATE</var> command leave <var>DEFCENT</var> unaffected. </li><br />
<br />
<li>The <var>BASECENT</var> parameter is calculated based on the current time whenever the <var>CENTSPLT</var> parameer is set. This current time is taken from the active <var>APPDATE</var> clock, but subsequent invocations of the <var>APPDATE</var> command do not affect the <var>BASECENT</var> parameter. </li><br />
</ul></li><br />
<br />
<li>The <var>APPDATE</var> command does not affect the date and time printed on header 0 of each output page. </li><br />
<br />
<li>The <var>APPDATE</var> command and the use of the Model&nbsp;204 <var>SYSDATE</var> parameter are mutually exclusive. </li><br />
<br />
<li><var>$Command</var>, <var>$CommBg</var>, and <var>$CommndL</var> (see [[List_of_$functions]]) provide a mechanism for passing a unit of work to an sdaemon or background thread that is different from the thread that issues the request. <br />
<p><br />
When the requested unit of work receives control, the <code>APPDATE USER</code> settings from the thread that invoked the $function will be in effect. If an <code>APPDATE USER</code> command is issued in the sdaemon thread, its effect is not reflected back to the invoking thread. </p></li><br />
<br />
<li>The current application date used by <var>#DATE<i>xxx</i></var> functions in [[FUEL]] is set to the active <var>APPDATE</var> clock when the <var>$FunLoad</var> function is used. </li><br />
</ol><br />
<br />
==See also==<br />
{{Template:Sir2000 topic list}}<br />
<br />
[[Category: Sir2000 User Language Tools]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Sir2000_User_Language_Tools&diff=105106Sir2000 User Language Tools2018-02-08T22:00:52Z<p>Admin: 1 revision imported</p>
<hr />
<div>==Overview==<br />
The <var class="product">Sir2000 User Language Tools</var> is a package of products designed to help you change and test User Language ([[SOUL]]) applications for correct operation across the millennium rollover. The package consists of several components that are described below.<br />
<br />
===The APPDATE command===<br />
<p><br />
The <var>[[The Sir2000 APPDATE command|APPDATE]]</var> command allows you to control the operation of date and time oriented User Language $functions. </p><br />
<br />
===Date $functions===<br />
<p><br />
Sir2000 User Language Tools includes $functions that manipulate datetime values,<br />
support improved datetime formats, while providing enhanced 2-digit year handling<br />
(<var>CENTSPAN</var>/<var>SPANSIZE</var>) and improved error handling. These $functions replace and/or augment some standard Model&nbsp;204 date-related functions. </p><br />
<br />
====Datetime formats====<br />
The $functions included with the Sir2000 User Language Tools allow you to specify<br />
formats for datetime values that include all of the tokens and separator characters for any common application, including mixed case, variable length, and day of week. Date and time are handled uniformly, and there are no special $function names, special arguments, nor customization parameters to control the date formats.<br />
<br />
To get the current date in a different format with the standard Model&nbsp;204 date $functions, you must specify a special switch and/or use combinations of different $functions, frequently involving string concatenation or substring to deal with composite date and time formats. <br />
<br />
With the Sir2000 date $functions, each function performs some datetime related<br />
calculation, and you can specify a combination of tokens to determine the format,<br />
which may include time of day. For example, the following SOUL code<br />
fragment is required to print the current day of the week using the standard<br />
$functions provided with Model&nbsp;204:<br />
<br />
<p class="code">PRINT $DAY($DAYI($DATECNV('CYY-MM-DD', 'CYYDDD', $DATE(2)))) </p><br />
<br />
With the Sir2000 User Language Tools, this set of nested $function calls becomes:<br />
<p class="code">PRINT $SIR_DATE('Wkday') </p><br />
<br />
You can also get the current date and time conveniently for a report:<br />
<p class="code">%D STRING LEN 40<br />
%D = $SIR_DATE('Wkday, DAY Month YYYY @ HH:MI:SS AM')<br />
SET HEADER 1 %D </p><br />
<p><br />
This sets a line such as the following at the top of each page:<br />
</p><br />
<p class="code">Monday, 1 January 2001 @ 01:11:10 PM </p><br />
<br />
====Processing two digit years (CENTSPAN/SPANSIZE)====<br />
The $functions included with the Sir2000 User Language Tools provide a robust<br />
technique for handling 2-digit years. An optional <var>CENTSPAN</var> argument supplies the beginning of year of the up to 100-year range of dates covered by the two-digit years.<br />
<p><br />
<var>CENTSPAN</var> provides both of these: </p><br />
<ul><br />
<li>An absolute specification, in which the full 4-digit start year is specified </li><br />
<br />
<li>A relative specification, in which the start year is specified relative to the current time, for example, 50 years ago </li><br />
</ul><br />
<p><br />
The default <var>CENTSPAN</var> value is <code>-50</code>. </p><br />
<p><br />
To reduce the ambiguities caused by mapping two-digit years into four digit years,<br />
<var>SPANSIZE</var> is used to limit the number of years mapped. <var>SPANSIZE</var> and its relationship to <var>CENTSPAN</var> is explained in [[Sir2000 datetime processing considerations#CENTSPAN|CENTSPAN]]. The default <var>SPANSIZE</var> is <code>90</code>. </p><br />
<br />
====Error handling====<br />
The $Sir_Date<i>xxx</i> and Sir2000 datetime $functions that process user-provided datetime format strings or datetime values accept an optional last argument that is a character string specifying the action to be taken if the function detects an error. If this argument is omitted, the action taken upon an error is determined by the current state of the <var>USER</var> and <var>SYSTEM</var> switches of <var>DATE_ERR</var>. The <var>DATE_ERR</var> switches can be set by an <var>APPDATE</var> command with a <var>DATE_ERR</var> clause or by the <var>$Sir_Date_Err</var> function. <br />
<br />
<var>DATE_ERR</var> allows the interception of date processing errors at their source, making it much easier to perform ad-hoc testing and validation of date processing. The following error actions can be specified:<br />
<br />
<table class="thJustBold"><br />
<tr><th>CANCEL</th><br />
<td>If a datetime $function (including the non-Sirius functions) detects an error, an error message is produced describing the nature of the error and the current request is cancelled. Sirius datetime $functions produce detailed error messages describing the precise nature of the error. </td></tr><br />
<br />
<tr><th>REPORT</th><br />
<td>If a datetime $function detects an error, a warning message is produced describing the nature of the error, and the appropriate standard error value is returned by the $function. </td></tr><br />
<br />
<tr><th>IGNORE</th><br />
<td>If a datetime $function detects an error, the appropriate standard error value is returned by the $function. </td></tr><br />
</table><br />
<br />
The errors that are detected include:<br />
<ul><br />
<li>Invalid datetime format specification </li><br />
<br />
<li>Datetime string not matching format </li><br />
<br />
<li>Datetime out of range for the format </li><br />
<br />
<li>Invalid <var>CENTSPAN</var> value </li><br />
<br />
<li>Datetime out of range for <var>CENTSPAN</var>/<var>SPANSIZE</var> combination. </li><br />
</ul><br />
<p><br />
In addition, an <var>APPDATE</var> command with a <var>DATE_ERR</var> clause can specify that warning and error messages should include the procedure name and line number of the failing $function. </p><br />
<br />
===Subroutines for FUNU===<br />
Included with the Sir2000 User Language Tools is a set of subroutines that can be invoked by user-provided [[Assembler language subroutines for FUNU|assembler language (FUNU) $functions]] to obtain the current<br />
date and time using the appropriate <var>APPDATE</var> clock, if any. They are compatible with the similar set of subroutines Rocket Model&nbsp;204 provides for current date only, with an additional entry point which allows you to obtain the current date and time using any of the Sirius datetime formats.<br />
<br />
===SirPro===<br />
[[SirPro]] provides a highly productive integrated environment for the development and maintenance of Model&nbsp;204 applications. SirPro efficiently manages very large procedure<br />
files while providing high performance search and global replace features. SirPro also provides a full screen interface for commonly used Model&nbsp;204 commands. <br />
<br />
===SirLib===<br />
[[SirLib]] is a comprehensive change management system for Model&nbsp;204 SOUL<br />
applications. SirLib enables multiple programmers to simultaneously work on the same procedures, with tools for resolving update conflicts and backing out individual changes<br />
or projects. SirLib is modeled on the change control system used by IBM and virtually all large scale mainframe product developers. SirLib support is integrated within SirPro to minimize its intrusion into the development process.<br />
<br />
==Documentation topics==<br />
The <var class="product">Sir2000 User Language Tools</var> documentation consists of the pages listed below. This list is also available as a "See also" link from each of the pages. <br />
<br />
Also:<br />
<ul><br />
<li>See [[List of Model 204 messages#msir|MSIR. messages]] for information about product error messages. </li><br />
<br />
<li>See the [[List of $functions]] for documentation for all $functions except the Sir2000-specific $functions, which are documented in [[List of Sir2000 User Language Tools $functions]].</li><br />
</ul><br />
<br />
===Sir2000 UL Tools topic list===<br />
{{Template: Sir2000 topic list}}<br />
<br />
[[Category: Sir2000 User Language Tools]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Sir2000_User_Language_Tools_$functions&diff=105104Sir2000 User Language Tools $functions2018-02-08T22:00:52Z<p>Admin: 1 revision imported</p>
<hr />
<div>This section lists the $functions that are only available with the Sir2000 User Language Tools, as well as related $functions that are not exclusive to Sir2000 User Language Tools. In addition to a link to each $function's description page, the listing includes a brief phrase denoting its use.<br />
<br />
The $function list is followed by a discussion of datetime error handling.<br />
<br />
==Sir2000 UL Tools $functions==<br />
The following $functions are provided with Sir2000 User Language Tools, some of which are also available to other Model&nbsp;204 products. Those $functions that are available only to the Sir2000 User Language Tools product are indicated as "exclusive."<br />
<table><br />
<tr class="head"><th>$Function</th><br />
<th>Description</th><br />
<th>Exclusive to <br>Sir2000 UL Tools?</th></tr><br />
<br />
<tr><td>[[$Sir_Date_Err]]</td><br />
<td>Set and query default error handling at request level </td><br />
<td>Yes</td></tr><br />
<br />
<tr><td>[[$Sir_DateChg]]</td><td>Add some days to datetime </td><br />
<td>Yes</td></tr><br />
<br />
<tr><td>[[$Sir_DateChk]]</td><td>Check if datetime matches format </td><br />
<td>Yes</td></tr><br />
<br />
<tr><td>[[$Sir_DateCnv]]</td><td>Convert datetime to different format </td><br />
<td>Yes</td></tr><br />
<br />
<tr><td>[[$Sir_DateDif]]</td><td>Calculate difference between two dates </td><br />
<td>Yes</td></tr><br />
<br />
<tr class="head"><th colspan="3">"Sir_Date<i>xxx</i>" functions</th></tr><br />
<br />
<tr><td>[[$Sir_Date]]</td><td>Get current datetime </td><br />
<td>No</td></tr><br />
<br />
<tr><td>[[$Sir_DateFmt]]</td><td>Validate datetime format </td><br />
<td>No</td></tr><br />
<br />
<tr><td>[[$Sir_DateN|$Sir_DateN/ND/NM/NS]]</td><td>Current date and time as integer </td><br />
<td>No</td></tr><br />
<br />
<tr><td>[[$Sir_Date2N|$Sir_Date2N/ND/NM/NS]]</td><td>Convert datetime string to integer </td><br />
<td>No</td></tr><br />
<br />
<tr><td nowrap>[[$Sir_ND2Date|$Sir_ND2Date/NM2Date/NS2Date/N2Date]]</td><td>Convert datetime integer to string </td><br />
<td>No</td></tr><br />
</table><br />
<br />
==Errors in datetime $functions==<br />
Sir2000 User Language Tools provides you with several ways to detect datetime related errors and control the action taken by the system when these errors occur. <br />
<ul><br />
<li>On a system-wide or thread-only basis, by using an [[The Sir2000 APPDATE command#Error handling control with DATE_ERR|APPDATE DATE_ERR command]] </li><br />
<br />
<li>On a request level, by using the <var>[[$Sir_Date_Err]]</var> function </li><br />
<br />
<li>In The $Sir_Date<i>xxx</i> and Sir2000 $function calls, by coding a special argument </li><br />
</ul> <br />
<br />
You can also control error handling in some standard SOUL date $functions by using <br />
<code>APPDATE DATE_ERR</code> or <var>$Sir_Date_Err</var>.<br />
<br />
If you intend to use the $function error handling features of Sir2000 User Language<br />
Tools, you should also be sure to use the [[The Sir2000 APPDATE command#Setting default error handling with the APPDATE command|DEBUG feature of APPDATE]]. The <var>DEBUG</var> feature saves line number, procedure, and file information for date-related $functions.<br />
This information, along with argument values, is then displayed and reported to greatly simplify debugging.<br />
<br />
The $Sir_Date<i>xxx</i> and Sir2000 $functions provide an optional error control argument for some datetime $functions. If you omit the error control argument and an error is detected in the $function, the action taken depends upon the latest invocation of <var>$Sir_Date_Err</var>, if any, or the switches established by the relevant <var>APPDATE</var> command with <var>DATE_ERR</var> clause.<br />
<br />
See [[The Sir2000 APPDATE command#Error handling control with DATE ERR|Error handling control with DATE_ERR]] for a complete description of<br />
the type of errors encountered by date $functions, and for the control and detection approaches available to you with the Sir2000 User Language Tools.<br />
<p><br />
For example, since the input date doesn't match the provided format, the following<br />
fragment prints <code>Error incrementing date</code>:<br />
</p><br />
<p class="code">%NEW_DT = $SIR_DATECHG('MM/DD/YY', '96/01/01', 7,, 'IGNORE')<br />
IF %NEW_DT EQ &apos;&apos; OR $SUBSTR(%NEW_DT, 1, 1) = '*' THEN<br />
PRINT 'Error incrementing date'<br />
END IF </p><br />
<p><br />
The following fragment causes the request to be cancelled: </p><br />
<p class="code">%NEW_DT = $SIR_DATECHG('MM/DD/YY', '96/01/01',7,, 'CANCEL') </p><br />
<p><br />
The cancellation comes with an error message: </p><br />
<p class="output"> I DATERR<br />
*** 1 MSIR.0323: Error in $SIR_DATECHG call, no Sirius debug info<br />
- Invalid date<br />
*** MSIR.0326: $SIR_DATECHG - argument 1 = 'MM/DD/YY'<br />
*** MSIR.0326: $SIR_DATECHG - argument 2 = '96/01/01'<br />
*** MSIR.0326: $SIR_DATECHG - argument 3 = '7'<br />
*** MSIR.0326: $SIR_DATECHG - argument 5 = 'CANCEL'<br />
*** 2 CANCELLING REQUEST: MSIR.0324: Cancelling request because of<br />
$SIR_DATECHG error </p><br />
<p><br />
If the <code>APPDATE DATE_ERR DEBUG</code> option is in effect, the SOUL procedure<br />
name and line number will be reported, along with more detail about the error: </p><br />
<p class="output"> APPDATE USER DATE_ERR DEBUG<br />
I DATERR<br />
*** 1 MSIR.0321: Error in $SIR_DATECHG call in line 523, procedure<br />
DATERR, file PROCFILE - Invalid date<br />
*** MSIR.0326: $SIR_DATECHG - argument 1 = 'MM/DD/YY'<br />
*** MSIR.0326: $SIR_DATECHG - argument 2 = '96/01/01'<br />
*** MSIR.0326: $SIR_DATECHG - argument 3 = '7'<br />
*** MSIR.0326: $SIR_DATECHG - argument 5 = 'CANCEL'<br />
*** 2 CANCELLING REQUEST: MSIR.0324: Cancelling request because of<br />
$SIR_DATECHG error </p><br />
<p><br />
Each $function description on this page includes: </p><br />
<ul><br />
<li>The error conditions detected by the $function </li><br />
<br />
<li>The value returned by the $function in case of an error with <code>IGNORE</code> or <code>REPORT</code> specified or defaulted. </li><br />
</ul><br />
<br />
==See also==<br />
{{Template:Sir2000 topic list}}<br />
<br />
[[Category: Sir2000 User Language Tools]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Sir2000_datetime_processing_considerations&diff=105102Sir2000 datetime processing considerations2018-02-08T22:00:52Z<p>Admin: 1 revision imported</p>
<hr />
<div>==Introduction==<br />
This page presents date processing issues, including usage of the Sir2000 User<br />
Language Tools past the year 1999, an explanation of its processing of dates, and any<br />
rules and restrictions you must follow to achieve correct results using date values with the Sir2000 User Language Tools.<br />
<br />
===Sir2000 User Language Tools dates===<br />
The Sir2000 User Language Tools uses dates in the following ways:<br />
<ul><br />
<li>To examine the CPU clock (as returned by the STCK hardware instruction) to<br />
determine the current date, in case the Sir2000 User Language Tools is under a<br />
rental or trial agreement. </li><br />
<br />
<li>As arguments to various $functions, and as returned values from them. </li><br />
<br />
<li>To set a date for testing with the <var>APPDATE</var> command. </li><br />
<br />
<li>See [[SirLib]] and [[SirPro]] for date processing considerations for those products as part of the Sir2000 User Language Tools. </li><br />
</ul><br />
<br />
===Two views of datetime $functions===<br />
<p><br />
This page refers to datetime $functions in two product groups: </p><br />
<ul><br />
<li>The [[SOUL $functions#datetime|$Sir_Date<i>xxx</i> $functions]]<br />
<p><br />
These date $functions are available to users of multiple Model&nbsp;204 add-on products, as well as to Sir2000 User Language Tools users. </p></li><br />
<br />
<li>The [[Sir2000 User Language Tools $functions]]<br />
<p><br />
These $functions are available only to users of the Sir2000 User Language Tools. </p></li><br />
</ul><br />
<p><br />
In <i>operational</i> terms, there are two classes of datetime $functions: </p><br />
<ul><br />
<li>$functions using a numeric value to represent a datetime, where 0 represents<br />
<code>12:00 AM, 1 January 1900</code>; for example, <var>[[$Sir_Date2NM]]</var> and <var>[[$Sir_NM2Date]]</var> (number of milliseconds since the start of 1900).<br />
<p><br />
These $functions, and <var>[[$Sir_Date]]</var>, have the following error return values: </p><br />
<ul><br />
<li>-9.E12 for numeric result $functions </li><br />
<br />
<li>null string for string result $functions </li><br />
</ul><br />
<p><br />
They also perform non-strict matching of date strings to date formats. For example,<br />
a leading blank is allowed for the <var>HH</var> token. </p><br />
<p><br />
All numeric datetime $functions, and <var>$Sir_Date</var>, are part of the <var class="product">[[Sirius Functions]]</var>. </p></li><br />
<br />
<li>Other $functions that only manipulate strings and associated datetime formats<br />
(<var>$Sir_Date</var> not included in this class); for example, <var>[[$Sir_DateChg]]</var> (add number of days to given date).<br />
<p><br />
These $functions have error return values of a variable number of asterisks (or, in<br />
the case of <var>[[$Sir_DateDif]]</var>, the value 99,999,999). They also perform strict matching of date strings to date formats; for example, a leading blank is not allowed for the <var>HH</var> token. These $functions produce the same results as standard SOUL [[SOUL $functions#datex|$Date<i>xxx</i> functions]], with additional enhancements. </p><br />
<p><br />
These string-format datetime $functions are available only with the Sir2000 User<br />
Language Tools. </p><br />
<p><br />
See [[#Strict and non-strict format matching|Strict and non-strict format matching]] for a discussion of strict and non-strict format matching, including a technique for accomplishing strict date checking using the non-strict $functions. </p></li><br />
</ul><br />
<p><br />
See [[Sir2000 User Language Tools $functions#Errors in datetime $functions|Errors in datetime $functions]] for information about error handling for datetime $functions. </p><br />
<br />
==Datetime formats==<br />
The string representation of a date is determined by a <b>datetime format</b>.<br />
This value is a character string, composed of the concatenation of these:<br />
<ul><br />
<li>Tokens <br />
<p><br />
For example, <var>YYYY</var> for a four-digit year, and <var>MI</var> for<br />
minutes.</p></li><br />
<br />
<li>Separator characters<br />
<p><br />
For example, forward slash (<tt>/</tt>) in <var>MM/DD/YY</var> for two-digit month, day, and year separated by slashes.</p></li><br />
</ul><br />
<p><br />
These datetime format strings are used in several Rocket Model&nbsp;204 add-on products in addition to <var class="product">Sir2000</var>.<br />
The additional products using datetime format strings are: </p><br />
<ul><br />
<li><var class="product">[[Fast/Unload]]</var> </li><br />
<br />
<li><var class="product">[[Media:JoclrNew.pdf|Janus Open Client]]</var> </li><br />
<br />
<li><var class="product">[[Media:JosrvrNew.pdf|Janus Open Server]]</var><br />
</li><br />
<br />
<li><var class="product">[[Media:JsdsrNew.pdf|Janus Specialty Data Store]]</var> </li><br />
<br />
<li><var class="product">[[Janus Web Server]]</var> </li><br />
<br />
<li><var class="product">[[SirDBA]]</var> </li><br />
<br />
<li><var class="product">[[Sirius Functions]]</var> </li><br />
<br />
<li><var class="product">[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</var> </li><br />
</ul><br />
<!-- Note: all the above products imbed the SCRIPT file COMDATE except Janus Web --><br />
<p><br />
The rules for these datetime format strings are consistent throughout all these products, though certain uses of these strings might impose extra restrictions.<br />
For example, a leading blank is allowed for the <var>HH</var>, <var>DD</var>, and <var>MM</var> parts of a date argument using a non-strict date $function (such as<br />
<var>[[$Sir_Date2NS]]</var>), but such a blank is not allowed for the strict date $functions ([[Sir2000 User Language Tools $functions]]). </p><br />
{{Template:Datetime rules, tokens, and separators}}<br />
<br />
==Valid datetimes==<br />
For a datetime string to be valid it must meet the following criteria:<br />
<ul><br />
<li>Its length must be less than 128 characters. </li><br />
<br />
<li>It must be compatible with its corresponding format string. </li><br />
<br />
<li>It must represent a valid date and/or time. <br />
<p><br />
For example, at most <code>23:59:59.999</code> for a time, <code>01-12</code> for a month, <code>01-31</code> or less (depending on the month) for a day. February 29 is only valid<br />
in leap years (only centuries divisible by 4 are leap years: 2000 is but neither 1800, 1900, nor 2100 are). <br />
</p><br />
<p class="note"><b>Note:</b> Weekdays are not checked for consistency against the date. For example, both <code>Saturday, 02/15/97</code> and <code>Friday, 02/15/97</code> are valid. </p> </li><br />
<br />
<li>It must be within the date range allowed for the corresponding format.<br />
<p><br />
A datetime string used with a <var>CYY</var> or <var>ZYY</var> format can only represent dates from 1900 to 2899, inclusive.<br />
A datetime string used with a <var>YY</var> format can only represent<br />
dates in a range of 100 or less years, as determined by <var>CENTSPAN</var> and<br />
<var>SPANSIZE</var> (described below).<br />
The valid range of dates for all other formats is from <code>1 January 1753</code><br />
thru <code>31 December 9999</code>. </p></li><br />
</ul><br />
<br />
==Processing dates with two-digit year values==<br />
{{Template:Processing dates with two-digit year values}}<br />
<br />
==Strict and non-strict format matching==<br />
As mentioned in [[#Datetime formats|Datetime formats]], for some of the $functions,<br />
the input format rule for a token is the same as the output format rule.<br />
This is the definition of "strict date format matching."<br />
However, non-strict $functions sometimes allow a string to match a token on input that would not be produced by that token on output.<br />
<p><br />
The types of strict matching are as follows: </p><br />
{{Template:Datetime format matching}}<br />
<br />
The strict functions are available only with the <var class="product">Sir2000 User Language Tools</var>. If you want to use non-strict date $functions to check a datetime string using strict rules, you can use the following technique:<br />
<p class="code">If <i>date</i> Eq &apos;' Or <i>date</i> NE $Sir_NM2Date(-<br />
$Sir_Date2NM(<i>date</i>, <i>fmt</i>), <i>fmt</i>) Then<br />
<i>error handling</i><br />
End If<br />
</p><br />
<br />
==Datetime and format examples==<br />
There is an extensive set of format tokens, as shown in [[#Datetime format tokens|Datetime format tokens]]. These tokens and the various separator characters<br />
can be combined in almost limitless possibility, giving rise to an extremely large set of datetime formats.<br />
This section provides examples of some common datetime formats, and it<br />
also tries to explain the use of some of the format tokens that might not be obvious.<br />
<p><br />
This section also has examples for<br />
formats used with <var class="product">Sir2000 Use Language Tools</var> that differ from their usage with other <var class="product">Model&nbsp;204</var> products.<br />
These are noted in the examples. </p><br />
<p><br />
Each example format is explained and is also presented with some matching<br />
datetimes, demonstrating only a few of the very many ways these tokens can be combined. It is assumed that these examples are invoked sometime between the<br />
years 1998-2040, as the basis for relative <var>CENTSPAN</var> calculations.<br />
</p><br />
{{Template:Datetime and format examples}}<br />
<br />
==CENTSPAN argument of $Sir_Datexxx functions==<br />
<p><br />
Many of the $Sir_Date<i>xxx</i> functions accept an optional argument<br />
containing a <var>CENTSPAN</var> value to be used for the call.<br />
The default value of any <var>CENTSPAN</var> argument is <code>-50</code>, excepting the [[$Web_Date2D, $Web_Date2N, $Web_Date2ND, $Web_Date2NM, $Web_Date2NS|$Web_Date2<i>xx</i>]] functions without a format argument, in<br />
which case the <var>CENTSPAN</var> argument is ignored and a <var>CENTSPAN</var> of <code>1990</code> is used. <br />
The default value should be adequate in most cases. If you carefully determine it should be different in some application, code the value on the relevant $function invocations.</p><br />
<p><br />
For a different approach, see the description of the <var>[[CENTSPLT parameter|CENTSPLT]]</var> and <var>[[DEFCENT parameter|DEFCENT]]</var> parameters and $function arguments.</p><br />
<br />
==Benefits of Sir2000 datetime processing==<br />
<p><br />
Following is a list of benefits offered by <var class="product">Sir2000</var><br />
and $Sir_Date<i>xxx</i> datetime processing. To provide concrete comparisons, there<br />
are some references to the standard <var class="product">SOUL</var> date $functions. </p><br />
{{Template:Benefits of $Sir Datexxx datetime processing}}<br />
<br />
==See also==<br />
{{Template:Sir2000 topic list}}<br />
<br />
[[Category:Sir2000 User Language Tools]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Assembler_language_subroutines_for_FUNU&diff=105100Assembler language subroutines for FUNU2018-02-08T22:00:52Z<p>Admin: 1 revision imported</p>
<hr />
<div>If your site has coded its own dollar functions that obtain the system date or time, you need to modify these functions to work correctly with the [[The Sir2000 APPDATE command#Setting clocks with the APPDATE command|APPDATE clocks]]. Sir2000 User Language Tools provides four entry points to assist you in this conversion effort.<br />
<br />
Three of these entry points (SDATE4, SDATE3, and SDATE) are compatible with entry<br />
points provided in Model&nbsp;204 V4R1 for FUNU (DATE4, DATE3, and DATE). In<br />
addition, a fourth entry point, SDATEF, lets you obtain the current date and time<br />
using any of the datetime formats described in [[Sir2000 datetime processing considerations#Datetime formats|Datetime formats]].)<br />
<br />
If a datetime argument error occurs during execution of these subroutines, the error<br />
handling performed is controlled by T3 in the case of SDATEF, or by the<br />
<var>$Sir_Date_Err</var> or [[The Sir2000 APPDATE command#Error handling control with DATE_ERR|APPDATE DATE_ERR settings]]. The datetime argument errors that can occur are:<br />
<ul><br />
<li>Invalid format, for SDATEF </li><br />
<br />
<li>Date out of range, for SDATE3 (if you used <var>APPDATE</var> to set your application clock outside the range 1900-2899) </li><br />
</ul><br />
<p><br />
The subroutines are summarized below: <br />
</p><br />
<p class="code">SDATE4 — Datetime routine for FUNU, with 4-digit year.<br />
SDATE3 — Datetime routine for FUNU, with 3-digit year.<br />
SDATE — Datetime routine for FUNU, with 2-digit year.<br />
SDATEF — Datetime routine for FUNU, format specified by argument.<br />
<br />
All of the SDATE/3/4/F routines obtain the time based<br />
on the current active APPDATE clock.<br />
<br />
Input T1 — Address of area for result<br />
T2 — Address of counted format (SDATEF)<br />
T3 — Address of error handling string (SDATEF); values may be:<br />
CANCEL — Cancel request<br />
IGNORE — Return T4=1<br />
REPORT — Issue error message, return T4=1<br />
OFF — $SIR_DATE_ERR and APPDATE DATE_ERR<br />
determine error handling action<br />
<br />
Returns T4 — Month number (1-12) (SDATE/3/4)<br />
T4 — 0: format OK, 1 format bad (SDATEF)<br />
Output area set to current date & time:<br />
SDATE4: YYYY.DDD MON DD HH:MI:SS (26 bytes)<br />
SDATE3: CYY.DDD MON DD HH:MI:SS (25 bytes)<br />
SDATE: YY.DDD MON DD HH:MI:SS (24 bytes)<br />
SDATEF: Counted string datetime, in format requested.<br />
T1-T3, T5, R6-R1 preserved. </p><br />
<br />
==See also==<br />
{{Template:Sir2000 topic list}}<br />
<br />
[[Category:Sir2000 User Language Tools]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Template:SirTune_installation&diff=104094Template:SirTune installation2017-08-11T19:39:03Z<p>Admin: Admin moved page SirTune installation to Template:SirTune installation without leaving a redirect: reduce number of topics</p>
<hr />
<div>SirTune consists of an object file (for data collecting) as well as SOUL files (for reporting).<br />
As of SirTune 7.1, the object code was integrated into [[Sirius Mods]], and as of Model&nbsp;204 7.5, Sirius Mods was integrated into the Model&nbsp;204 nucleus. Thus, if you are running Model&nbsp;204 7.5 or later and you are authorized to use SirTune, the necessary object code is already installed into Model&nbsp;204.<br />
<br />
In addition to the object code, you need to download and install the SirTune SOUL files to run SirTune reports, and this is covered in the following section.”<br />
<br />
==SirTune object file==<br />
If you are running a pre-7.5 version of Model&nbsp;204 and want to refresh the SirTune object file, you can download the "Sirius Mods" object file from the Rocket Software<br />
website "Rocket M204 Customer Care" page ([http://m204.rocketsoftware.com/ http://m204.rocketsoftware.com]). <br />
<br />
The SirTune object file is integrated into the Sirius Mods object file <i>until</i> Model&nbsp;204 7.5; thereafter it is part of the Model&nbsp;204 object.<br />
The download process requires a Model&nbsp;204 user ID and password.<br />
<ol><br />
<li>On the "Rocket M204 Customer Care" page, go to the "Downloads and Uploads" section and click the "Download object files" link.<br />
<p><br />
After providing Model&nbsp;204 login credentials, you access the "Download object files" page, which contains a dynamically-generated list of the various Model&nbsp;204 object files that you are authorized to download. </p></li> <br />
<br />
<li>Select the Sirius Mods row for the version you require, and click the "Download object file" link. </li><br />
</ol><br />
<br />
==SirTune SOUL files==<br />
SirTune report generation is performed by a [[SOUL]] program<br />
that is distributed as part of the <var class="product">[[RKTools]]</var> product family in the <code>SIRIUS</code> file (for versions of RKTools prior to 7.7) or the <code>M204PROC</code> file (as of RKTools 7.7).<br />
<ul><br />
<li>If your site uses <var class="product">RKTools</var>, verify that file <code>SIRIUS</code> or <code>M204PROC</code> contains the program <code>SIRTUNEREPORT</code>. If the RKTools version is 7.7 or higher, you can use the [[RKWeb]] interface to view SirTune report output on your browser. [[RKTools installation]] has information about RKTools and RKWeb installation. </li><br />
<br />
<li>If your site is not licensed for <var class="product">RKTools</var>, you are still authorized (as a user of <var class="product">SirTune</var>) to download the <code>SIRIUS</code> or <code>M204PROC</code> file.<br />
You can download the file from the Rocket website: <br />
<ol><br />
<li>On the "SOUL files" page, click the "SOUL files" link in the "Downloads and Uploads" section. </li><br />
<br />
<li>On the [http://m204.rocketsoftware.com/ Rocket M204 Customer Care] page, find the appropriate row for your version of RKTools, and click the "Download Procfile" link. </li><br />
</ol><br />
<p><br />
You don't need to do the entire <var class="product">RKTools</var> installation: just download and restore the <code>SIRIUS</code> or <code>M204PROC</code> file, and make it available to your [[SirTune reports|SirTune report]] jobs. </p></li><br />
</ul><br />
<br />
==See also==<br />
{{Template:SirTune topic list}}<br />
<br />
[[Category: SirTune]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=MediaWiki:Common.css&diff=104084MediaWiki:Common.css2017-08-11T18:10:43Z<p>Admin: tweak superstar class for toc</p>
<hr />
<div>/* CSS placed here will be applied to all skins */<br />
/* See also MediaWiki:Vector.css, MediaWiki:MonoBook.css, <br />
/* MediaWiki:Modern.css */<br />
<br />
/* *** NOTE: MANY SKIN TWEAKS ARE SPECIFIED IN MediaWiki:Vector.css *** /*<br />
<br />
/* following comment won't work for IE>9 */<br />
<!-[if gte IE8]<br />
<linkrel=”stylesheet” type=”text/css” href=”/stylesheets/standards.css”/><br />
<![endif]-><br />
<br />
/* current practice is to use p class="code" instead of this pre tag */<br />
pre {<br />
overflow-x: auto; /* Use horizontal scroller if needed; for FF2, not needed in FF3 */<br />
overflow-y: hidden; /* overflow-x above messes up Chrome, this is the fix. Sigh */<br />
white-space: pre-wrap; /* css-3 */<br />
white-space: -moz-pre-wrap !important; /* Mozilla, since 1999 */<br />
white-space: -pre-wrap; /* Opera 4-6 */<br />
white-space: -o-pre-wrap; /* Opera 7 */ /*<br />
width: 99%; */<br />
word-wrap: break-word; /* Internet Explorer 5.5+ */<br />
}<br />
<br />
p.pre, p.code, p.codeInTable, p.output, p.syntax, p.syntaxUL, p.pre pre.syntax {<br />
color: #000;<br />
background-color: #f9f9f9;<br />
padding: 5px 5px 5px 10px;<br />
border: 1px dashed #4169E1;<br />
font-family: Consolas,"Liberation Mono",monospace;<br />
line-height: 1.2;<br />
vertical-align: baseline;<br />
white-space: pre; /* pre-wrap OK if IE>=11, but we want code not to wrap */<br />
overflow: auto; <br />
}<br />
<br />
p.codeInTable {<br />
border:0; <br />
padding:0;<br />
margin-top:0;<br />
font-family: Consolas,"Liberation Mono",monospace;<br />
}<br />
<br />
p.syntaxUL {<br />
line-height: 1.35; <br />
display: inline-block;<br />
}<br />
<br />
/* make bold in syntax larger */<br />
.syntax b {<br />
font-size: 105%;<br />
}<br />
<br />
p.syntaxUL~hr {<br />
height: 2px;<br />
margin: 2px 0;<br />
}<br />
<br />
span.squareb {<br />
font-size: 105%;<br />
font-weight: bold;<br />
color: black;<br />
}<br />
<br />
span.literal {<br />
font-style: normal;<br />
color: #501010;<br />
}<br />
<br />
span.term {<br />
font-style: italic;<br />
color: #000;<br />
}<br />
<br />
<br />
span.boldGreen {<br />
font-weight: bold;<br />
color: green;<br />
}<br />
<br />
/* for error-message page subtitle */<br />
span.msgtext {<br />
font-family: Arial, Helvetica, sans-serif; <br />
font-size:150%;<br />
line-height:1.5em;<br />
}<br />
<br />
/* the following tag is designed for the superscript star in Connect*; */<br />
/* HTML superscript tag (sup) makes star char (&#9733;) too large and lines displace */<br />
span.superstar, span.toctext span {<br />
font-size: .6em;<br />
vertical-align: baseline;<br />
position: relative;<br />
top: -0.5em;<br />
}<br />
<br />
.pageBreak { page-break-before: always; }<br />
<br />
<br />
/* table element variations *************************************************** */<br />
<br />
/* thJustBold for a table with non-heading <th>s bold but not italicized */<br />
/* also see tr.head, below */<br />
table, table.list table.thJustBold {<br />
margin: 1em 1em 1em 0;<br />
background: #f9f9f9;<br />
border: 1px #aaa solid;<br />
border-collapse: collapse;<br />
}<br />
th, td, .list th, .list td, .thJustBold th, .thJustBold td {<br />
border: 1px #aaa solid;<br />
padding: 0.5em;<br />
text-align: left;<br />
vertical-align: top;<br />
}<br />
<br />
td.bold {<br />
font-weight: bold;<br />
}<br />
<br />
/* JAL added explicit bkgrd color to preserve it in table column *headings* in a */ <br />
/* class=thJustBold table */<br />
tr.head > th {<br />
vertical-align: bottom;<br />
white-space: nowrap;<br />
font-style: normal;<br />
background: #f2f2f2;<br />
}<br />
<br />
th, .list th {<br />
font-style: italic;<br />
background: #f2f2f2;<br />
}<br />
<br />
/* if <th> in first columns in table *content* in a class thJustBold table, make sure */ <br />
/* tr class=head for column headings */<br />
.thJustBold th {<br />
font-style: normal;<br />
background: #f2f2f2;<br />
}<br />
<br />
th var, th var.term {<br />
font-weight: bold;<br />
font-size: 100%;<br />
color: black;<br />
}<br />
<br />
table.optionTable {<br />
margin: 0;<br />
border: none;<br />
border-collapse: collapse;<br />
}<br />
<br />
table.noBorder {<br />
margin: 0;<br />
border: none;<br />
border-collapse: collapse;<br />
background-color: transparent;<br />
}<br />
<br />
table.noBorder th, table.noBorder td {<br />
border: none;<br />
}<br />
<br />
table.nested {<br />
margin: 0;<br />
border: hidden;<br />
border-collapse: collapse;<br />
}<br />
<br />
table table.nested th {<br />
border: hidden;<br />
}<br />
<br />
/* following two tweaks tighten spacing for search result list items */<br />
table.gsc-table-result {<br />
margin: 0;<br />
}<br />
<br />
table.gsc-resultsHeader {<br />
display: none;<br />
}<br />
<br />
/* for the List of MSIR and M204 message tables ************* */<br />
/* more visible vertical borders & merges msg num w/ its text */<br />
table.msgList {<br />
border: 2px #aaa solid;<br />
}<br />
<br />
.msgList th {<br />
border-right-style:none;<br />
border-left:2px solid #aaa;<br />
font-style: normal;<br />
background: #f9f9f9;<br />
}<br />
<br />
.msgList td {<br />
border-left-style:none;<br />
}<br />
<br />
/* for SoftSpy message tables ****************************** */<br />
table.message {<br />
margin: 0;<br />
border: none;<br />
border-collapse: collapse;<br />
background-color: transparent;<br />
}<br />
<br />
table.message th {<br />
border: none;<br />
font-style: normal;<br />
white-space: nowrap;<br />
}<br />
<br />
table.message td {<br />
border: none;<br />
}<br />
<br />
table.message tr:first-child th {<br />
min-width: 7em;<br />
}<br />
<br />
table.message tr:first-child td {<br />
font-weight: bold;<br />
}<br />
<br />
table.message~hr {<br />
height: 2px;<br />
margin: 1em 0;<br />
}<br />
/* ******************************************************* */<br />
<br />
code, p.output {<br />
background-color: #F0F0F9;<br />
}<br />
<br />
var {<br />
font-style: normal;<br />
font-weight: bold;<br />
font-size: 95%;<br />
color: #555;<br />
}<br />
/* tentatively removed from above: text-transform: capitalize; */ <br />
<br />
/* link-within-var */<br />
var a:link {<br />
color: #5353EF;<br />
}<br />
<br />
var a:visited {<br />
color: #5353EF;<br />
}<br />
<br />
var.syntax {<br />
font-size: 100%;<br />
color: black;<br />
}<br />
<br />
var.term {<br />
text-transform: none;<br />
font-style: italic;<br />
font-weight: normal;<br />
font-size: 100%;<br />
color: black;<br />
}<br />
<br />
/* Sirius style was italic */<br />
var.product {<br />
text-transform: none;<br />
color: black;<br />
font-style: normal;<br />
font-weight: normal;<br />
font-size: 100%;<br />
}<br />
<br />
/* JAL added 04/13 */<br />
var.book {<br />
color: black;<br />
font-style: italic;<br />
font-weight: normal;<br />
font-size: 100%;<br />
}<br />
<br />
/* darker color used when font-style was italic */<br />
/* Otherwise product links are very faint */<br />
/* var.product a { color: #002bb8; } */<br />
<br />
var.camel {<br />
text-transform: none;<br />
}<br />
<br />
/* prevent break before parens for terms like %(System in IE and Chrome */<br />
var.nobr {<br />
white-space: pre;<br />
}<br />
<br />
pre var {<br />
font-weight: bold;<br />
}<br />
<br />
.pageSubtitle {<br />
font-size:120%;<br />
color:black;<br />
font-weight: bold;<br />
}<br />
<br />
a:visited {<br />
color: #002bb8;<br />
}<br />
<br />
/* The "normal" source of the #bodyContent styles is the monobook css file on lin875 */<br />
/* make links to non-wiki targets same color as non-var wiki links */<br />
#bodyContent a.external:link,<br />
#bodyContent a.external:visited {<br />
color: #002bb8;<br />
}<br />
<br />
.showVisit a:link {<br />
color: #002bb8;<br />
}<br />
.showVisit a:visited {<br />
color: #5a3696;<br />
}<br />
.showVisit a:hover {<br />
text-decoration: underline;<br />
}<br />
.showVisit a:active {<br />
color: #faa700;<br />
}<br />
.showVisit a.new, #p-personal a.new {<br />
color: #ba0000;<br />
}<br />
.showVisit a.new:visited, #p-personal a.new:visited {<br />
color: #a55858;<br />
}<br />
<br />
/* to caption a table, as child of a "table" tag */<br />
caption {<br />
font-weight: bold;<br />
font-size: 110%;<br />
padding-bottom: .6em;<br />
}<br />
<br />
/* use for fig (image) caption; as class for "p" tag; compare with "caption" above */<br />
/* use style="width:XXpx" on "p" tag to center precisely; XX is width of graphic */<br />
/* or use style="margin-right:XXem" to ctr a non-image manually; XX often around 15 */<br />
/* then "p class=figure" before the image & append image sz in its "File:" value */<br />
/* IE wraps caption if it is wider than the image */<br />
.caption, div#content p.caption {<br />
color: black;<br />
font-size: 100%;<br />
font-weight: bold;<br />
text-align: center;<br />
line-height: 100%;<br />
margin-left: 1.6em;<br />
margin-top: 2em;<br />
margin-bottom: 1.6em;<br />
}<br />
<br />
.figure, div#content p.figure {<br />
margin-left: 1.6em;<br />
margin-top: 1.6em;<br />
margin-bottom: 2em;<br />
}<br />
<br />
<br />
/* enclose non-single-paragraph Notes with blockquote class="note". */<br />
/* Otherwise, use p class="note" */<br />
/* use noteN class to automatically get a bolded "Note:" term */<br />
.note, div#content p.note, .noteN, div#content p.noteN {<br />
margin-left: 15px;<br />
margin-right: 30px;<br />
border: none;<br />
padding: 0px;<br />
}<br />
<br />
/* auto-provision of bold text "Note:" */<br />
.noteN:before {<br />
content: "Note: ";<br />
font-weight: bold;<br />
}<br />
<br />
<br />
li *.note, td *.note, th *.note, li *.noteN, td *.noteN, th *.noteN {<br />
margin-left: 10px;<br />
margin-right: 30px;<br />
border: none;<br />
padding: 0px;<br />
}<br />
<br />
/* enclose non-single-paragraph Cautions & Warnings with blockquote class="warn". */<br />
/* Otherwise, use p class="warn" */<br />
.warn, div#content p.warn {<br />
margin-left: 20px;<br />
margin-right: 60px;<br />
margin-top: 1em;<br />
margin-bottom: 1em;<br />
text-align: justify;<br />
border-top: 1px solid #000;<br />
border-bottom: 1px solid #000;<br />
padding: 5px 5px 5px 10px;<br />
}<br />
<br />
/* used by message on Sirius $function pgs; consider .warn class (above) instead */<br />
.warning {<br />
color: #990000;<br />
font-style: italic;<br />
}<br />
<br />
.smallAndTightList {<br />
line-height: 1.3;<br />
}<br />
<br />
ul.nobul li {<br />
list-style-type: none;<br />
list-style-image: none;<br />
margin-left: 0;<br />
}<br />
<br />
ul.nobulnoindent li {<br />
list-style-type: none;<br />
list-style-image: none;<br />
margin-left: 0;<br />
text-indent: -1.5em;<br />
}<br />
<br />
/* square bullets for lower-level nested lists */<br />
ul li ul {<br />
list-style-type:square;<br />
list-style-image: none;<br />
}<br />
<br />
/* HTML for types of ordered list doesn't work in wiki, hence the following CSS */<br />
ol.low-al li {<br />
list-style-type:lower-alpha;<br />
}<br />
<br />
<br />
/** * Allow limiting of which header levels are shown in a TOC;<br />
* <div class="toclimit-3">, for instance, will limit to<br />
* showing ==headings== and ===headings=== but no further.<br />
* Used in [[Template:TOCright]]; see MediaWiki's Template:TOC page<br />
*/<br />
<br />
.toclimit-2 .toclevel-1 ul,<br />
.toclimit-3 .toclevel-2 ul,<br />
.toclimit-4 .toclevel-3 ul,<br />
.toclimit-5 .toclevel-4 ul,<br />
.toclimit-6 .toclevel-5 ul,<br />
.toclimit-7 .toclevel-6 ul {<br />
display: none; <br />
}<br />
<br />
/* selectively suppress TOC numbering -- put TOC within div class=autonum */<br />
.noautonum .tocnumber { <br />
display: none; <br />
}<br />
<br />
/* add top space to TOC */<br />
div#toc.toc {<br />
margin-top:1em;<br />
}<br />
<br />
/* squeeze footer list items a bit to fit Sirius copyright claim */<br />
#footer li {<br />
margin:0 1em;<br />
}<br />
<br />
/* use same red as Sirius PDFs */<br />
h1 {<br />
color: #660000;<br />
font-family: Arial, Helvetica, sans-serif;<br />
}<br />
<br />
h2 { <br />
font-family: Arial, Helvetica, sans-serif;<br />
color: #660000;<br />
}<br />
<br />
div#content h3 {<br />
font-size: 1.25em; <br />
}<br />
<br />
h5, h6, div#content h5, div#content h6 {<br />
font-style: italic;<br />
font-size: 92%; <br />
}<br />
<br />
tt {<br />
font-family: Consolas, "Liberation Mono", monospace;<br />
font-size:105%;<br />
}<br />
<br />
/* two cosmetic tweaks for Category page sections to remove some extra space */<br />
div#mw-subcategories h3 {<br />
padding-top:0px;<br />
margin-top:0px;<br />
}<br />
<br />
div#mw-pages h3 {<br />
padding-top:0px;<br />
}<br />
<br />
/* redirect pgs that have Category tag won't have italicized names on cat pg: */<br />
.redirect-in-category {<br />
font-style: normal;<br />
}<br />
<br />
code {<br />
font-family: Consolas,"Liberation Mono",monospace;<br />
}<br />
<br />
/** <br />
* make toggle text/icon display to the left of toggled content; <br />
* but elements after this floated element will try to flow around it,<br />
* so after the collapsible element's closing tag, specify <br close="all"><br />
*/<br />
.mw-collapsible span.mw-collapsible-toggle { float: left; }<br />
<br />
/* indent collapsed text to line-up with h2 title text */<br />
div.mw-collapsible-content {<br />
margin-left:2.32em;<br />
}<br />
<br />
<br />
/* ************************changes for Vector default ***************************** */<br />
/* hides sidebar Toolbox (so we can substitute our own set of items) */<br />
#p-tb { display:none; <br />
}<br />
<br />
/* for Monobook, widens sidebar boxes a tiny bit */<br />
.portlet {<br />
width: 11.75em;<br />
}<br />
<br />
/* for Monobook, reduces (moves right) page content area a tiny bit */<br />
/* b/c IE doesn't respond, need to snug box padding (see 'portlet pBody', below) */<br />
div#content { <br />
margin-left: 12.4em; /* not needed for Vector */<br />
}<br />
<br />
/* four tweaks to increase Vector sidebar width and make associated adjustments; */<br />
/* see also MediaWiki:Vector.css */<br />
div#mw-panel { <br />
width: 11.5em;<br />
padding-left: 0; /* was .5, which is not needed if centering vector */ <br />
left:auto; /* for Vector centering project */<br />
}<br />
<br />
#left-navigation { <br />
left: 11em;<br />
margin-left: 11.5em; /* increase of .5 for Vector centering project */<br />
}<br />
<br />
div#content.mw-body { <br />
margin-left: 11.5em; /* increase of .5 for Vector centering project */<br />
border-width: 1px; /* blue right border for Vector centering project */<br />
}<br />
<br />
div#footer ul {<br />
margin-left: 1em;<br />
}<br />
<br />
<br />
/* Monobook: for IE, lets sidebar box close on right by reducing the right padding */<br />
.portlet .pBody {<br />
padding-right: .1em;<br />
}<br />
<br />
/* Vector: used to widen sidebar boxes a tiny bit by larger padding to right */<br />
/* moving some divs undid that, so reducing it gives more room to text items */<br />
.portal .body {<br />
padding-right: .5em;<br />
} <br />
<br />
/* Monobook: rmv box from containing class of "What's New" element; tweak bot space */<br />
#p-\.C2\.A0.generated-sidebar.portlet .pBody {<br />
background-color:transparent;<br />
border:0px hidden transparent;<br />
padding-bottom: 0em; <br />
}<br />
<br />
/* for Monobook, removes bullet graphic, chngs font sz & left margin for "What's New" */<br />
#p-\.C2\.A0.generated-sidebar.portlet ul {<br />
list-style-type: none;<br />
list-style-image: none;<br />
font-style: normal;<br />
font-size: 100%;<br />
margin: .75em 0 0 .75em;<br />
} <br />
<br />
/* hides Blank list item but preserves its space so sibling list el has more cushion */ <br />
#n-Blank {<br />
visibility:hidden;<br />
} <br />
<br />
/* in Vector, tweaks "What's New" element */<br />
#mw-panel div.portal div.body ul:first-child li:only-child {<br />
line-height: 2.5em;<br />
padding-bottom: 1em;<br />
}<br />
<br />
/* tweaks list containing "What's New" element in Monobook and Vector */<br />
#p-\.C2\.A0 ul {<br />
line-height: 1em;<br />
padding-bottom: 0em;<br />
}<br />
<br />
/* makes Vector left margin for "What's New" same as list items in lower sections */<br />
/* default for this was .5; needed to precisely specify the "first" and "persistent" */<br />
#mw-panel.noprint.collapsible-nav .portal.first.persistent div.body {<br />
margin-left: 1.25em; /* this gets overridden to .5 */<br />
} <br />
<br />
/* -- Vector centering proj (also see few commented tweaks above & in Vector.css) -- */<br />
div#center {<br />
margin: auto;<br />
max-width: 60em;<br />
}<br />
<br />
div#mw-head {<br />
right: auto;<br />
max-width: 60em;<br />
background-image: none;<br />
background-color: transparent;<br />
}<br />
<br />
div#p-logo {<br />
left: 0; /* was .5, not needed if centering vector (Vector.css overrides it) */ <br />
} /* see also mw-panel chg above */<br />
<br />
/* move top tab text up a bit to make white space above it less noticeable */<br />
div.vectorTabs ul li {<br />
line-height: .6em; <br />
}<br />
<br />
/* next 2 tweaks to snug right-nav els to content edge xcpt for 1px */<br />
div#p-personal {<br />
right: 1px;<br />
}<br />
<br />
div#p-search {<br />
margin-right: 1px;<br />
}<br />
<br />
div#mw-page-base {<br />
background-image: none;<br />
background-color: transparent;<br />
}<br />
<br />
/* ----------------------------------------------- */<br />
<br />
/* ****************************************************************************** */</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Template:SirTune_size_requirement_for_SIRTUNED&diff=104065Template:SirTune size requirement for SIRTUNED2017-08-08T21:49:29Z<p>Admin: Admin moved page SirTune size requirement for SIRTUNED to Template:SirTune size requirement for SIRTUNED without leaving a redirect: reduce number of SirTune pages</p>
<hr />
<div>It is recommended that you do not spend a lot of time trying to size<br />
[[SirTune data collection under MVS#sirtuned|SIRTUNED]], because the consequences of under- or over-estimating the SIRTUNED space requirements<br />
are relatively benign.<br />
However, if you do want to size SIRTUNED, this page provides some basic<br />
rules of thumb for estimating the correct size.<br />
<br />
==<b id="formula"></b>A formula for the estimate==<br />
<br />
The size of SIRTUNED is mainly determined by these factors:<br />
<ul><br />
<li>The number of lines of compilations saved.<br />
This is the number of lines in precompiled APSY procedures compiled in the run, or if the [[SirTune data collection statements#allcomp|ALLCOMP]] statement is specified for <var class="product">SirTune</var>, the number of lines of all compiled procedures.<br />
In any case, a line counts as 1 each time it is compiled. </li><br />
<br />
<li>The number of samples collected. </li><br />
<br />
<li>The average number of users for which data is collected per sample. </li><br />
</ul><br />
<br />
To estimate the number of lines of compilations saved when the ALLCOMP statement has not been specified, and when subsystems are not START'ed and STOP'ed multiple times in a run, simply total the number of lines in all precompiled procedures in START'ed subsystems.<br />
To get an estimate of this:<br />
<ol><br />
<li>Count the total number of precompiled procedures. </li><br />
<br />
<li>Estimate the average number of lines per precompiled<br />
procedure by entering the editor for a representative sample of them. </li><br />
<li>Multiply these two values. </li><br />
</ol><br />
Call the number of compiled lines <code>COMP_LINES</code>.<br />
<br />
To estimate the number of samples, divide the number of seconds over which data is to be collected, by the sample interval length (1 or whatever was specified on the [[SirTune data collection statements#INTerval num_sec|INTERVAL]] statement).<br />
Call this value <code>NUM_SAMP</code>.<br />
<br />
The best guide to estimating the number of users for which data is collected per sample is the <var class="product">Model&nbsp;204</var> performance monitor. There are certain worst-case<br />
values that one can assume, however:<br />
<ul><br />
<li>If only state RUNG is being collected, at most<br />
1 user will have data collected per sample, unless MP/204 is installed (in which case, the upper limit is 1 plus the number of subtasks). </li><br />
<br />
<li>If only REDY, RUNG, BLKIN, BLKIU, SWPGI, SWPGOW, SWPGOBN, and/or SWPGOBU states are being collected, the upper limit is the number of servers. </li><br />
<br />
<li>Otherwise, a crude upper limit is the number of users. </li><br />
</ul><br />
<br />
Call whatever value one comes up with <code>AVG_USERS</code>.<br />
<br />
The total number of bytes required for SIRTUNED can be estimated by this:<br />
<p class="code">100,000 + ( 12 * COMP_LINES ) + ( NUM_SAMP * 64 * ( 1 + AVG_USERS ) )<br />
</p><br />
This estimator provides a fairly generous estimate without being<br />
excessive. To determine the number of disk tracks required, divide<br />
the number of bytes produced by this estimator by the number of bytes<br />
per track at the block size for SIRTUNED (46,952 is the default bytes<br />
per track on a 3380, and 55,996 is the default on a 3390).<br />
<br />
==An example estimate==<br />
<p><br />
Suppose a shop has 100,000 lines of pre-compiled<br />
User Language code, expects to collect samples over 8 hours at 1 per<br />
second, is collecting data for states RUNG, REDY, and BLKIN, and has<br />
30 servers defined in the Online.<br />
These factors are clear:</p><br />
<p class="code">COMP_LINES = 100,000<br />
NUM_SAMP = 8 * 60 * 60 / 1 = 28,800<br />
</p><br />
<br />
Since all the users in a collected state must be in a server,<br />
use the number of servers as a gross estimator for AVG_USERS, that is:<br />
<p class="code">AVG_USERS = 30<br />
</p><br />
<br />
This means that the estimated space requirements in this case is:<br />
<p class="code">100,000 + ( 12 * 100,000 ) +<br />
28,800 * 64 * ( 1 + 30 ) = 58,439,200<br />
</p><br />
<br />
If the sample data was going to a 3380 with the <var class="product">SirTune</var> default block<br />
size, it would require 1245 tracks or 83 cylinders.<br />
<br />
The number of samples collected in this example is fairly extreme:<br />
generally there is not much benefit to collecting more than 10,000 samples.<br />
If sampling is limited to some key hours to restrict<br />
the number of samples collected to 10,000, the estimator becomes:<br />
<p class="code">100,000 + ( 12 * 100,000 ) +<br />
10,000 * 64 * ( 1 + 30 ) = 21,140,000<br />
</p><br />
<br />
If the sample data in this case was going to a 3380 with the <var class="product">SirTune</var> default<br />
block size, it would require 451 tracks or 31 cylinders.<br />
<br />
==See also==<br />
{{Template:SirTune topic list}}<br />
<br />
[[Category: SirTune]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=SirTune_data_collection_statements&diff=104062SirTune data collection statements2017-08-08T21:03:42Z<p>Admin: Admin moved page SirTune configuration statements to SirTune data collection statements without leaving a redirect: page name was ambiguous</p>
<hr />
<div>An optional DD card (or FILEDEF under CMS) called <code>SIRTUNEI</code> allows users to specify characteristics of the reporting run and to customize which reports are requested and how they are ordered.<br />
<br />
The configuration statements take the form of control cards.<br />
There can be only one <var class="product">SirTune</var> configuration statement<br />
per line, there are no line continuations, and a line beginning<br />
with an asterisk character (<tt>*</tt>) is treated as a comment and ignored.<br />
<br />
Available <var class="product">SirTune</var> data collection configuration statements are described in the subsections that follow.<br />
The minimum abbreviation allowed for each statement is indicated with<br />
uppercase characters, while optional characters are indicated with lowercase.<br />
Optional statement parameters are enclosed in brackets (<tt>[</tt><tt>]</tt>).<br />
Alternatives are separated with a vertical bar (<tt>|</tt>).<br />
<br />
==<b id="allcomp"></b>ALLComp==<br />
This statement specifies that <var class="product">SirTune</var> should collect compilation data for all procedures; it is the inverse of the <code>[[#precomp|PRECOMP]]</code> statement.<br />
<br />
The default for a single user run (<code>NUSERS=1</code>) is that <var class="product">SirTune</var> collects compilation data for all procedures.<br />
The default for a multi-user run (<code>NUSERS>1</code>)<br />
is that <var class="product">SirTune</var> collects compilation data only for precompiled procedures.<br />
It is unnecessary to specify <code>ALLCOMP</code> in a single-user run since it is the default.<br />
<br />
If ALLCOMP is not used explicitly in a multi-user run, or if it is overridden by the PRECOMP statement in a single-user run,<br />
the report generator can produce line-by-line breakdowns<br />
for precompiled [[Application Subsystem development|Application Subsystem]] (APSY) procedures only.<br />
Using the ALLCOMP statement makes it possible for the<br />
reporting module to provide line-by-line breakdowns for all<br />
User Language procedures executed in the job.<br />
<br />
Specifying the ALLCOMP statement can significantly increase the<br />
size of the sample data set, and in extreme cases, it can adversely<br />
affect the performance of an Online.<br />
Because of this, it is generally recommended that you use only the ALLCOMP option<br />
when running <var class="product">SirTune</var> against a single-user batch job, or when running<br />
multi-user jobs that do a lot of processing in non-APSY or<br />
non-precompiled procedures.<br />
<p class="note"><b>Note:</b> <var class="product">SirTune</var> cannot provide line-by-line breakdowns for SOUL programs not contained in procedures, including inline procedures in CCAIN, IODEV3, or BATCH2 input streams, or those entered at a terminal without use of the editor.<br />
</p><br />
<br />
==<b id="authorize"></b>AUTHorize userid1 [userid2] ...==<br />
This statement specifies the user IDs from whom <var class="product">SirTune</var> should accept<br />
<code>MODIFY</code> commands (under MVS) or <code>SMSG</code> commands (under CMS).<br />
The default is that MODIFY or SMSG commands to <var class="product">SirTune</var> are not accepted from any user ID.<br />
<br />
Since MVS provides no information about the user issuing a MODIFY<br />
statement, the only <code>AUTHORIZE</code> statement that makes any sense under MVS<br />
is:<br />
<p class="code"><nowiki>AUTHORIZE *<br />
</nowiki></p><br />
This indicates that <var class="product">SirTune</var> will accept MODIFY commands from any user that has the privilege to issue a MODIFY command (either an operator at a console or a user in SDSF).<br />
<br />
Under CMS, an arbitrary number of user IDs can be specified, and<br />
the IDs can contain wildcard characters.<br />
For example:<br />
<p class="code"><nowiki>AUTHORIZE BART HOMER*<br />
</nowiki></p><br />
The statement above indicates that <var class="product">SirTune</var> should accept SMSG commands from<br />
user ID <code>BART</code> and from any user ID that starts with the characters <code>H O M E R</code>.<br />
For more information on wildcards, see [[SirTune statement wildcards]].<br />
<br />
SIRTUNEI can contain an arbitrary number of AUTHORIZE statements.<br />
The AUTHORIZE statements are cumulative, so the user IDs specified<br />
on an AUTHORIZE statement are added to the list of user IDs specified<br />
by all previous AUTHORIZE statements.<br />
<br />
For more information on the commands that can be issued via MODIFY<br />
or SMSG by authorized users, see [[SirTune MODIFY and SMSG commands]].<br />
<br />
==CMSout vmid [ddname]==<br />
This statement has meaning only under CMS.<br />
It specifies the user ID of the virtual machine (<var class="term">vmid</var>) running the SIRTUNED load module, and<br />
it specifies the DD name (<var class="term">ddname</var>) that virtual machine is to<br />
use for the sample dataset.<br />
The default for <var class="term">vmid</var> is <code>SIRTUNED</code>, and the default<br />
for <var class="term">ddname</var> is the user ID of the virtual machine running <var class="product">SirTune</var>.<br />
<br />
For example, this statement<br />
indicates that there is a SIRTUNED service machine with user ID<br />
<code>HOHO</code> that should use DD name <code>MARGE</code> for the sample dataset:<br />
<p class="code">CMSOUT HOHO MARGE<br />
</p><br />
<br />
The <code>CMSOUT</code> statement makes it possible to run multiple SIRTUNED service machines, because it allows <var class="product">SirTune</var> in each <var class="product">Model 204</var> service machine to indicate the user ID of its SIRTUNED service machine. This is not a generally recommended mode of operation,<br />
however, because of the extra overhead of running multiple virtual machines.<br />
<br />
==<b id="colstat"></b>COLLect state [extra_data]==<br />
This statement makes it possible to increase the quantity of<br />
data collected by <var class="product">SirTune</var>.<br />
While collecting extra data<br />
increases the size of the sample data set, it also makes it<br />
possible to produce extended reports.<br />
<br />
The default for <code>COLLECT</code> in multi-user runs is <code>COLLECT RUNG</code>, which means that data is only collecting for running users (users consuming CPU), and no extra data is collected.<br />
The default for COLLECT in single-user runs is <code>COLLECT ALLN BLKU DISKIO</code>, which means that the only user for which data is not collected is waiting PSTs.<br />
Data is always collected for<br />
running users, regardless of the COLLECT statements in SIRTUNEI.<br />
<br />
<var class="term">state</var> is a list of one or more blank-delimited user states.<br />
<var class="product">SirTune</var> will collect sample data for a user<br />
in any of the states indicated by COLLECT statements at the<br />
moment a sample is collected.<br />
<br />
For example, if the following is specified, <var class="product">SirTune</var> will collect sample data for any user that is swapping into or out of a server at the instant a<br />
sample is collected:<br />
<p class="code">COLLECT SWPG<br />
</p><br />
<br />
To be able to produce a report for a particular state, data must<br />
be collected for that state with <var class="product">SirTune</var>.<br />
For example, if you want to produce a report for <code>STATE SWPG</code>, you can ensure<br />
the appropriate data will be collected by <var class="product">SirTune</var> by placing<br />
this statement in SIRTUNEI:<br />
<p class="code">COLLECT SWPG<br />
</p><br />
For a discussion of available states and their meanings, see [[SirTune user states]].<br />
<br />
In addition to requesting that sample data be collected for users<br />
in specific states, it is also possible to request extra data to<br />
isolate the cause of certain wait types.<br />
The only valid values for <var class="term">extra_data</var> are <code>DISKIO</code> and/or <code>CFR</code>.<br />
<br />
Specifying <code>DISKIO</code> as a parameter on a COLLECT statement<br />
indicates that <var class="product">SirTune</var> should collect data for every wait on <var class="product">Model 204</var> disk I/O.<br />
This data allows the reporting module to produce the DISKIO reports.<br />
These reports allow breakdowns<br />
of waits on <var class="product">Model&nbsp;204</var> disk I/O by file, table, and groups of pages within tables.<br />
<br />
Specifying <code>DISKIO</code> on a collect statement implies the <code>BLKIN</code> parameter.<br />
That is, this statement:<br />
<p class="code"><nowiki>COLLECT DISKIO BLKIN<br />
</nowiki></p><br />
is functionally equivalent to this:<br />
<p class="code"><nowiki>COLLECT DISKIO<br />
</nowiki></p><br />
<br />
Specifying <code>CFR</code> as a parameter on a COLLECT statement indicates that <var class="product">SirTune</var> should collect data for users with "Critical File Resource" activity.<br />
Critical file resources are used to provide concurrency control among<br />
updating and retrieving operations on the same file.<br />
Contention on critical file resources can exacerbate performance<br />
problems, sometimes dramatically.<br />
<br />
The CFR data allows the reporting module<br />
to produce the <code>CFRROOT</code>, <code>STATE CFRH<i>xxx</i></code>, and <code>STATE CFRB<i>xxx</i></code> reports.<br />
These reports allow breakdowns of:<br />
<ul><br />
<li>The root causes of critical file resource waits<br />
<li>Activities that result in the holding of critical file resources<br />
</ul><br />
<br />
Since critical file resources are used to provide multi-user concurrency control, the CFR parameter is meaningless in a single-user run.<br />
<br />
COLLECT statements are cumulative.<br />
That is, this sequence:<br />
<p class="code">COLLECT SWPGI<br />
COLLECT BLKIN<br />
COLLECT BLKON<br />
</p><br />
is functionally equivalent to this:<br />
<p class="code">COLLECT SWPGI BLKIN BLKON<br />
</p><br />
and it results in data being collected for all users in state SWPGI, BLKIN, or BLKON.<br />
There is no limit to the number of COLLECT statements in SIRTUNEI.<br />
<br />
The first COLLECT statement in SIRTUNEI for a single-user run is treated<br />
as an override to the single-user default.<br />
That is, if the following is the first COLLECT statement<br />
in SIRTUNEI for a single-user run:<br />
<p class="code">COLLECT RUNG<br />
</p><br />
it would turn off data collection for all other user states in the single-user default and for DISKIO data.<br />
<br />
==EXClude [start_time end_time] [days_of_week]==<br />
This statement makes it possible to limit the times<br />
in which sample data is collected.<br />
Note that compilation data is always collected, whether or not sample data is being collected.<br />
<br />
<var class="term">start_time</var> and <var class="term">end_time</var> can have the format<br />
HH, HH:MM, or HH:MM:SS, where HH represents an hour of the day, MM<br />
represents minutes, and SS represents seconds.<br />
The maximum allowable<br />
time is 24 or 24:00 or 24:00:00, which corresponds to midnight.<br />
<br />
For example, the following<br />
indicates that no sample data should be collected from midnight through<br />
8 AM every day of the week:<br />
<p class="code">EXCLUDE 0 8<br />
</p><br />
<br />
The following indicates that no sample data should be collected from 11:30 AM through 1:30 PM every day of the week:<br />
<p class="code">EXCLUDE 11:30 13:30<br />
</p><br />
<br />
The following indicates that no sample data should be collected from 30 seconds before 12 noon through 50 seconds after 1 PM every day of the week:<br />
<p class="code">EXCLUDE 11:59:30 13:00:50<br />
</p><br />
<br />
If <var class="term">start_time</var> is greater than <var class="term">end_time</var>, the times are assumed to wrap.<br />
For example, the following means that no sample data should be collected between 11 PM and 1 AM:<br />
<p class="code"><nowiki>EXCLUDE 23:00 1:00<br />
</nowiki></p><br />
<br />
<var class="term">days_of_week</var> is a blank-delimited list of days of the week.<br />
The following are valid days of the week, with the<br />
minimum abbreviations in uppercase:<br />
<ul><br />
<li>SUNday</li><br />
<li>MONday</li><br />
<li>TUEsday</li><br />
<li>WEDnesday</li><br />
<li>THUrsday</li><br />
<li>FRIday</li><br />
<li>SATurday</li><br />
</ul><br />
<br />
For example, the following indicates that no sample data should be collected all day Sundays and Saturdays:<br />
<p class="code">EXCLUDE SUNDAY SAT<br />
</p><br />
<br />
The following indicates that no sample data should be collected from 6:30 PM through midnight on Mondays through Fridays:<br />
<p class="code">EXCLUDE 18:30 24:00 MOND TUES WEDN THU FRIDAY<br />
</p><br />
<br />
In addition to the days of the week, the following groupings are<br />
also available in a <var class="term">days_of_week</var> list:<br />
<ul><br />
<li>WEEKDay = Monday, Tuesday, Wednesday, Thursday, Friday</li><br />
<li>WEEKEnd = Saturday, Sunday</li><br />
<li>ALL = Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday</li><br />
</ul><br />
<br />
For example, the following<br />
indicates that no sample data should be collected all day Saturday through<br />
Sunday:<br />
<p class="code">EXCLUDE WEEKE<br />
</p><br />
<br />
The following indicates that no sample data should be collected on any day of the week:<br />
<p class="code">EXCLUDE ALL<br />
</p><br />
<br />
The following indicates that no sample data should be collected between 10 AM and 12 noon on Sunday, Saturday, and Monday:<br />
<p class="code">EXCLUDE 10 12 WEEKEND MONDAY<br />
</p><br />
<br />
The following<br />
indicates that no sample data should be collected between 11 PM and midnight on all days of the week:<br />
<p class="code">EXCLUDE 23:00 24:00 ALL<br />
</p><br />
<br />
Note that the statement above is identical to this:<br />
<p class="code">EXCLUDE 23:00 24:00<br />
</p><br />
<br />
If no INCLUDE or EXCLUDE statements occur in SIRTUNEI, sample data is<br />
collected as if <code>INCLUDE ALL</code> had been specified.<br />
<br />
The order of INCLUDE and EXCLUDE statements in SIRTUNEI is important:<br />
If the first INCLUDE or EXCLUDE statement in SIRTUNEI is <code>EXCLUDE</code>, it is treated as if it<br />
were preceded by an <code>INCLUDE ALL</code>.<br />
That is, data will only not be collected over<br />
intervals explicitly indicated by EXCLUDE statements.<br />
<br />
For example,<br />
if this is the only INCLUDE or EXCLUDE statement in SIRTUNEI:<br />
<p class="code">EXCLUDE 0 9<br />
</p><br />
sample data will be collected between 9 AM and midnight every day of<br />
the week.<br />
No data will be collected at other times.<br />
If SIRTUNEI contains the following sequence,<br />
data should be collected on Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday:<br />
<p class="code">EXCLUDE WEEKEND<br />
INCLUDE SATURDAY<br />
</p><br />
<br />
If SIRTUNEI contains the following sequence,<br />
data should be collected on every weekday from 8 AM to 5 PM and on Fridays<br />
from 10 PM to midnight:<br />
<p class="code">EXCLUDE WEEKEND<br />
EXCLUDE 0 8<br />
EXCLUDE 17 24<br />
INCLUDE 22 24 FRIDAY<br />
</p><br />
<br />
Note that there is no harm in including a range<br />
that has already been excluded.<br />
For example, the following<br />
<p class="code">EXCLUDE 0:00 7:00<br />
EXCLUDE 4:00 10:00<br />
</p><br />
is the same as<br />
<p class="code">INCLUDE 0:00 10:00<br />
</p><br />
<br />
The INCLUDE/EXCLUDE statements are only honored if sampling is set<br />
to <code>AUTO</code> (automatic) mode, either by default or by a SAMPLE statement or a MODIFY or SMSG SAMPLE command.<br />
When sampling is in manual mode, INCLUDE/EXCLUDE statements have no effect.<br />
<br />
Generally, you should use the INCLUDE/EXCLUDE statements to avoid<br />
collecting data for time intervals in which there is nothing interesting<br />
likely to be happening, that is, periods of low activity.<br />
The only real cost of this is the disk space and the minor amount of CPU<br />
consumed collecting this sample data.<br />
<br />
If you are only interested in collecting data at peak hours, say<br />
10 AM to 11:30 AM and 1:30 PM to 4 PM on weekdays, simply put<br />
the following in SIRTUNEI:<br />
<p class="code">INCLUDE 10 5 WEEKDAY<br />
EXCLUDE 11:30 13:30<br />
</p><br />
<br />
==INClude [start_time end_time] [days_of_week]==<br />
This statement makes it possible to limit the times<br />
in which sample data is collected.<br />
Note that compilation data is<br />
always collected, whether or not sample data is being collected.<br />
<br />
<var class="term">start_time</var> and <var class="term">end_time</var> can have the format<br />
HH, HH:MM, or HH:MM:SS where HH represents an hour of the day, MM<br />
represents minutes, and SS represents seconds.<br />
<br />
The maximum allowable<br />
time is 24 or 24:00 or 24:00:00, which corresponds to midnight.<br />
For example, the following<br />
indicates that sample data should be collected from 8 AM through<br />
6 PM every day of the week:<br />
<p class="code">INCLUDE 8 18<br />
</p><br />
<br />
The following indicates that sample data should be collected from 8:30 AM<br />
through 5:30 PM every day of the week:<br />
<p class="code">INCLUDE 8:30 17:30<br />
</p><br />
<br />
The following<br />
indicates that sample data should be collected from 10 seconds<br />
before 9 AM through 10 seconds after 5 PM every day of the week:<br />
<p class="code">INCLUDE 8:59:50 17:00:10<br />
</p><br />
<br />
If <i>start_time</i> is greater than <i>end_time</i>,<br />
the times are assumed to wrap.<br />
For example, the following<br />
means that sample data should be collected between 11 PM and<br />
1 AM:<br />
<p class="code"><nowiki>INCLUDE 23:00 1:00<br />
</nowiki></p><br />
<br />
<i>days_of_week</i> is a blank-delimited list of days of the week.<br />
The following are valid days of the week, with the<br />
minimum abbreviations in uppercase:<br />
<ul><br />
<li>SUNday<br />
<li>MONday<br />
<li>TUEsday<br />
<li>WEDnesday<br />
<li>THUrsday<br />
<li>FRIday<br />
<li>SATurday<br />
</ul><br />
<br />
For example,<br />
indicates that sample data should be collected all day Mondays and Tuesdays:<br />
<p class="code">INCLUDE MONDAY TUE<br />
</p><br />
<br />
The following<br />
indicates that sample data should be collected from 8:45 AM through<br />
5:45 PM on Mondays through Fridays:<br />
<p class="code">INCLUDE 8:45 17:45 MOND TUES WEDN THU FRIDAY<br />
</p><br />
<br />
In addition to the days of the week, the following groupings are<br />
also available in a <var class="term">days_of_week</var> list:<br />
<ul><br />
<li>WEEKDay = Monday, Tuesday, Wednesday, Thursday, Friday </li><br />
<li>WEEKEnd = Saturday, Sunday </li><br />
<li>ALL = Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday </li><br />
</ul><br />
<br />
For example, the following<br />
indicates that sample data should be collected all day Monday through<br />
Friday:<br />
<p class="code">INCLUDE WEEKD<br />
</p><br />
<br />
The following<br />
indicates that sample data should be collected all day on every day of<br />
the week:<br />
<p class="code">INCLUDE ALL<br />
</p><br />
<br />
The following indicates that sample data should be collected between 10 AM and 12 noon on Sunday, Saturday, and Monday:<br />
<p class="code">INCLUDE 10 12 WEEKEND MONDAY<br />
</p><br />
<br />
The following<br />
indicates that sample data should be collected between 11 PM and midnight<br />
on all days of the week:<br />
<p class="code">INCLUDE 23:00 24:00 ALL<br />
</p><br />
<br />
Note that the above statement is identical to this:<br />
<p class="code">INCLUDE 23:00 24:00<br />
</p><br />
<br />
If no INCLUDE or EXCLUDE statements occur in SIRTUNEI, sample data is<br />
collected as if INCLUDE ALL had been specified.<br />
<br />
The order of INCLUDE and EXCLUDE statements in SIRTUNEI is important:<br />
If the first INCLUDE or EXCLUDE statement in SIRTUNEI is <code>INCLUDE</code>, it is treated as if it<br />
were preceded by an <code>EXCLUDE ALL</code> (that is, data will only be<br />
collected over intervals explicitly indicated by INCLUDE statements).<br />
<br />
For example,<br />
if this is the only INCLUDE or EXCLUDE statement in SIRTUNEI:<br />
<p class="code">INCLUDE 9 17<br />
</p><br />
sample data should be collected between 9 AM and 5 PM every day of<br />
the week.<br />
No data should be collected at other times.<br />
If SIRTUNEI contains the following sequence:<br />
<p class="code">INCLUDE WEEKDAY<br />
EXCLUDE TUESDAY THURSDAY<br />
</p><br />
Data should be collected on Monday, Wednesday, and Friday.<br />
If SIRTUNEI contains the following sequence:<br />
<p class="code">INCLUDE 8 17 TUESDAY<br />
EXCLUDE 11 14<br />
INCLUDE 12 13 TUESDAY<br />
</p><br />
Data should be collected on Tuesdays from 8 AM to 11 AM, 12 noon to 1 PM,<br />
and 2 PM to 5 PM.<br />
<blockquote class="note"><b>Note:</b> There is no harm in INCLUDE'ing a range that has already been included. For example, the following range<br />
<p class="code"><nowiki>INCLUDE 9:00 13:00<br />
INCLUDE 12:00 17:00<br />
</nowiki></p><br />
is the same as<br />
<p class="code"><nowiki>INCLUDE 9:00 17:00<br />
</nowiki></p><br />
</blockquote><br />
<br />
The INCLUDE/EXCLUDE statements are only honored if sampling is set<br />
to <code>AUTO</code> (automatic) mode, either by default, or by a SAMPLE statement or a MODIFY or SMSG SAMPLE command.<br />
When sampling is in manual mode,<br />
INCLUDE/EXCLUDE statements have no effect.<br />
<br />
Generally, you should use the INCLUDE/EXCLUDE statements to avoid<br />
collecting data for time intervals in which there is nothing interesting<br />
likely to be happening, that is, periods of low activity.<br />
The only real cost of collecting data in periods of low activity<br />
is wasted disk space and a minor amount of CPU<br />
consumed collecting the sample data.<br />
<br />
If you are only interested in collecting data at peak hours, say<br />
10 AM to 11:30 AM and 1:30 PM to 4 PM on weekdays, simply<br />
put the following statements into SIRTUNEI:<br />
<p class="code">INCLUDE 10 11:30 WEEKDAY<br />
INCLUDE 1:30 4 WEEKDAY<br />
</p><br />
<br />
==INTerval num_sec==<br />
This statement is used to set the sampling rate,<br />
thus making it possible to limit the amount of sample data collected.<br />
The default for <var class="term">num_sec</var> is 1, which<br />
means that sample data is collected at one-second intervals.<br />
<br />
The values specified for <i>num_sec</i> have a maximum<br />
resolution of 1/100 of a second so that:<br />
<p class="code">INTERVAL 3.1415929<br />
</p><br />
<br />
Is identical to:<br />
<p class="code">INTERVAL 3.14<br />
</p><br />
This also means that the lowest legal value for <var class="term">num_sec</var> is 0.01.<br />
<br />
The objective in setting the sampling interval should be to<br />
collect sufficient data to produce statistically significant<br />
results, without collecting unnecessarily huge amounts of data.<br />
Setting the sampling interval extremely low can also produce<br />
biased results.<br />
Generally, sampling intervals greater than 0.1<br />
seconds should avoid any biasing problems.<br />
<br />
A reasonable rule of thumb is that 10,000 samples are<br />
sufficient to produce accurate reports.<br />
Thus to collect data on a batch job that generally takes half an hour to<br />
complete, samples should be collected every 1800/10000 seconds.<br />
To accomplish this, place the following statement into SIRTUNEI:<br />
<p class="code"><nowiki>INTERVAL 0.18<br />
</nowiki></p><br />
<br />
If data is to be collected over 8 hours of a production<br />
ONLINE run, the default sampling interval of 1 second<br />
would result in 8*3600 or 28,800 samples being collected.<br />
In this case, it would not be unreasonable to place<br />
the following statement into SIRTUNEI to reduce the number of samples collected to 14,400:<br />
<p class="code">INTERVAL 2<br />
</p><br />
<br />
==MIXed==<br />
Status: This parameter is deprecated as of Version 7.2.<br />
If it is specified as an input parameter, it is ignored.<br />
<br />
This statement indicates that <var class="product">SirTune</var> should issue all messages in mixed-case.<br />
The default is to issue messages in mixed-case except on Japanese<br />
operating systems.<br />
On these systems, the default is to issue all messages in uppercase only.<br />
This option should be used on Japanese operating systems when<br />
mixed-case messages are desired.<br />
<br />
==NOSeq==<br />
This statement indicates that <var class="product">SirTune</var> should not consider characters in columns 73 through 80 of SIRTUNEI as part of<br />
its input.<br />
If SIRTUNEI has <code>RECFM=F</code> and <code>LRECL=80</code>, <var class="product">SirTune</var> ordinarily assumes that characters in columns 73 through 80 are<br />
sequence numbers, and therefore it ignores them.<br />
If SIRTUNEI has any<br />
other format, <var class="product">SirTune</var> considers all characters in the input record<br />
as part of the <var class="product">SirTune</var> statements.<br />
<br />
==PGM pgm_name==<br />
Effective in version 1.5 of <var class="product">SirTune</var> and lower, <i>this statement is ignored in versions after 1.5</i>.<br />
<br />
The PGM statement makes it possible to specify the name<br />
of the <var class="product">Model 204</var> ONLINE load module to be loaded by the SIRTUNE module.<br />
The default for <var class="term">pgm_name</var> is <code>ONLINE</code><br />
under MVS, and it is <code>M204ONLN</code> under CMS.<br />
<br />
Thus, if SIRTUNE is to collect data for a job that should be<br />
run with BATCH204, put the following statement into SIRTUNEI:<br />
<!-- get non-BATCH204 example --><br />
<p class="code"><nowiki>PGM BATCH204<br />
</nowiki></p><br />
<br />
If the name of the load module for which SIRTUNE is to collect data is <code>ONLINE22</code>, put the following statement into SIRTUNEI:<br />
<p class="code">PGM ONLINE22<br />
</p><br />
<br />
==<b id="precomp"></b>PREComp==<br />
This statement specifies that <var class="product">SirTune</var> should only collect compilation data for precompiled APSY procedures;<br />
it is the inverse of the <code>[[#allcomp|ALLComp]]</code> statement.<br />
<br />
The default for a single-user run (<code>NUSERS=1</code>) is that <var class="product">SirTune</var> collects<br />
compilation data for all procedures.<br />
The default for a multi-user run (<code>NUSERS>1</code>)<br />
is that <var class="product">SirTune</var> collects compilation data only for precompiled procedures.<br />
It is unnecessary to specify <code>PRECOMP</code> in a multi-user run, since it is the default.<br />
<br />
When PRECOMP is in effect, either because of an explicit PRECOMP statement<br />
or as the result of multi-user run defaults, the reporting module<br />
can produce line-by-line breakdowns for precompiled APSY procedures only.<br />
<br />
==SAMPle ON | OFF | AUTO==<br />
This statement places <var class="product">SirTune</var> in manual sampling mode.<br />
In this mode, <var class="product">SirTune</var> ignores INCLUDE and EXCLUDE statements until a <code>SAMPLE AUTO</code> command is issued via a MODIFY or SMSG command issued by an authorized user.<br />
The default for this statement is <code>SAMPLE AUTO</code>, which places<br />
<var class="product">SirTune</var> under the control of INCLUDE and EXCLUDE statements.<br />
<br />
For example, to have <var class="product">SirTune</var> come up so that no sample data<br />
is collected until a user issues a (MODIFY or SMSG) SAMPLE command to<br />
turn sampling off or to put sampling in AUTO mode, simply<br />
place the following statement into SIRTUNEI:<br />
<p class="code">SAMPLE OFF<br />
</p><br />
<br />
To have <var class="product">SirTune</var> come up so that sample data<br />
is collected until a user issues a MODIFY or SMSG SAMPLE command,<br />
place the following statement into SIRTUNEI:<br />
<p class="code">SAMPLE ON<br />
</p><br />
<p class="note"><b>Note:</b> If <code>SAMPLE OFF</code> is specified in SIRTUNEI and there are no<br />
AUTHORIZE statements in SIRTUNEI, it will be impossible to<br />
collect any sample data for the course of the run, because no<br />
user will have the authority to issue the MODIFY or SMSG SAMPLE<br />
command to set sampling to <code>ON</code> or to <code>AUTO</code>.<br />
</p><br />
<br />
==UPper==<br />
This statement indicates that <var class="product">SirTune</var> should issue all messages in uppercase only.<br />
The default is to issue messages in mixed-case, except on Japanese<br />
operating systems. On these systems the default is to issue all messages in uppercase only.<br />
<br />
This option should be used on systems where mixed-case messages<br />
might not be displayed correctly on terminals or printers.<br />
<br />
==See also==<br />
{{Template:SirTune topic list}}<br />
<br />
[[Category: SirTune]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=SECURE_command:_File&diff=103944SECURE command: File2017-07-25T23:10:06Z<p>Admin: Admin moved page SECURE FILE command to SECURE command: File without leaving a redirect: no keyword "FILE"</p>
<hr />
<div>==Summary==<br />
<dl><br />
<dt>Privileges<br />
<dd>File manager<br />
<dt>Function<br />
<dd>Secures the currently open <var class="product">Model&nbsp;204</var> file<br />
</dl><br />
==Syntax==<br />
<p class="syntax">SECURE<br />
</p><br />
===Syntax notes===<br />
SECURE must be issued in file context, that is, the current default must be a file, not a group.<br />
==Usage notes==<br />
<p>The SECURE command secures the <var class="product">Model&nbsp;204</var> file that is currently open. A special field in the password table serves as the key for securing files. SECURE processing copies this key into the open file. Then the secured file is opened and the password table key is compared with the file's copy. The file is accessible only if the two keys match.</p><br />
<p>The LOGKEY command can be used by the system manager to change the password table from its initial setting. </p><br />
<p>When it processes SECURE, <var class="product">Model&nbsp;204</var> ends any current User Language update unit and begins a non-backoutable update unit. If a <var class="product">Model&nbsp;204</var> command is processing an update unit that cannot be backed out, the SECURE command is included in that update unit. For more information about <var class="product">Model&nbsp;204</var> update units, see [[File integrity and recovery#Update units and transactions|Update units and transactions]].</p><br />
<p>To use the SECURE command you must have update authority to the selected file. If the file is open for read-only access, the SECURE command is rejected with the following message: </p><br />
<p class="code">M204.1036: UPDATES NOT PERMITTED.<br />
</p><br />
[[Category: File manager commands]]<br />
[[Category:Commands]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=SYSOPT_parameter&diff=103943SYSOPT parameter2017-07-25T23:08:56Z<p>Admin: /* Commands restricted by option 4 */ link repair</p>
<hr />
<div>{{Template:SYSOPT parameter subtitle}}<br />
<br />
==Summary==<br />
<dl><br />
<dt>Default value<br />
<dd>128 (X'80')<br />
<dt>Parameter type<br />
<dd>System<br />
<dt>Where set<br />
<dd><br />
<ul><br />
<li>In z/OS, the <var>SYSOPT</var> parameter must always be set via the PARM field in the EXEC card (see [[Defining the runtime environment (CCAIN)#Specifying EXEC statement parameters|Specifying EXEC statement parameters]]), using the parameters passed by the operating system when <var class="product">Model&nbsp;204</var> is invoked.</li><br />
<br />
<li>In z/VM, the <var>SYSOPT</var> parameter is stacked in the EXEC that issues all the FILEDEFs.</li><br />
<br />
<li>In z/VSE, the <var>SYSOPT</var> parameter is passed in the UPSI statement.</li><br />
</ul><br />
<dt>Related products<br />
<dd>All<br />
<dt>Introduced<br />
<dd><var class="product">Model 204 V6.1</var> or earlier<br />
</dl><br />
<br />
==Description==<br />
<p><br />
Specifies the system options.</p><br />
<p><br />
Valid settings of <var>SYSOPT</var> are (options can be summed):</p><br />
<table><br />
<tr class="head"><th>Hex setting</th><th>Decimal setting</th><th>Meaning</th></tr><br />
<br />
<tr><th align="right"><var>X'80' </var></th><td>128 </td><td>Write to audit trail and/or journal.</td></tr><br />
<br />
<tr><th align="right"><var>X'40'</var></th><td> 64 </td><td>Force an ABEND without a dump at termination when the return code is not zero.</td></tr><br />
<br />
<tr><th align="right"><var>X'20' </var></th><td> 32 </td><td>Include RK lines in the audit trail and/or the journal.</td></tr><br />
<br />
<tr><th align="right"><var>X'10' </var></th><td> 16</td><td>Require login.</td></tr><br />
<br />
<tr><th align="right"><var>X'08' </var></th><td> 8 </td><td>Perform <var>DISCONNECT</var> during logout (not effective for terminals connected to <var class="product">Model&nbsp;204</var> through CRAM).</td></tr><br />
<br />
<tr><th align="right"><var>X'04'</var></th><td> 4</td><td>Execute <var class="product">Model&nbsp;204</var> data definition commands within a particular run of <var class="product">Model&nbsp;204</var> only through the File Management facility of Dictionary.</td></tr><br />
<br />
<tr><th align="right"><var>X'02' </var></th><td> 2 </td><td>Open CCAGRP for use of permanent file groups.</td></tr><br />
<br />
<tr><th align="right"><var>X'01' </var></th><td> 1 </td><td>Open CCASYS during initialization </td></tr><br />
</table><br />
<p><br />
<var>SYSOPT</var> cannot be reset by the system manager. </p><br />
<br />
===Commands restricted by option 4===<br />
Setting the <var>SYSOPT</var> option 4 bit restricts the use of <var class="product">Model&nbsp;204</var> data definition commands within a particular <var class="product">Model&nbsp;204</var> run. When the <var>SYSOPT</var> value includes option 4, the following commands can be executed only through the File Management facility of Dictionary/204:<br />
<br />
:<var>[[CREATE command: File|CREATE FILE]]</var>, <var>[[SECURE command: File|SECURE]]</var>, <var>[[DESECURE command: File|DESECURE]]</var><br />
:<var>[[INITIALIZE command|INITIALIZE]]</var><br />
:<var>[[DEFINE FIELD command|DEFINE FIELD]]</var>, <var>[[REDEFINE command|REDEFINE FIELD]]</var>, <var>[[RENAME FIELD command|RENAME FIELD]]</var>, <var>[[DELETE command: Field|DELETE FIELD]]</var><br />
:<var>[[INCREASE command|INCREASE]]</var>, <var>[[DECREASE command|DECREASE]]</var><br />
:<var>[[RESET command|RESET]]</var><br />
<br />
===Parameters restricted by option 4===<br />
<p><br />
As a result of restricting the <var>RESET</var> command, <var>SYSOPT</var> 4 prevents the resetting of all resettable file parameters except <var>FISTAT</var>. The following parameters are restricted:</p><br />
<br />
:<var>[[ADDLVL parameter|ADDLVL]]</var>, <var>[[READLVL parameter|READLVL]]</var>, <var>[[SELLVL parameter|SELLVL]]</var>, <var>[[UPDTLVL parameter|UPDTLVL]]</var><br />
:<var>[[BRESERVE parameter|BRESERVE]]</var>, <var>[[DRESERVE parameter|DRESERVE]]</var><br />
:<var>[[FOPT parameter|FOPT]]</var>, <var>[[FRCVOPT parameter|FRCVOPT]]</var><br />
:<var>[[OPENCTL parameter|OPENCTL]]</var><br />
:<var>[[PRCLDEF parameter|PRCLDEF]]</var><br />
:<var>[[PRIVDEF parameter|PRIVDEF]]</var><br />
:<var>[[VERIFY parameter|VERIFY]]</var><br />
<br />
[[Category:System parameters]]<br />
[[Category:Parameters]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=SirSafe_command_and_function_reference&diff=103942SirSafe command and function reference2017-07-25T23:08:02Z<p>Admin: link repair</p>
<hr />
<div><var class="product">SirSafe</var> is controlled by enhancements to the <var>AUTHCTL</var> command, and it provides its services through extensions to other <var class="product">Model&nbsp;204</var> commands, including <var>LOGCTL</var>, <var>LOGFILE</var>, <var>LOGGRP</var>, and <var>SECURE</var>. <var class="product">SirSafe</var> also offers subsystem maintenance commands and a $function that provides an interface to an external authorizer. <br />
<br />
All of these controls are described on this page.<br />
<br />
==AUTHCTL==<br />
The <var>AUTHCTL</var> command is used to activate <var class="product">SirSafe</var> for a <var class="product">Model&nbsp;204</var> password table and to control various aspects of its function.<br />
The basic <var>AUTHCTL</var> command is described in the Model&nbsp;204<br />
[[Security interfaces overview|Security interfaces]] pages.<br />
This section describes only additions and extensions specific to <var class="product">SirSafe</var>.<br />
<br />
===<b id="autha"></b>AUTHCTL A SIRSAFE===<br />
The <code>AUTHCTL A SIRSAFE</code> command is used both to<br />
activate <var class="product">SirSafe</var> for a <var class="product">Model&nbsp;204</var> password table and to specify the<br />
security environments that are allowed to access the password table.<br />
This is accomplished by adding a <var class="product">SirSafe</var> security entry that is processed during <var class="product">Model&nbsp;204</var> initialization.<br />
<br />
====Syntax====<br />
<p class="syntax">AUTHCTL A SIRSAFE { OPTIONAL | REQUIRED } [ MVSRW | MVSRO ] -<br />
<span class="term">interface</span>=<span class="term">mask</span> [<span class="term">interface</span>=<span class="term">mask</span>] ... </p><br />
<br />
====Syntax terms====<br />
<table><br />
<tr><th><var>OPTIONAL</var></th><br />
<td>Indicates that the current <var class="product">Model&nbsp;204</var> password table will be accessible to any <var class="product">Model&nbsp;204</var> Online, including those without <var class="product">SirSafe</var> support.<br />
However, no visible file or group entries may be added to a password table when <var class="product">SirSafe</var> support is optional.<br />
<p class="note"><b>Note:</b> If a <var class="product">SirSafe</var>-enabled <var class="product">Model&nbsp;204</var> instance opens a password table that has been set as<br />
optional, <var class="product">SirSafe</var> will activate only if the current security environment satisfies the conditions described by the <var class="product">SirSafe</var> security entry. </p></td></tr><br />
<br />
<tr><th><var>REQUIRED</var></th><br />
<td>Indicates that the current <var class="product">Model&nbsp;204</var> password table will only be accessible to a <var class="product">Model&nbsp;204</var> online that has:<br />
<ul><br />
<li><var class="product">SirSafe</var> support<br />
<li>A current security environment that matches one of those specified in the special <var class="product">SirSafe</var> entry </ul> <p></p> This condition enables support for visible file and group entries.</td></tr><br />
<br />
<tr><th><var>MVSRW</var></th><br />
<td>Indicates that <var class="product">Model&nbsp;204</var> will try to open all files in read/write mode and update their FPL pages, even if the file is being opened for read/only access.<br />
If a file cannot be opened in read/write mode, it will not be opened. This is the standard <var class="product">Model&nbsp;204</var> behavior, and it is the default.</td></tr><br />
<br />
<tr><th><var>MVSRO</var></th><br />
<td>Indicates that if <var class="product">Model&nbsp;204</var> is not allowed to open a file in read/write mode, it will try to open it in read/only mode and so not update theFPL page of the file.<br />
Whether or not <var class="product">Model&nbsp;204</var> is allowed to open afile in read/write mode depends, of course, on the security profile of the user under which the<var class="product">Model&nbsp;204</var> job is running.</td></tr><br />
<br />
<tr><th>interface</th><br />
<td>The name of a <var class="product">Model&nbsp;204</var> external security interface: <var>RACF</var>, <var>ACF2</var>, or <var>TOPSECRET</var>.</td></tr><br />
<br />
<tr><th>mask</th><br />
<td>A character string that identifies an acceptable environment for the corresponding security interface, as described further, below. You can use a trailing asterisk (<tt>*</tt>) to identify a range of possible environments.</td></tr><br />
</table><br />
<br />
====Usage notes====<br />
Multiple <i>interface=mask</i> pairs may be specified.<br />
During initialization, a <var class="product">SirSafe</var>-enabled <var class="product">Model&nbsp;204</var> scans the password<br />
table for a <var class="product">SirSafe</var> security entry.<br />
If one is found, its list of <i>interface=mask</i> pairs is checked.<br />
If an entry matching the current security environment is found,<br />
<var class="product">Model&nbsp;204</var> enters the <var class="product">SirSafe</var>-active state.<br />
Otherwise an M204.0340 or M204.0341 error message is produced.<br />
<br />
The interpretation of <i>interface</i> and <i>mask</i><br />
combinations depends upon the particular interface:<br />
<ul><br />
<li>For RACF, the <i>mask</i> value applies to the field identified<br />
as the "RACF CONTROL GROUP NAME" on an <var>AUTHCTL VIEW</var><br />
command (see the example in [[#auctlvw|AUTHCTL VIEW]]). </li><br />
<br />
<li>For ACF2, the <i>mask</i> value applies to the field identified as the<br />
"ACF2 RESOURCE TYPE" on an <var>AUTHCTL VIEW</var> command,<br />
prefixed with the letter <code>R</code>. </li><br />
<br />
<li>For TOPSECRET, the <i>mask</i> value applies to the field identified as the<br />
"ACID" on an <var>AUTHCTL VIEW</var> command. </li><br />
</ul><br />
<br />
Thus, the following command allows visible file and group passwords to be stored and requires that <var class="product">Model&nbsp;204</var> be <var class="product">SirSafe</var>-enabled when it tries to use<br />
the password table:<br />
<p class="code">AUTHCTL A SIRSAFE REQUIRED RACF=M204* -<br />
ACF2=R204 TOPSECRET=*<br />
</p><br />
<br />
If RACF was being used, the RACF control group could be any<br />
name starting with <code>M204</code>, which would include the default <var>M204RACF</var>.<br />
If ACF2 was being used, the ACF2 resource type would need to be <code>204</code>, which is the default.<br />
And any CA-Top Secret environment would be allowed.<br />
<br />
===<b id="authc"></b>AUTHCTL C SIRSAFE===<br />
The <var>AUTHCTL C SIRSAFE</var> command is used to<br />
change the <var class="product">SirSafe</var> security entry for a <var class="product">Model&nbsp;204</var> password table.<br />
It accepts the same parameters as the <var>AUTHCTL A SIRSAFE</var> command.<br />
It is especially useful for updating the security masks for a<br />
password table that contains visible file or group entries.<br />
<br />
The <var>AUTHCTL C SIRSAFE</var> command may not be<br />
used to switch a password table to the <var class="product">SirSafe</var>-optional state<br />
if the table contains any visible file or group entries.<br />
An MSIR.0542 error message is produced, and the command is ignored.<br />
<br />
===<b id="authd"></b>AUTHCTL D SIRSAFE===<br />
The <var>AUTHCTL D SIRSAFE</var> command is used to<br />
delete the <var class="product">SirSafe</var> security entry from a <var class="product">Model&nbsp;204</var> password table, deactivating <var class="product">SirSafe</var>.<br />
<br />
Any visible file and group entries must be deleted before <var class="product">SirSafe</var> can be deactivated.<br />
If the current <var class="product">SirSafe</var> security entry includes the <var>REQUIRED</var><br />
attribute, and visible file or group password entries have been<br />
added to the password table, an <code>AUTHCTL D</code> request will be rejected<br />
with an MSIR.0542 error message.<br />
<br />
===<b id="authlst"></b>AUTHCTL LIST SIRSAFE===<br />
The <var>AUTHCTL LIST SIRSAFE</var> command is used to<br />
list the <var class="product">SirSafe</var> security entry, if any in the current <var class="product">Model&nbsp;204</var> password table.<br />
The output from this command is the <var>AUTHCTL A SIRSAFE</var><br />
command that could be used to recreate the <var class="product">SirSafe</var> security entry.<br />
For example:<br />
<p class="code"><b>AUTHCTL LIST SIRSAFE</b><br />
AUTHCTL A SIRSAFE REQUIRED MVSRO RACF=M204*<br />
</p><br />
<br />
===<b id="auctref"></b>AUTHCTL REFRESH===<br />
The <var>AUTHCTL REFRESH</var> command causes <var class="product">Model&nbsp;204</var> to manually rebuild<br />
its list of systems for which enhanced shared DASD enqueueing is active, including whether the systems are visible or have become invisible.<br />
This list is displayed by the <var>AUTHCTL VIEW</var> command, as described in<br />
[[SirSafe enhanced shared DASD enqueueing#condasd|Controlling shared DASD enqueueing]].<br />
<br />
====Syntax====<br />
<p class="syntax">AUTHCTL REFRESH [CLEAR]<br />
</p><br />
The <var>CLEAR</var> option directs <var class="product">Model&nbsp;204</var> to remove from its list any systems that were once visible, but are now invisible.<br />
<br />
====Usage notes====<br />
If a <var class="product">Model&nbsp;204</var> instance is started without a copy of <var class="product">SIRENQ</var> running, an <var>AUTHCTL REFRESH</var><br />
command is required to enable enhanced shared DASD enqueueing.<br />
<br />
===<b id="authtst"></b>AUTHCTL TEST===<br />
The <var>AUTHCTL TEST</var> command is used to activate or<br />
deactivate the logging of <var class="product">SirSafe</var> debugging and diagnostic information.<br />
When the <var>AUTHCTL TEST</var> facility is active, informative messages are produced that<br />
track the various calls SirSafe makes to the current security interface.<br />
The <var class="product">[[SirScan]]</var> product may be used to examine the messages, or they may be retrieved with the <var class="product">Model&nbsp;204</var> <var>[[VIEW command#VIEW ERRORS|VIEW ERRORS]]</var> command.<br />
<br />
<p class="note"><b>Note:</b> If using <var>VIEW ERRORS</var>, remember that the most recent messages are listed first. </p><br />
<br />
====Syntax====<br />
<p class="syntax">AUTHCTL TEST { ON | OFF } </p><br />
<br />
====Usage notes====<br />
<ul><br />
<li><code>AUTHCTL TEST ON</code> produces six informational messages to the journal and <var class="product">Model&nbsp;204</var> operator.<br />
If the <var>MVSRO</var> feature is active, two messages are used to track the tests<br />
performed to determine access to <var class="product">Model&nbsp;204</var> database file data sets, as shown in [[SirSafe support for read-only files under MVS#Monitoring and debugging|Monitoring and debugging]].<br />
The remaining four messages are for debugging access to file and group passwords. </li><br />
<br />
<li>If no security environment is active, <var class="product">SirSafe</var> produces an <code>MSIR.0552</code><br />
message, and access to file and group passwords is disallowed.<br />
Otherwise, an <code>MSIR.0553</code> message is produced for each file or group<br />
password table entry that matches a password provided by a user, indicating<br />
that SirSafe is testing the current end user's access.<br />
If the external security interface disallows the requested access,<br />
an <code>MSIR.0554</code> message is produced.<br />
If the requested access is allowed by the external security interface,<br />
an <code>MSIR.0557</code> message is produced. </li><br />
<br />
<li>The <code>MSIR.0553</code> message identifies the user attempting the access, the<br />
"dataset" name associated with the access, and the type of access required (read or write).<br />
The user ID is identified in two ways: the <var class="product">Model&nbsp;204</var> "internal ID," that is,<br />
the ID that appears in messages on the journal, and the external security<br />
interface view &mdash; including the user ID and group ID.<br />
The <code>MSIR.0553</code> message is the only source of the external authorizer information, which is important for several reasons:<br />
<ul><br />
<li>The access checks are performed using the external ID and group. </li><br />
<br />
<li>The access rights are frequently conferred from group, as opposed to the ID. </li><br />
<br />
<li>When <var class="product">Model&nbsp;204</var> processes a login with an ID from CCASTAT, the external<br />
user ID and group are defined by the <var class="product">Model&nbsp;204</var> external security interface. </li><br />
</ul> </li><br />
</ul><br />
<br />
====Example====<br />
In the following example, user <code>GARY</code> logs in with a CCASTAT ID,<br />
then opens the semi-public file <code>PROCFILE</code> with the password <code>WRITE</code>.<br />
The user does not get the expected access privileges, in fact the user gets the<br />
default privileges for the file:<br />
<p class="code"><b>O PROCFILE</b><br />
<nowiki>*** M204.0347: PASSWORD<br />
*** M204.0620: FILE PROCFILE OPENED -- NO UPDATES ALLOWED </nowiki><br />
<b>VIEW ERRORS</b><br />
MSIR.0554: SirSafe disallowed password access<br />
MSIR.0553: GARY (M204USR,M204GRP) read to<br />
M204RACF.FILE.PROCFILE.INDEXA tried by<br />
MSIR.0598: SirSafe: R/W access allowed<br />
MSIR.0597: SirSafe: (GARY,SYS1) checking R/W to M204.GARY.PROCFILE on MVS204<br />
<b>V CURPRIV,PRIVDEF</b><br />
CURPRIV X'0761' PRIVS FOR CURRENT FILE/GROUP<br />
PRIVDEF X'0761' DEFAULT FILE PRIVILEGES<br />
</p><br />
<var class="product">SirSafe</var> first performed MVS read-only access checking, using the profile for<br />
the <var class="product">Model&nbsp;204</var> <b><i>job</i></b> (user ID <code>GARY</code>, group <code>SYS1</code>),<br />
and read/write access was allowed, so the file was not opened in read-only mode.<br />
Then the password was matched to the CCASTAT entry for <code>PROCFILE</code> with<br />
index character <code>A</code>, and access to that entry was denied.<br />
Since this was the only password matched (only one MSIR.0553 message), the user was<br />
given the default privileges for the file.<br />
<br />
<p class="note"><b>Note:</b> Although the Model&nbsp;204 internal user ID was <code>GARY</code>, the external profile<br />
being used was user <code>M204USR</code>, group <code>M204GRP</code>.<br />
This occurred because CCASTAT contained an entry for the ID <code>GARY</code>,<br />
a common source of confusion.<br />
</p><br />
<br />
===<b id="auctlvw"></b>AUTHCTL VIEW===<br />
The <var>AUTHCTL&nbsp;VIEW</var> command displays the status of<br />
the current <var class="product">Model&nbsp;204</var> external security interface, if any.<br />
If an interface is active, the command displays its type and current execution parameters.<br />
If SirSafe is installed, the <var>AUTHCTL&nbsp;VIEW</var> command also displays<br />
the status of <var class="product">SirSafe</var>, as the following example shows:<br />
<p class="code"><b>AUTHCTL VIEW</b><br />
<br />
RACF INTERFACE OPTIONS<br />
GROUP M204RACF RACF CONTROL GROUP NAME<br />
COMGROUP M204RAC1 RACF COMMON CONTROL GROUP NAME<br />
PRIORITY STANDARD PRIORITY DEFAULT<br />
M204GRP DEFAULT USER GROUP<br />
M204USR DEFAULT USERID<br />
DLMCHECK USE $JOB DLM CHECKING OPTION<br />
<br />
<nowiki>*** MSIR.0551: SirSafe is active and required for current CCASTAT<br />
*** MSIR.0599: SirSafe read-only file checking is active<br />
*** MSIR.0687: SirSafe enhanced shared DASD not active, run SirEnq on ZOS4 (P390)<br />
</nowiki></p><br />
<br />
For information about using <var>AUTHCTL VIEW</var><br />
for monitoring enhanced shared DASD enqueueing, see [[SirSafe enhanced shared DASD enqueueing#condasd|Controlling shared DASD enqueueing]].<br />
<br />
==<b id="logctl enhancements"></b>LOGCTL enhancements for visible file/group entries==<br />
<var class="product">SirSafe</var> provides support for <i>visible</i> file and<br />
group passwords when it is operated in the <var>REQUIRED</var> mode.<br />
Visible file and group entries are easier to administer because<br />
all of the data is visible while it is being entered, and<br />
because the password value is displayed by a <var>LOGFILE</var><br />
or <var>LOGGRP</var> command.<br />
<br />
<var>LOGCTL</var> recognizes standard file entries because the file name is<br />
prefixed by a colon (<tt>:</tt>), and group entries because the name is<br />
prefixed by a comma (<tt>,</tt>).<br />
<var class="product">SirSafe</var> extends the <var>LOGCTL&nbsp;A</var>, <var>LOGCTL&nbsp;C</var>, and <var>LOGCTL&nbsp;D</var> commands to support visible file and group entries.<br />
Visible file entries are indicated by prefixing the file name with a greater-than sign (<tt>></tt>).<br />
Visible group entries are indicated by prefixing the group name with a plus sign (<tt>+</tt>).<br />
<br />
Whenever a <var>LOGCTL&nbsp;A</var> or <var>LOGCTL&nbsp;C</var> command is issued for a<br />
visible file or group entry, the subsequent line of input is not masked, remaining visible on the System Manager's screen.<br />
The following example illustrates how to add a visible file password entry:<br />
<p class="code"><b>logctl a >procfile a</b><br />
M204.0374: ENTER FILE/GROUP PASSWORD,PRIVILEGES,CLASS,SELECT,READ,UPDATE,ADD<br />
<b>theman,X'bfff'</b><br />
M204.0379: ENTER TERMINAL LIST, ALL, NONE, ADD, DEL, OR RETURN<br />
<br />
<nowiki>>PROCFILE A THEMAN X'BFFF' 0, 0, 0, 0, 0, ALL<br />
M204.0376: PARAMETERS ACCEPTED<br />
M204.0345: CCASTAT UPDATED<br />
</nowiki></p><br />
Note that the password and privileges are visible while typing, and they are echoed to the screen.<br />
Also, when the completed entry is listed, the password is displayed.<br />
Contrast this to the case for adding a conventional file password:<br />
<p class="code"><b>logctl a :procfile b</b><br />
M204.0374: ENTER FILE/GROUP PASSWORD,PRIVILEGES,CLASS,SELECT,READ,UPDATE,ADD<br />
M204.0379: ENTER TERMINAL LIST, ALL, NONE, ADD, DEL, OR RETURN<br />
<br />
<nowiki>:PROCFILE B ******** X'00FF' 0, 0, 0, 0, 0, ALL<br />
M204.0376: PARAMETERS ACCEPTED<br />
M204.0345: CCASTAT UPDATED<br />
</nowiki></p><br />
In the conventional case, the password and privilege line does not<br />
echo while typing, and the password is not displayed when the entry is<br />
listed.<br />
<br />
==<b id="logctlr"></b> LOGCTL R==<br />
The <var>LOGCTL&nbsp;R</var> command is a <var class="product">SirSafe</var> implemented subcommand for the <var>LOGCTL</var> command.<br />
<var>LOGCTL&nbsp;R</var> is used to <b>R</b>eplicate (copy) a file or group entry in the password table.<br />
<br />
====Syntax====<br />
<p class="syntax">LOGCTL R {:<span class="term">filename</span> | ><span class="term">filename</span> | ,<span class="term">grpname</span> | +<span class="term">grpname</span>} [<span class="term">indx</span>]<br />
</p><br />
<br />
Where:<br />
<table><br />
<tr><th><var>:</var>filename</th><br />
<td>Indicates a classic, invisible password entry for the named file.</td></tr><br />
<br />
<tr><th>>filename</th><br />
<td>Indicates a visible password entry for the named file.</td></tr><br />
<br />
<tr><th><var>,</var>grpname</th><br />
<td>Indicates a classic, invisible password entry for the named group.</td></tr><br />
<br />
<tr><th><var>+</var>grpname</th><br />
<td>Indicates a visible password entry for the named group.</td></tr><br />
<br />
<tr><th>indx</th><br />
<td>A single index character used to distinguish between multiple entries for a file or group; it defaults to a single space.</td></tr><br />
</table><br />
<br />
====Usage notes====<br />
<ul><br />
<li>If the identified entry is found in the <var class="product">Model&nbsp;204</var> password table,<br />
the user is prompted for an index character that will identify a new copy of the entry.<br />
<p class="note"><b>Note:</b> The sequence of a <code>LOGCTL&nbsp;R</code> followed by<br />
a <code>LOGCTL&nbsp;D</code> may be used to move a file or group<br />
entry in the <var class="product">Model&nbsp;204</var> password table.<br />
</p> </li><br />
<br />
<li>For a simple example of <var>LOGCTL R</var>, see [[SirSafe control of access to passwords#mvcstat|Moving file/group CCASTAT entries]]. </li><br />
</ul><br />
<br />
==LOGFILE and LOGGRP enhancements==<br />
<var class="product">SirSafe</var> enhances the <var>[[LOGFILE command|LOGFILE]]</var> and<br />
<var>[[LOGGRP command|LOGGRP]]</var> commands to facilitate the management of<br />
file and group password table entries.<br />
These changes are active whenever <var class="product">SirSafe</var> is enabled,<br />
whether the <var class="product">SirSafe</var> mode is <i>required</i> or <i>optional</i>.<br />
<br />
===Viewing visible entries in sorted display===<br />
Even though visible file and group entries begin with a different character (<tt>></tt>)<br />
than their standard counterparts, the file and group sections of the CCASTAT<br />
file are sorted in order of file or group name and index character.<br />
<p class="code"><b>logfile procfile</b><br />
<nowiki>>PROCFILE A THEMAN X'BFFF' 0, 0, 0, 0, 0, ALL<br />
:PROCFILE B ******** X'0761' 0, 0, 0, 0, 0, ALL<br />
>PROCFILE 4 THEMAN X'0221' 0, 0, 0, 0, 0, ALL<br />
</nowiki></p><br />
Note that for visible entries, the value of the password is displayed in<br />
clear text, while standard entries are flagged with a field of eight asterisks.<br />
<br />
===<b id="pwdloca"></b>Selecting entries by password===<br />
The syntax for <var>LOGFILE</var> and <var>LOGGRP</var> is extended to include a <var>PWDLOCATE</var> option.<br />
If the keyword <var>PWDLOCATE</var> is present, the end user is prompted for a password value.<br />
That value is used to filter the list of entries that would have been produced without the <var>PWDLOCATE</var> option, and the entries with matching password values is displayed.<br />
<br />
====LOGFILE PWDLOCATE syntax====<br />
<p class="syntax">LOGFILE [PWDLOCATE] [ [<span class="term">filename1</span>] [<span class="term">filename2</span>] ]<br />
</p><br />
If just one filename is provided, the command lists just the entries for that file.<br />
Otherwise, the command lists all the entries that are between the two values, inclusive.<br />
<br />
====LOGGRP PWDLOCATE syntax====<br />
<p class="code">LOGGRP [PWDLOCATE] [ [<span class="term">groupname1</span>] [<span class="term">groupname2</span>] ]<br />
</p><br />
If just one group name is provided, the command lists just the entries for that group.<br />
Otherwise, the command lists all the entries that are between the two values, inclusive.<br />
<br />
====Example====<br />
The following example assumes that the user entered <code>theman</code> in response<br />
to the password prompt:<br />
<p class="code"><b>logfile pwdlocate</b><br />
<nowiki>*** M204.0347: PASSWORD<br />
>PROCFILE A THEMAN X'BFFF' 0, 0, 0, 0, 0, ALL<br />
>PROCFILE 4 THEMAN X'BFFF' 0, 0, 0, 0, 0, ALL<br />
</nowiki></p><br />
<br />
For an additional example using <var>PWDLOCATE</var>, see [[SirSafe control of access to passwords#idccsta|Identifying file/group CCASTAT entries]]<br />
<br />
==SECURE command enhancements==<br />
The variant of the <var>[[SECURE command: File|SECURE]]</var> command used to secure a file<br />
is extended to accept the qualifier <var>FILE</var> and the optional keyword <var>SIRSAFE</var>:<br />
<br />
====SECURE FILE syntax====<br />
<p class="code">SECURE [[FILE] SIRSAFE]<br />
</p><br />
If the keyword <var>SIRSAFE</var> is present, the current file<br />
is set in a mode such that it can only be open when <var class="product">SirSafe</var> is active.<br />
<br />
For additional comments about this feature, see [[SirSafe control of access to passwords#secure|Enhanced SECURE command]].<br />
<br />
==Subsystem control commands==<br />
For versions of Model&nbsp;204 prior to 7.5, only sites authorized for SirSafe were allowed to set the <var>[[APSYSEC parameter|APSYSEC]]</var> parameter. <var>APSYSEC</var> lets a system manager <var>[[START command: Starting an application subsystem|START]]</var>, <var>[[STOP command: Stopping an application subsystem|STOP]]</var>, <var>[[DEBUG command|DEBUG]]</var>, or <var>[[TEST command|TEST]]</var> any subsystem, without having to<br />
add the system manager to the [[SCLASS]] authorized to do these things.<br />
<br />
For sites with Model&nbsp;204 7.5 and higher, no SirSafe authorization is required for <var>APSYSEC</var>.<br />
<br />
==$Sir_Check_Access==<br />
{{Template:$Sir Check Access}}<br />
<br />
==See also==<br />
{{Template:SirSafe topic list}}<br />
<br />
[[Category:SirSafe]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=SirSafe&diff=103941SirSafe2017-07-25T23:06:19Z<p>Admin: link repair</p>
<hr />
<div><var class="product">SirSafe</var> integrates the file security and access control mechanisms employed<br />
by <var class="product">Model 204</var> with the native facilities of MVS (OS/390 and z/OS).<br />
<var class="product">SirSafe</var> addresses several potential security exposures, while providing significant improvements in usability for large scale environments.<br />
<var class="product">SirSafe</var> allows <var class="product">Model&nbsp;204</var> to continue to use its proprietary security<br />
mechanisms to manage access to the information contained in database<br />
files, preserving its rich set of security controls.<br />
In addition to improving security, the tight integration of <var class="product">SirSafe</var> with<br />
modern MVS facilities enables support of <i>read-only</i> files, and it<br />
simplifies file sharing among members of a sysplex.<br />
<br />
==Overview==<br />
<var class="product">SirSafe</var> functions as a layer on top of <var class="product">Model&nbsp;204</var>, using the System Authorization<br />
Facility (SAF) to control access to individual <var class="product">Model&nbsp;204</var> file and group passwords.<br />
SAF provides a standardized interface for accessing the services of a system<br />
<b>security manager</b> such as RACF, ACF2, or Top Secret.<br />
The <var class="product">Model&nbsp;204</var> System Manager is still responsible for maintaining file and<br />
group entries in a <var class="product">Model 204</var> password table (<code>CCASTAT</code>).<br />
However, each user's access to particular file and group <i>entries</i> in the password<br />
table is controlled by a system security manager, using rules entered by a system security officer.<br />
Thus, even if a password is known to a user, that user may be prevented<br />
from gaining the access rights conferred by the password.<br />
<br />
<var class="product">SirSafe</var> can significantly improve the behavior of <var class="product">Model&nbsp;204</var> in multi-system or sysplex environments.<br />
In addition, <var class="product">SirSafe</var> extends the functionality of <var class="product">Model&nbsp;204</var> database file security<br />
in four important ways:<br />
<ul><br />
<li>The security of data contained in <var class="product">Model&nbsp;204</var> databases no longer depends upon<br />
maintaining the secrecy of file and group passwords. </li><br />
<br />
<li><var class="product">SirSafe</var> can be configured to support read-only access to database files,<br />
preventing unintended updates while reducing the number of users requiring<br />
update access to <var class="product">Model&nbsp;204</var> file data sets. </li><br />
<br />
<li>A given file or group password can confer different privileges,<br />
depending upon the identity of the current user and the current Online,<br />
<i>without</i> the confusion of multiple password tables. </li><br />
<br />
<li>Enhancements to the <var class="product">Model&nbsp;204</var> <var>[[SECURE command: File|SECURE]]</var> command<br />
make it easier to manage security in complex, multiple online environments,<br />
while also eliminating certain security exposures. </li><br />
</ul><br />
<br />
By providing control over who can use <var class="product">Model&nbsp;204</var> file and group passwords,<br />
<var class="product">SirSafe</var> allows the passwords to be freely shared, without the need for periodic changes.<br />
Straightforward file and group passwords that are easy to remember, such as<br />
<code>read</code>, <code>update</code>, or <code>sysprog</code>, can be freely<br />
distributed and embedded in batch job streams.<br />
Security is not compromised, because <var class="product">SirSafe</var> will verify access to the passwords for each user and for the submittor of batch jobs.<br />
<br />
This is especially useful for large programming teams, where members may come and go.<br />
Without <var class="product">SirSafe</var>, an ever-expanding circle of programmers become aware of key <var class="product">Model&nbsp;204</var> file and group passwords, or the passwords need<br />
to be changed frequently and redistributed to those users still authorized.<br />
With <var class="product">SirSafe</var>, the system security administrator would simply change<br />
the access rules for the affected user in order to grant or revoke<br />
access to the required <var class="product">Model&nbsp;204</var> file and group passwords.<br />
<br />
==Model 204 database security==<br />
<var class="product">Model&nbsp;204</var> enforces a sophisticated array of controls to enforce security and integrity policies for its database files.<br />
The access to each individual file is determined by fourteen independent capability bits, four<br />
separate access levels for field-level security, and a procedure class designation.<br />
The "file group" feature of <var class="product">Model&nbsp;204</var> adds an additional two<br />
capability bits for each database file that is accessed as a group member.<br />
All of these controls are documented in [[Model 204 security features]].<br />
<br />
===Subsystem access rights===<br />
Most end users access applications that are formally defined to <var class="product">Model&nbsp;204</var> as application subsystems,<br />
using the <code>SUBSYSMGMT</code> administrative tool described in<br />
[[System requirements for Application Subsystems#Overview of the SUBSYSMGMT interface|Overview of the SUBSYSMGMT interface]].<br />
Application subsystems are invoked from the <var class="product">Model&nbsp;204</var> command level with a simple command, and then<br />
the so-called "APSY" runtime uses information saved in the [[System requirements for Application Subsystems#Overview of CCASYS|CCASYS]] file to determine the<br />
set of files and groups that need to be opened for the application along with<br />
their appropriate access rights.<br />
Users of application subsystems are not prompted for file or group passwords:<br />
the subsystem definition identifies<br />
the access granted for each user, with some users getting potentially different<br />
privileges based upon their user ID.<br />
<br />
<var class="product">SirSafe</var> does not affect how APSY assigns file or group privileges. SirSafe does, however, offer the use of Model&nbsp;204 [[SirSafe command and function reference#Subsystem control commands|subsystem maintenance commands]] that simplify the stopping, starting, testing, and debugging of subsystems.<br />
<br />
===Model 204 password table===<br />
Programmers and DataBase Administrators frequently use the<br />
<var class="product">Model&nbsp;204</var> <var>OPEN</var><br />
command to access files and groups while they are developing applications and maintaining files.<br />
The file or group access privileges granted as a result of an <var>OPEN</var> command depend upon the <i>type</i> of the file and upon the user-provided password, as follows:<br />
<br />
<table class="thJustBold"><br />
<tr><th>Public</th><br />
<td>The end-user is not prompted for a password, and the privileges are those that were specified as the default when the file or group was created.</td></tr><br />
<br />
<tr><th>Semipublic</th><br />
<td>The end-user is prompted for a password. The <var class="product">Model&nbsp;204</var> password table is searched for a corresponding password (for the file or group being opened),<br />
and if a match is found, the user is given the privileges from the matching entry. If a matching password is not found, the user is given the default privileges for the file, as specified when the file or group was created.</td></tr><br />
<br />
<tr><th>Private</th><br />
<td>The end-user is prompted for a password. The <var class="product">Model&nbsp;204</var> password table is searched for a corresponding password (for the file or group being opened),<br />
and if a match is found, the user is given the privileges from the matching entry. Otherwise the <var>OPEN</var> is rejected.</td></tr><br />
</table><br />
The <var class="product">Model&nbsp;204</var> password table provides the ability to store multiple passwords for each<br />
file or group.<br />
A distinct set of access rights is associated with each password, so in effect the passwords become substitutes for named roles.<br />
It is the development and the file maintenance roles that present the<br />
greatest challenges, since they confer the strongest (update) privileges,<br />
and they are frequently embedded in maintenance job streams.<br />
<br />
==Model 204 password table (CCASTAT)==<br />
The <var class="product">Model&nbsp;204</var> password table (maintained in the sequential file <code>CCASTAT</code>)<br />
is divided into three physical sections.<br />
The <code>user&nbsp;ID</code> section contains one entry for each<br />
ten-character login ID that is directly managed by <var class="product">Model&nbsp;204</var><br />
(as opposed to the IDs managed by a "security manager" like RACF or ACF2).<br />
Each user ID entry holds a one-way encrypted password and a set of login privileges.<br />
Most users of <var class="product">SirSafe</var> do not use CCASTAT to manage login security; instead they typically use a formal security manager like RACF or ACF2.<br />
For more information, refer to the Model 204 [[Security interfaces overview|security interfaces wiki pages]].<br />
<br />
The <code>file</code> and <code>group</code> sections of CCASTAT contain the various one-way<br />
encrypted passwords and the privileges they confer for <var class="product">Model&nbsp;204</var> database files and groups.<br />
The two sections are physically distinct so that a file and group of the<br />
same name can have separately managed passwords.<br />
A particular file or group may have multiple entries in CCASTAT, each<br />
conferring a set of (possibly different) access rights and privileges.<br />
<br />
The <var>[[LOGCTL command: Modifying user ID entries in the password table|LOGCTL]]</var> command is used to<br />
maintain entries in the <var class="product">Model&nbsp;204</var> password table.<br />
Variants of the <var>LOGCTL</var> command are used to <var>A</var>dd, <var>D</var>elete or <var>C</var>hange entries in CCASTAT.<br />
The basic form of the command is:<br />
<p class="syntax">LOGCTL {A | D | C} <span class="term">key</span><br />
</p><br />
The first argument indicates the type of operation being performed.<br />
<var class="term">key</var> indicates both the type of entry as well as the specific entry:<br />
<ul><br />
<li>For a file entry, <var class="term">key</var> must begin with a colon (<tt>:</tt>),<br />
immediately followed by a one- to eight-character file or group name, then<br />
one or more optional blanks and a single <i>index character</i>.<br />
If no index character is present, a blank is assumed.</li><br />
<br />
<li>For group entries, the format is the same as for a file entry,<br />
except the colon character is replaced by a comma (<tt>,</tt>).</li><br />
<br />
<li>For a login entry, a key contains from one to ten alphanumeric characters.</li><br />
</ul><br />
<br />
The following example deletes the password table entry for group <code>GARY</code> with an<br />
index character of <code>C</code>, and then it adds an entry for file <code>ALEX</code> with index character <code>2</code>:<br />
<p class="code">LOGCTL D ,GARY C<br />
LOGCTL A :ALEX 2<br />
</p><br />
After the second command completes, the end user is prompted to enter a password, privileges, and other access information, and a terminal mask, if any.<br />
<br />
The three sections of the password table are maintained in the order of their<br />
ten-byte key strings.<br />
Thus all of the entries for a particular file follow each other, sorted in the<br />
order of their index character (with blank coming first, of course).<br />
The <var>LOGFILE</var> command is used to display the file entries in a CCASTAT,<br />
producing output like:<br />
<p class="code"><nowiki>:ALANPROC X'0201' 0, 0, 0, 0, 0, ALL<br />
:ALANPROC A X'BFFF' 0, 0, 0, 0, 0, ALL<br />
:ALANPROC 1 X'0CCC' 0, 0, 0, 0, 0, ALL<br />
:ASDF X'BFFF' 0, 0, 0, 0, 0, ALL<br />
:BACKUP X'8761' 0, 0, 0, 0, 0, ALL<br />
</nowiki></p><br />
When a Semipublic or Private file or group is OPENed, the end user is<br />
prompted for a password, which is immediately one-way encrypted.<br />
Then the file or group section of CCASTAT is searched for a match on the<br />
"middle" eight characters of the key.<br />
For each file or group name match, the one-way encrypted password in the<br />
entry is compared to the one-way encrypted value of the password provided by the end-user.<br />
If they match, the privileges contained in the entry are granted to the <var>OPEN</var> request.<br />
Otherwise, the scan continues until all entries for the file/group have been checked.<br />
<br />
You can see that if two or more CCASTAT entries for a file or group contain the same password, the one with the lowest index character value will be the only one ever used.<br />
The possibility of duplicate passwords, coupled with the fact that<br />
<var>LOGFILE</var> and <var>LOGGRP</var> don't display password values, can cause a great deal of confusion.<br />
<br />
SirSafe offers <var>LOGCTL</var>, <var>LOGFILE</var>, and <var>LOGGRP</var> enhancements to make password table maintenance simpler. See [[SirSafe command and function reference#LOGCTL enhancements for visible file/group entries|LOGCTL enhancements for visible file/group entries]] and [[SirSafe command and function reference#LOGFILE and LOGGRP enhancements|LOGFILE and LOGGRP enhancements]].<br />
<br />
==SECURE and DESECURE commands==<br />
Each password table contains an encrypted eight-character key value.<br />
The <var>[[LOGKEY command|LOGKEY]]</var> command changes the key value from its default.<br />
The <var>SECURE</var> command copies the current CCASTAT key value into the current default file.<br />
Once this has been done, that file can only be opened by a copy of <var class="product">Model&nbsp;204</var> using a CCASTAT with the same key value.<br />
This feature can be used to prevent a malicious user from counterfeiting a<br />
password table and using it to<br />
obtain inappropriate access to a private or semipublic <var class="product">Model&nbsp;204</var> database file.<br />
Once a file has been successfully opened, the <var>DESECURE</var> command can be used to clear the key value<br />
from the current default file so that it can once again be opened by an Online with any CCASTAT.<br />
<br />
==Physical OPEN of Model 204 files==<br />
Under MVS, <var class="product">Model&nbsp;204</var> does a physical (operating system) OPEN of its database files with the INOUT option, using the access profile of the current job.<br />
Because INOUT implies WRITE access to the file, the job's profile must<br />
allow WRITE access, or the <var>Open</var> will be rejected with an IEC150I message.<br />
<br />
The INOUT option is used because a subsequent <var>OPEN</var> for the same file uses the already opened DCB, so the initial <var>OPEN</var> must allow for READ or WRITE access.<br />
While this is not typically a problem for Online jobs, it means that users running batch jobs<br />
require WRITE access to the data sets of the <var class="product">Model&nbsp;204</var> database files,<br />
even if the files are opened with access privileges that do not allow updating.<br />
This can raise concerns with Sarbanes/Oxley reporting requirements.<br />
<br />
==Shared DASD enqueueing==<br />
A shared DASD configuration allows a particular DASD device to be accessed by more than one computer system or operating system instance.<br />
Shared DASD has become far more common with the advent of Logical PARtition<br />
(LPAR) support, fiber-optic (ESCON) channels with EMIF sharing between LPARs, and Sysplex clusters.<br />
<br />
<var class="product">Model 204</var> utilizes a variety of mechanisms to serialize the access and update of database files<br />
among the various users in an online instance and between various instances of <var class="product">Model&nbsp;204</var>.<br />
The primary mechanism serializing database file accesses between various instances of<br />
<var class="product">Model&nbsp;204</var> is the operating system ENQ and DEQ facility.<br />
<br />
When a database file is opened, <var class="product">Model&nbsp;204</var> enqueues upon a resource name comprising the<br />
database file name, the volume serial for the first (or only) data set of<br />
the file, and the data set name for the first data set:<br />
<p class="code"><i>filename.volser.fully_qualified_dataset_name</i><br />
</p><br />
The strength of enqueue (share or exclusive) depends upon the access intent for the file.<br />
In order to support deadlock-free reduction in access strength, <var class="product">Model&nbsp;204</var> uses three<br />
different "queue names": <code>IFAMQA</code>, <code>IFAMQB</code>,<br />
and <code>IFAMQC</code>.<br />
<br />
This mechanism works well for cataloged and uncataloged data sets<br />
referenced only from one operating system instance.<br />
However, it breaks down when two instances of <var class="product">Model&nbsp;204</var> running on<br />
separate systems access the same file via shared DASD.<br />
By default, the two operating system instances will not<br />
share information about the enqueues used by <var class="product">Model&nbsp;204</var>.<br />
Thus, two separate instances of <var class="product">Model&nbsp;204</var>, each running on different systems, can<br />
simultaneously hold exclusive enqueues for the same resource.<br />
<br />
The shared DASD support in <var class="product">Model&nbsp;204</var> is based upon the concept of a "Shared DASD Enqueue List."<br />
This enqueue list is a structure contained in the first page of the first (or only) data set of each database file, the <b>File Parameter List (FPL)</b> page.<br />
An entry is placed in a file's enqueue list for every <var class="product">Model&nbsp;204</var> instance that opens the file.<br />
The entry is deleted when the file is physically closed by the instance, and the entry is updated if the instance changes its access intent for the file.<br />
<br />
The shared DASD enqueue list is used during the <var class="product">Model&nbsp;204</var> database file open process<br />
to identify conflicts with <var class="product">Model&nbsp;204</var> instances running under other operating system instances.<br />
Each entry in the enqueue list contains the following information:<br />
<br />
<table><br />
<tr><td nowrap>System name</td><br />
<td>A four-character name that identifies the system that is hosting the <var class="product">Model&nbsp;204</var> instance, identified as the first field in message M204.0061.<br />
For instances running under MVS, this ID will be the SMF system ID, set by the parameter <code>SID</code> in a <code>SMFPRMxx parmlib</code> member.<br />
For instances running under CMS, this ID will be <code>CMS</code>.</td></tr><br />
<br />
<tr><td>Access intent</td><br />
<td>This is <code>EXCL</code> when a file is opened for update; otherwise, it is <code>SHR</code>.</td></tr><br />
<br />
<tr><td>Job name</td><br />
<td>For most operating systems, this is the job name of the <var class="product">Model&nbsp;204</var> instance.<br />
For instances of <var class="product">Model&nbsp;204</var> running under CMS, it is the ID of the <var class="product">Model&nbsp;204</var> virtual machine.</td></tr><br />
<br />
<tr><td>Step name</td><br />
<td>For most operating systems, this is the step name of the <var class="product">Model&nbsp;204</var> instance.<br />
For instances of <var class="product">Model&nbsp;204</var> running under CMS, it is the six-character CPU serial number padded on the right with two blanks.</td></tr><br />
<br />
<tr><td>Date/Time</td><br />
<td>The date and time when the entry was added or last updated.</td></tr><br />
</table><br />
<br />
The open logic also removes obsolete enqueue entries that were established,<br />
but no longer needed, by <var class="product">Model&nbsp;204</var> instances executing under the current operating system instance.<br />
Obsolete entries can result from system crashes, x22 ABENDs, and other infrequent (but ordinary) events.<br />
The following logic is used:<br />
<ol><br />
<li>Standard operating system ENQ/DEQ logic is used to enqueue<br />
upon the specific database file.<br />
If the enqueue fails, the open is rejected with <i>file is in use</i>.<br />
<br />
<li>A hardware <code>RESERVE</code> is placed upon the volume containing the FPL page.<br />
This prevents other systems from accessing the device and potentially<br />
changing the enqueue list.<br />
<br />
<li>The FPL is read and the shared DASD enqueue list is scanned for a conflict with the<br />
access being requested by the current open.<br />
<ol type="a"><br />
<li>If an entry is found that conflicts with our access, but the entry was<br />
established by a <var class="product">Model&nbsp;204</var><br />
instance under our system, delete the entry because it is obsolete.<br />
We know the entry is obsolete because the standard ENQ/DEQ mechanism under our operating system gave us the requested access.<br />
<br />
<li>If a conflicting entry was established under a <b>different</b> operating system instance,<br />
reject the open with M204.0582 <i>access prevented by</i> and M204.0584 <i>file is in use</i> messages.<br />
<br />
<li>If all entries are processed with no current conflict, then add an entry for our requested access, and write the FPL back out to disk.<br />
</ol><br />
<br />
<li>Release the hardware <code>RESERVE</code> on the volume containing the FPL page.<br />
</ol><br />
If an <var>Open</var> request is prevented by an obsolete entry from a different operating<br />
system instance, the <var class="product">Model&nbsp;204</var> <var>ENQCTL</var> command can be used to clear out the offending entry.<br />
If <var>ENQCTL</var> is used to delete a non-obsolete entry, then an <code>M204.0585 <i>list overlaid</i></code> message results when the file is closed on the system whose entry was deleted.<br />
<br />
==SirSafe topics==<br />
The <var class="product">SirSafe</var> documentation consists of the pages listed below. <br />
This list is also available as a "See also" link from each of the pages. <br />
<br />
For information about product changes and Model&nbsp;204 feature<br />
support per <var class="product">SirSafe</var> version, see<br />
the [[M204wiki main page#rktools_notes|RKTools release notes]].<br />
<br />
For information about product error messages, see [[List of Model 204 messages#msir|MSIR. messages]].<br />
<br />
{{Template: SirSafe topic list}}<br />
<br />
[[Category:SirSafe]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Establishing_and_maintaining_security&diff=103940Establishing and maintaining security2017-07-25T23:04:07Z<p>Admin: link repair</p>
<hr />
<div>==Overview==<br />
<p><br />
<var class="product">Model&nbsp;204</var> provides basic internal security features at all levels. </p><br />
<p><br />
All security features are optional. Any combination of features is supported.</p><br />
<p><br />
[[Storing security information (CCASTAT)]]<br />
explains how to maintain the CCASTAT data set, which contains a password table of encrypted user and file security information. </p><br />
<p><br />
For information about <var class="product">Model&nbsp;204</var> and standard commercial security interfaces, refer to [[:Category:Security interfaces|Security interfaces]]. </p><br />
<br />
==File security==<br />
<p><br />
The file security feature limits access to particular files by requiring a password to open the file. The type of operation a particular user can perform on the file is also controlled by the file password. </p><br />
<br />
===OPENCTL parameter===<br />
<p><br />
The <var>OPENCTL</var> parameter, issued during creation of the file (or reset during a <var class="product">Model&nbsp;204</var> run) determines whether a file is public (no password required) or is protected by one of several levels of file, group, and record security.</p><br />
<p><br />
For <var>OPENCTL</var> settings that pertain to Parallel Query Option/204, see [[OPENCTL parameter]].<br />
</p><br />
<br />
===PRIVDEF parameter===<br />
<p><br />
Access to a file is limited by the settings on the <var>PRIVDEF</var> parameter. The <var>PRIVDEF</var> parameter summarizes the default file privileges that are assigned when a public file is opened, or when a semipublic file is opened without a password or with an invalid password. User privileges are included in the <var>PRIVDEF</var> specification. </p><br />
<p><br />
Set <var>PRIVDEF</var> to any combination of values listed below in [[#PRIVDEF parameter settings|PRIVDEF parameter settings]].</p><br />
<p><br />
If you must restrict the viewing of file-related parameters, reset the default value (X'BFFF') of <var>PRIVDEF</var> with the <var>RESET PRIVDEF</var> command. Otherwise, the odd setting of <var>PRIVDEF</var> allows a user to view file-related parameters through one of the following display commands or functions: </p><br />
<ul><br />
<li>DISPLAY FILE or DISPLAY VIEW</li><br />
<br />
<li>$View</li><br />
<br />
<li>IFDISP or IFPERM </li><br />
</ul><br />
<br />
====PRIVDEF parameter settings====<br />
<p><br />
The following table lists <var>PRIVDEF</var> settings, which you can add in any combination.</p><br />
<table><br />
<caption>PRIVDEF parameter values</caption><br />
<tr class="head"><br />
<th>Setting</th><br />
<th>User can...</th><br />
</tr><br />
<br />
<tr><br />
<td>X'8000'</td><br />
<td>Use privileged commands such as INITIALIZE, SECURE, and DESECURE. The user can also reset file parameters if ad hoc update privileges (X '2000') are obtained.</td><br />
</tr><br />
<br />
<tr><br />
<td>X'4000'</td><br />
<td>Override record security.</td><br />
</tr><br />
<br />
<tr><br />
<td>X'2000'</td><br />
<td>Update data with ad hoc requests or host language programs.</td><br />
</tr><br />
<br />
<tr><br />
<td>X'1000'</td><br />
<td>Make changes to procedures defined in the same file as the data but cannot delete them.</td><br />
</tr><br />
<br />
<tr><br />
<td>X'0800'</td><br />
<td>Update data with internal procedures.</td><br />
</tr><br />
<br />
<tr><br />
<td>X'0400'</td><br />
<td>Retrieve data with ad hoc requests or host language programs.</td><br />
</tr><br />
<br />
<tr><br />
<td>X'0200'</td><br />
<td>Display, echo, and copy internal procedures.</td><br />
</tr><br />
<br />
<tr><br />
<td>X'0100'</td><br />
<td>Retrieve data with internal procedures.</td><br />
</tr><br />
<br />
<tr><br />
<td>X'0080</td><br />
<td>Update data with procedures defined in a different file from the data.</td><br />
</tr><br />
<br />
<tr><br />
<td>X'0040'</td><br />
<td>Retrieve data with external procedures.</td><br />
</tr><br />
<br />
<tr><br />
<td>X'0020'</td><br />
<td>Include internal procedures.</td><br />
</tr><br />
<br />
<tr><br />
<td>X'0010'</td><br />
<td>Define internal procedures.</td><br />
</tr><br />
<br />
<tr><br />
<td>X'0008'</td><br />
<td>Delete internal procedures.</td><br />
</tr><br />
<br />
<tr><br />
<td>X'0001'</td><br />
<td>Access file related parameters.</td><br />
</tr><br />
</table><br />
<br />
===File password table maintenance===<br />
<p><br />
The password table contains one entry for each file password. These entries consist of the following information: </p><br />
<ul><br />
<li>File or group name</li><br />
<br />
<li>Password that the user must specify in order to be granted the file or group privileges</li><br />
<br />
<li>Two-byte representation of the user privileges that is granted when the user successfully opens the file or group (see the "PRIVDEF parameter values" table, above) </li><br />
<br />
<li>User class for procedures</li><br />
<br />
<li>Field-level security SELECT, READ, UPDATE, and ADD levels </li><br />
</ul><br />
<br />
====Using LOGCTL to modify the file password table====<br />
<p><br />
The <var>[[LOGCTL command: Modifying file entries in the password table|LOGCTL]]</var> command allows you to add or delete file entries in the password table. For example, the following command adds a file to the password table:</p><br />
<p class="code">LOGCTL A :<i>filename</i><br />
</p><br />
<p><br />
You can specify an index character, necessary to differentiate entries for future changes or deletions, when a file has more than one password.</p><br />
<p><br />
If you change a file or group password entry and omit one or more specifications, the corresponding entries in the password table are preserved.</p><br />
<p><br />
To list all the file entries in the password table, along with the associated privileges (but not the passwords), issue the <var>LOGFILE</var> command. </p><br />
<br />
====Sample dialogue using LOGCTL====<br />
<p><br />
The following dialogue illustrates the use of <var>LOGCTL</var> to add, change, and delete file entries in the password table:</p><br />
<p class="code"><b>LOGCTL A :CENSUS1</b><br />
<b></b>*** M204.0374: ENTER FILE/GROUP PASSWORD, PRIVILEGES, CLASS, SELECT, READ, UPDATE, ADD<br />
<br />
<b>ACCESS,X'0900',60,20,30,30,40</b><br />
<b></b>*** M204.0379: ENTER TERMINAL LIST,ALL,NONE,ADD,DEL,OR RETURN<br />
<b>21,31</b><br />
<br />
<b>LOGCTL C :TCENSUS3</b><br />
<b></b>***M204.0374:ENTER FILE/GROUP PASSWORD, PRIVILEGES, CLASS, SELECT, READ, UPDATE, ADD<br />
<b>,,70</b> <br />
<b></b>*** M204.0379: ENTER TERMINAL LIST, ALL, NONE, ADD, DEL, OR RETURN<br />
<br />
<b>LOGCTL D :XCENSUSA</b><br />
</p><br />
<br />
===Adding and removing security from files===<br />
<p><br />
To secure a file, issue the <var>[[SECURE command: File|SECURE]]</var> command, which ensures that a user cannot access a file illegally by running a <var class="product">Model&nbsp;204</var> program with its own password table.</p><br />
<p><br />
A special field in the password table serves as the key for securing files. When a secured file is opened, the key is compared with a copy placed in the file by the <var>SECURE</var> command. The file is accessed only if the two passwords match. The comparison with the key is performed even when the file is opened as part of a group.</p><br />
<p><br />
To reverse the security placed upon a file by the <var>SECURE</var> command, issue the <var>[[DESECURE command: File|DESECURE]]</var> command.</p><br />
<p><br />
For additional information about<br />
the <var>SECURE</var> and <var>DESECURE</var> commands, see [[Model 204 security features#SECURE command, definition format|SECURE command, definition format]].<br />
</p><br />
<p><br />
To change the key in the password table, issue the <var>[[LOGKEY command|LOGKEY]]</var> command.<br />
</p><br />
<br />
==Group security==<br />
<p><br />
The group security feature restricts access to particular file groups to certain users. When the group is created, access is limited by parameter settings of the <var>[[CREATE command: Permanent group|CREATE GROUP]]</var> command. A group can be classified as:</p><br />
<table><br />
<tr class="head"><br />
<th>Classification</th><br />
<th>Meaning</th><br />
</tr><br />
<br />
<tr><br />
<td>Public</td><br />
<td>When a public group is opened, default group privileges are defined on the <var>PRIVDEF</var> parameter in the group definition.</td><br />
</tr><br />
<br />
<tr><br />
<td>Semipublic</td><br />
<td>When a semipublic group is opened without a password or with an invalid password, default group privileges are defined on the <var>PRIVDEF</var> parameter in the group definition.</td><br />
</tr><br />
<br />
<tr><br />
<td>Private</td><br />
<td>A password is required to open the group.</td><br />
</tr><br />
</table><br />
<p><br />
In addition to the file privileges discussed in the [[#File security|File security]] section, you can assign two additional classifications with the <var>PRIVDEF</var> parameter:</p><br />
<table><br />
<tr class="head"><br />
<th>Classification</th><br />
<th>User can...</th><br />
</tr><br />
<br />
<tr><br />
<td>X'0004'</td><br />
<td>Update data via procedures from the procedure file.</td><br />
</tr><br />
<br />
<tr><br />
<td>X'0002'</td><br />
<td>Retrieve data via procedures from the procedure file.</td><br />
</tr><br />
</table><br />
<p><br />
Group entries have the same format as that shown for file entries earlier on this page.</p><br />
<br />
===LOGCTL and LOGGRP commands===<br />
<p><br />
The following considerations apply: </p><br />
<ul><br />
<li>Use the <var>[[LOGCTL command: Modifying group entries in the password table|LOGCTL]]</var> command to add or delete group entries in the password table. For example, the following command changes the entries in the password table for the group named <code>AREA</code>:<br />
<p class="code">LOGCTL C ,AREA<br />
</p><br />
</li><br />
<br />
<li>You can specify an index character, necessary to differentiate entries for future changes or deletions, when a file has more than one password.</li><br />
<br />
<li>To list all the group entries in the password table, along with the associated privileges (but not the passwords), issue the <var>[[LOGGRP command|LOGGRP]]</var> command. </li><br />
</ul><br />
<br />
==Record security==<br />
<p><br />
The record security feature limits access to individual records in a file. Each user can retrieve and update only records that the user has stored in the file or that other users have agreed to share. The existence of other records is not apparent.</p><br />
<p><br />
The following considerations apply:</p><br />
<ul><br />
<li>Record security can be in effect for one or more of the files in a group, but not for the group as a whole.</li><br />
<br />
<li>Access to a single record depends only on the record security field defined for the record's file.</li><br />
<br />
<li>Record security cannot be used unless login security is in effect.</li><br />
<br />
<li>To initiate record security, set the <var>OPENCTL</var> parameter in the <var>CREATE</var> command for the file and describe the special record security field in the <var>INITIALIZE</var> command. <br />
For more information about these commands, see [[Model 204 security features#Creating files with file security|Creating files with file security]] and [[Initializing files#Initializing a record security file|Initializing a record security file]].<br />
</li><br />
<br />
<li>Record security can be overridden if the user has been granted the record security override privilege at login time (the X'04' bit must be set) and the user's file password also contains the record security override privilege (X'4000'). </li><br />
<br />
<li>Record security can be overridden for a file in a permanent file group if login and group privileges (X '4000') allow it. </li><br />
</ul><br />
<br />
==Field-level security==<br />
<p><br />
The field-level security feature (FLS) controls access to the individual fields of a <var class="product">Model&nbsp;204</var> file, if access to a record is allowed by previous file-level and record-level security checks. </p><br />
<p><br />
Every field definition (created by the [[Defining fields manually|DEFINE FIELD command]]) can have a security level from 0 to 255 associated with it. </p><br />
<p><br />
A level of 0 implies no security for the field; 255 implies the highest security. Field access types are described in the following sections.</p><br />
<br />
===Scope of field-level security===<br />
<p><br />
Field-level security controls only explicit field references. Implicit references, such as retrieving a record security field with a FIND statement or adding a record security key value with STORE, are not controlled. </p><br />
<p><br />
To include user field access levels to file and group passwords in the password table, use the<br />
<var>[[LOGCTL command: Modifying user ID entries in the password table|LOGCTL]]</var> command<br />
to add or delete access entries. </p><br />
<p><br />
The way access levels are determined for files that are also members of groups is summarized in<br />
[[Model 204 security features#Determining user access levels|Determining user access levels]]. </p><br />
<br />
===Field access types===<br />
<p><br />
Each user is assigned access levels, ranging from 0 to 255, for each file and group opened. Access to a field is limited to any combination of the following access types: </p><br />
<table><br />
<tr class="head"><br />
<th>Access type</th><br />
<th>Means the ability to...</th><br />
</tr><br />
<br />
<tr><br />
<td>ADD</td><br />
<td>Add new occurrences of a field, including those added by a <var>Store Record</var> statement. ADD access lets data entry clerks or other personnel add new field occurrences or records without being able to change existing occurrences, or possibly even to examine them. Add access can also provide a user with the ability to add occurrences of the record security field without altering existing occurrences. </td><br />
</tr><br />
<br />
<tr><br />
<td>READ</td><br />
<td>Examine the value of a field (for example, in a SOUL <var>Print</var> or assignment statement).</td><br />
</tr><br />
<br />
<tr><br />
<td>SELECT</td><br />
<td>Use the field in a SOUL <var>Find</var> statement or an <var>IFFIND</var> call.</td><br />
</tr><br />
<br />
<tr><br />
<td>UPDATE</td><br />
<td><br />
<p><br />
Change the value of a previously stored occurrence of a field. UPDATE access can be granted without a corresponding READ access, which precludes updates of the form: </p><br />
<p class="code">CHANGE <i>fieldname</i>=<i>value1</i> TO <i>value2</i></p><br />
</td><br />
</tr><br />
</table><br />
<p><br />
When a user attempts to access a field in a particular way, <var class="product">Model&nbsp;204</var> compares the user's access levels with the field level defined for the field. If the user's level for the desired type of access is greater than or equal to the field's FLS level, the particular type of field access is allowed.</p><br />
<p><br />
For example, a user who has a READ level of 30 is permitted to display any field that has a READ level between 0 and 30, but cannot display a field that has a READ level of 40.</p><br />
<br />
===Sample dialogue using LOGCTL===<br />
<p><br />
The following example adds field security levels 50 (SELECT), 40 (READ), 10 (UPDATE), and 0 (ADD); no other information is changed: </p><br />
<p class="code"><b>LOGCTL C :CENSUS</b><br />
&#42;** M204.0374:ENTER FILE/GROUP PASSWORD, PRIVILEGES, CLASS, SELECT, READ, UPDATE, ADD<br />
<b>,,,50,40,10,0</b><br />
&#42;** M204.0379: ENTER TERMINAL LIST,ALL,NONE,ADD,DEL,OR RETURN<br />
</p><br />
<br />
==Procedure security==<br />
<p><br />
The procedure security feature limits access to defined procedures.</p><br />
<p><br />
The following considerations apply:</p><br />
<ul><br />
<li>You can specify privileges to enable a user to manipulate a procedure (display, define, or delete the procedure). </li><br />
<br />
<li>You can limit access to a procedure to a particular class of users by assigning a user class number to the procedure being secured.</li><br />
<br />
<li>Certain privileges (such as <var>SECURE</var> and <var>DESECURE</var>) associated with file and group passwords indicate the user privileges that pertain to the procedures for that file or group.</li><br />
<br />
<li>To assign user class and procedure class mappings (see [[Model 204 security features#Procedure security|Procedure security]]) to file and group passwords, use the <var>LOGCTL</var> command to add the mappings to the password table.<br />
<p><br />
Use <var>LOGCTL</var> to add, delete, or change the user class for procedures defined for a file or group. </p></li><br />
</ul><br />
<br />
===Sample dialogue using LOGCTL===<br />
<p><br />
The following example adds a user class of 70 to an existing file entry; no other information is changed:</p><br />
<p class="code"><b>LOGCTL C :CENSUS</b><br />
&#42;** M204.0374: ENTER FILE/GROUP PASSWORD, PRIVILEGES, CLASS, SELECT, READ, UPDATE, ADD <br />
<b>,,70</b><br />
&#42;** M204.0379: ENTER TERMINAL LIST,ALL,NONE,ADD,DEL,OR RETURN<br />
</p><br />
<br />
==Terminal security==<br />
<p><br />
The terminal security feature restricts access to certain login user IDs, files, or groups to users at identified terminals by associating a list of user numbers with each login, file, or group password. During <var class="product">Model&nbsp;204</var> initialization, a terminal can be assigned a particular user number according to the order of the user parameter lines and the way in which they are assigned to specific telecommunications unit numbers in the JCL.</p><br />
<p><br />
For example, a user at a particular terminal that has a specific number can log in to a specific user ID or open a specific file or group only if the terminal number is in the terminal list associated with the password for that user ID, file, or group. If it is not, <var class="product">Model&nbsp;204</var> responds as if the user entered an invalid password.</p><br />
<p><br />
Terminal security is generally used only with hard-wired terminals (terminals on leased lines). For dial-up terminals, the terminal can be connected to a number of similar telecommunications units and user parameter lines. Even though the location of a dial-up terminal is fixed, its terminal number can change every time it is dialed up. </p><br />
<p><br />
The following considerations apply:</p><br />
<ul><br />
<li>To insert terminal lists into the appropriate password table entries and to change existing terminal assignments, use the <var>LOGCTL</var> command.</li><br />
<br />
<li>To obtain listings of the login, file, or group entries in the password table, with legal terminal numbers included, issue a <var>LOGLST</var>, <var>LOGFILE</var>, or <var>LOGGRP</var> command. </li><br />
<br />
<li>To update all terminal lists at once, use the <var>[[TMASKUPDATE command|TMASKUPDATE]]</var> command.<br />
<p><br />
<var>TMASKUPDATE</var> takes no arguments. It loops through the password table, displays each entry for which ALL has not been specified, and allows you to specify a new terminal list or a blank line (no change).</p><br />
</li><br />
<br />
<li>All password table entries are treated as if terminal security were in effect, even if the terminal security feature is not used:</li><br />
<br />
<li>Terminal lists are variable length, allowing you to add terminals even if you exceed the original number planned for. </li><br />
<br />
<li>If you specify <var>ALL</var> for a password table entry, the terminal list takes up no space beyond the basic entry.</li><br />
<br />
<li>A list representing <var>NONE</var> takes two bytes.</li><br />
<br />
<li>To compute the length of a list containing numbers, divide the highest specified number by eight and rounding up to a multiple of two. </li><br />
</ul><br />
<br />
[[Category:System management]]<br />
[[Category:Security management]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=Defining_file_security_with_FILEMGMT&diff=103939Defining file security with FILEMGMT2017-07-25T23:02:33Z<p>Admin: link repair</p>
<hr />
<div><p><br />
You can define security for a <var class="product">Model&nbsp;204</var> file either using the File Management Subsystem facility (FILEMGMT) or from the command line. For ease of use and to avoid errors, FILEMGMT is recommended. </p><br />
<p><br />
Press the F8 (FORward) key from the [[Creating a file with FILEMGMT#Defining file organization|File Definition - Organization screen]], or the F7 (BACkward) key from the [[Defining file procedures with FILEMGMT|File Definition - Procedure screen]]. FILEMGMT displays the second file definition screen, the Security screen:</p><br />
<br />
<table><br />
<tr><td><br />
<p class="code">FILEMGMT File Definition - Security PAGE 2 OF 3<br />
<br />
Filename: ABC Inactive<br />
<br />
FILE ACCESS OPENCTL X' 80 '<br />
Public: X Semipublic: _ Private: _<br />
<br />
Record Security: _ Key:<br />
<br />
REMOTE FILE ACCESS PRIVILEGES<br />
NO/INV PWD: _ VALID PWD: _ GROUP MEMBER: _<br />
<br />
DEFAULT FILE PRIVILEGES PRIVDEF X' BFFF '<br />
File Manager: X Record Security Override: _ View File Parms: X<br />
<br />
RETRIEVE DATA WITH PROCEDURES<br />
Adhoc: X Internal: X External: X<br />
<br />
UPDATE DATA WITH PROCEDURES<br />
Adhoc: X Internal: X External: X<br />
<br />
INTERNAL PROCEDURES<br />
Display/Copy: X Define: X Change: X Delete: X Include: X<br />
<br />
DEFAULT FIELD LEVEL SECURITY<br />
SELLVL: 0 READLVL: 0 UPDTLVL: 0 ADDLVL: 0<br />
<br />
===><br />
<br />
1=HELp 2= 3=QUIt 4=FIElds 5=WIDen 6=COMmands<br />
<br />
7=BACkward 8=FORward 9=SIZe 10= 11= 12=END<br />
</p></td><br />
</tr><br />
</table><br />
<br />
<p><br />
You use the File Definition - Security screen to specify <var class="product">Model&nbsp;204</var> security parameters for the file you are creating. When this screen is displayed for a file for the first time, FILEMGMT shows the standard <var class="product">Model&nbsp;204</var> default values for the parameters. </p><br />
<p><br />
For some of the parameters shown on this screen, you specify an actual parameter value. For others, you select options, and FILEMGMT uses your selections to compute an appropriate parameter value.</p><br />
<p><br />
[[#Setting file security|Setting file security]] describes the type of information you enter. For more information about parameter settings, refer to [[Model 204 security features#File security|File security]] and to [[Seven-Step File Load examples]]. For a discussion of how to select the most appropriate options for your particular file, refer to [[Model 204 security features]].</p><br />
<p><br />
The cursor is initially positioned at the first input prompt (the <b>Public</b> input field).</p><br />
<br />
==Setting file security==<br />
<p><br />
You can select more than one option from an option category.</p><br />
<p><br />
To select an option, type <code>X</code> or another value as indicated.</p><br />
<p><br />
To enter a null: type a space, or preserve the default underscore character (<tt>_</tt>). Null indicates that you do not want to select the option. </p><br />
<p><br />
Typing a character other than these is invalid, and produces an error message.</p><br />
<p><br />
FILEMGMT displays and/or prompts you for the following information.</p><br />
<br />
<table class="thJustBold"><br />
<tr class="head"><br />
<th>Prompt</th><br />
<th>Response</th><br />
</tr><br />
<br />
<tr><br />
<th>Filename</th><br />
<td>FILEMGMT displays the name of the file that you entered on the primary screen, and indicates whether the file is <b>Active</b> or <b>Inactive</b>. </td><br />
</tr><br />
<br />
<tr><br />
<th>FILE ACCESS</th><br />
<td><br />
<p>Selects file access characteristics for the specified file. FILEMGMT computes the <var class="product">Model&nbsp;204</var> <var>[[OPENCTL parameter|OPENCTL]]</var> parameter from your selections and displays the computed value.</p><br />
<p>Select just one option from the <b>Public</b>, <b>Semipublic</b>, and <b>Private</b> options. </p><br />
<br />
<table><br />
<tr><br />
<th>Prompt</th><br />
<th>Default</th><br />
<th>Response</th><br />
</tr><br />
<br />
<tr><br />
<th>Public</th><br />
<td>X</td><br />
<td>File is a public file.</td><br />
</tr><br />
<br />
<tr><br />
<th>Semipublic</th><br />
<td>null</td><br />
<td>File is a semipublic file.</td><br />
</tr><br />
<br />
<tr><br />
<th>Private</th><br />
<td>null</td><br />
<td>File is a private file.</td><br />
</tr><br />
</table><br />
</td></tr><br />
<br />
<tr><br />
<th>Record Security</th><br />
<td>File has record security in effect.<br />
<br />
<table><br />
<tr class="head"><br />
<th>Prompt</th><br />
<th>Default</th><br />
<th>Response</th><br />
</tr><br />
<br />
<tr><br />
<td>Key</td><br />
<td>null</td><br />
<td><br />
<p><br />
Name of the field used as the record security key. <b>Key</b> requires an entry if you select Record Security. The entry must be a valid field name (1-70 characters). The requirements for a valid field name are described in [[Field names]].</p><br />
<p><br />
A null entry is required unless you select <b>Record Security</b>.</p><br />
</td></tr><br />
</table><br />
</td></tr><br />
<br />
<tr><br />
<th nowrap>REMOTE FILE ACCESS PRIVILEGES</th><br />
<td>Additional <var>OPENCTL</var> options for Parallel Query Option/204 (PQO) sites. The following options determine how a file can be accessed remotely.<br />
<br />
<table><br />
<tr class="head"><br />
<th>Prompt</th><br />
<th>Default</th><br />
<th>Response</th><br />
</tr><br />
<br />
<tr><br />
<th>NO/INV PWD</th><br />
<td>N/A</td><br />
<td>Accessible remotely without a valid password.<br />
</td><br />
</tr><br />
<br />
<tr><br />
<th>VALID PWD </th><br />
<td>N/A</td><br />
<td>Accessible remotely with a valid password.</td><br />
</tr><br />
<br />
<tr><br />
<th>GROUP MEMBER </th><br />
<td>N/A</td><br />
<td>Accessible remotely as a permanent group member.</td><br />
</tr><br />
</table><br />
</td></tr><br />
<br />
<tr><br />
<th>DEFAULT FILE PRIVILEGES</th><br />
<td>Select the default user privileges for the specified file. FILEMGMT computes the <var class="product">Model&nbsp;204</var> <var>[[PRIVDEF parameter|PRIVDEF]]</var> parameter from your selections and displays the computed value.<br />
<br />
<table><br />
<tr class="head"><br />
<th>Prompt</th><br />
<th>Default</th><br />
<th>Response</th><br />
</tr><br />
<br />
<tr><br />
<th>File Manager</th><br />
<td>X</td><br />
<td>Default user privileges include file manager privileges.</td><br />
</tr><br />
<br />
<tr><br />
<th>Record Security Override</th><br />
<td>null</td><br />
<td>Default user privileges allow record security to be overridden.</td><br />
</tr><br />
<br />
<tr><br />
<th>View File Parms</th><br />
<td>X</td><br />
<td>Default user privileges allow file parameters to be viewed.</td><br />
</tr><br />
</table><br />
</td></tr><br />
<br />
<tr><br />
<th nowrap>RETRIEVE DATA WITH PROCEDURES</th><br />
<td>Select the default user privileges for retrieving data by means of procedures.<br />
<br />
<table><br />
<tr class="head"><br />
<th>Prompt</th><br />
<th>Default</th><br />
<th>Response</th><br />
</tr><br />
<br />
<tr><br />
<th>Adhoc</th><br />
<td>X</td><br />
<td>Default user privileges allow data to be retrieved by ad hoc requests.</td><br />
</tr><br />
<br />
<tr><br />
<th>Internal</th><br />
<td>X</td><br />
<td>Default user privileges allow data to be retrieved by internal procedures.</td><br />
</tr><br />
<br />
<tr><br />
<th>External</th><br />
<td>X</td><br />
<td>Default user privileges allow data to be retrieved by external procedures.</td><br />
</tr><br />
</table><br />
</td></tr><br />
<br />
<tr><br />
<th>UPDATE DATA WITH PROCEDURES </th><br />
<td>Select the default user privileges for updating data by means of procedures.<br />
<br />
<table><br />
<tr class="head"><br />
<th>Prompt</th><br />
<th>Default</th><br />
<th>Response</th><br />
</tr><br />
<br />
<tr><br />
<th>Adhoc</th><br />
<td>X</td><br />
<td>Default user privileges allow data to be updated by ad hoc requests.</td><br />
</tr><br />
<br />
<tr><br />
<th>Internal</th><br />
<td>X</td><br />
<td>Default user privileges allow data to be updated by internal procedures.</td><br />
</tr><br />
<br />
<tr><br />
<th>External</th><br />
<td>X</td><br />
<td>Default user privileges allow data to be updated by external procedures.</td><br />
</tr><br />
</table><br />
</td></tr><br />
<br />
<tr><br />
<th>INTERNAL PROCEDURES</th><br />
<td>Select the default user privileges for performing operations on internal procedures.<br />
<br />
<table><br />
<tr class="head"><br />
<th>Prompt</th><br />
<th>Default</th><br />
<th>Response</th><br />
</tr><br />
<br />
<tr><br />
<th>Display/Copy</th><br />
<td>X</td><br />
<td>Default user privileges allow internal procedures to be displayed, echoed, and copied.</td><br />
</tr><br />
<br />
<tr><br />
<th>Define</th><br />
<td>X</td><br />
<td>Default user privileges allow internal procedures to be defined.</td><br />
</tr><br />
<br />
<tr><br />
<th>Change</th><br />
<td>X</td><br />
<td>Default user privileges allow changes (other than deletions) to internal procedures.</td><br />
</tr><br />
<br />
<tr><br />
<th>Delete</th><br />
<td>X</td><br />
<td>Default user privileges allow internal procedure to be deleted.</td><br />
</tr><br />
<br />
<tr><br />
<th>Include</th><br />
<td>X</td><br />
<td>Default user privileges allow internal procedures to be included.</td><br />
</tr><br />
</table><br />
</td></tr><br />
<br />
<tr><br />
<th>DEFAULT FIELD LEVEL SECURITY </th><br />
<td>Default field level security. Valid values are 0-255.<br />
<br />
<table><br />
<tr><br />
<th>Prompt</th><br />
<th>Default</th><br />
<th>Response</th><br />
</tr><br />
<br />
<tr><br />
<th>SELLVL </th><br />
<td>0</td><br />
<td>Default SELECT access. </td><br />
</tr><br />
<br />
<tr><br />
<th>READLVL </th><br />
<td>0</td><br />
<td>Default READ access. </td><br />
</tr><br />
<br />
<tr><br />
<th>UPDTLVL </th><br />
<td>0</td><br />
<td>Default UPDATE access. </td><br />
</tr><br />
<br />
<tr><br />
<th>ADDLVL </th><br />
<td>0</td><br />
<td>Default ADD access.</td><br />
</tr><br />
</table><br />
</td></tr><br />
</table><br />
<br />
==Resetting file security==<br />
<ol><br />
<li>Select the File maintenance <b>RESET</b> function (number 2) from the primary screen. FILEMGMT displays the first of the reset screens, the File Parameter Reset screen. </li><br />
<br />
<li>Press F8 (FORward) to display the File Security Reset screen:</li><br />
</ol><br />
<br />
<table><br />
<tr><br />
<td><br />
<p class="code">FILEMGMT File Security Reset Page 2 of 2<br />
<br />
Filename: ABC Inactive<br />
<br />
FILE ACCESS OPENCTL X' 80 '<br />
Public: X Semipublic: _ Private: _ Record Security:<br />
<br />
REMOTE FILE ACCESS PRIVILEGES<br />
NO/INV PWD: _ VALID PWD: _ GROUP MEMBER: _<br />
<br />
DEFAULT FILE PRIVILEGES PRIVDEF X' BFFF '<br />
File Manager: X Record Security Override: _ View File Parms: X<br />
RETRIEVE DATA WITH PROCEDURES<br />
Adhoc: X Internal: X External: X<br />
UPDATE DATA WITH PROCEDURES<br />
Adhoc: X Internal: X External: X<br />
INTERNAL PROCEDURES<br />
Display/Copy: X Define: X Change: X Delete: X Include: X<br />
<br />
DEFAULT FIELD LEVEL SECURITY<br />
SELLVL: 0 READLVL: 0 UPDTLVL: 0 ADDLVL: 0<br />
<br />
DEFAULT PROCEDURE CLASS PRCLDEF: 0<br />
<br />
===><br />
<br />
1=HELp 2= 3=QUIt 4= 5= 6=COMmands<br />
7=BACkward 8= 9= 10= 11= 12=END<br />
</p></td><br />
</tr><br />
</table><br />
<br />
<p><br />
You use the Reset screens to change the values of <var class="product">Model&nbsp;204</var> file parameters that were originally set on the File Definition screens or the [[Managing file and table size with FILEMGMT|File Size Definition screen]]. FILEMGMT stages the file for a <var>RESET</var> command in response to your input.</p><br />
<p><br />
The Reset screens display the file parameters that can be reset. File parameters not displayed on the Reset screens can be changed only by recreating the file.</p><br />
<p><br />
For some of the file parameters shown on these screens, you specify an actual parameter value. For others, you select options, and FILEMGMT uses your selections to compute appropriate values for the <var>FOPT</var>, <var>FRCVOPT</var>, <var>OPENCTL</var>, and <var>PRIVDEF</var> parameters.</p><br />
<p><br />
You need not fill in all values on all screens. Current parameter values are preserved for any parameters for which you do not enter values.</p><br />
<p><br />
You can move freely between the two Reset screens by pressing the F7 (BACkward) and F8 (FORward) keys. FILEMGMT does not save any of the information you enter until you press one of the following function keys from either of the screens:</p><br />
<br />
<table><br />
<tr><br />
<td>F6 </td><br />
<td>COMmands</td><br />
</tr><br />
<br />
<tr><br />
<td>F12</td><br />
<td>END </td><br />
</tr><br />
</table><br />
<br />
<p><br />
The section [[#Input for the Security Reset screens|Input for the Security Reset screens]] describes the type of information you enter. For more information about parameter settings, refer to the [[List of Model 204 parameters]]. For a discussion of how to select the most appropriate options for your particular file, refer to [[Model 204 security features#File security|File security]].</p><br />
<p><br />
The cursor is initially positioned at the first input prompt on the first screen.</p><br />
<br />
==Input for the Security Reset screens==<br />
<p><br />
You can select more than one option from an option category.</p><br />
<p><br />
To select an option, type <code>X</code> or a numeric value.</p><br />
<p><br />
To enter a null: type a space, or preserve the default underscore character (<tt>_</tt>). Null indicates that you do not want to select the option. </p><br />
<p><br />
Typing a character other than these is invalid, and produces an error message.</p><br />
<p><br />
FILEMGMT displays and/or prompts you for the following information.</p><br />
<br />
<table class="thJustBold"><br />
<tr class="head"><br />
<th>Prompt</th><br />
<th>Response</th><br />
</tr><br />
<br />
<tr><br />
<th>Filename</th><br />
<td>FILEMGMT displays the name of the file that you entered on the primary screen, and indicates whether the file is Active or Inactive. </td><br />
</tr><br />
<br />
<tr><br />
<th>FILE ACCESS</th><br />
<td>Select file access characteristics for the specified file. FILEMGMT computes a new value for the <var class="product">Model&nbsp;204</var> <var>OPENCTL</var> parameter from your selections and displays the computed value. Select just one option from the <b>Public</b>, <b>Semipublic</b>, and <b>Private</b> options. </td><br />
</tr><br />
<br />
<tr><br />
<th>Public</th><br />
<td>File is a public file. The default is <code>X</code>. </td><br />
</tr><br />
<br />
<tr><br />
<th>Semipublic</th><br />
<td>File is a semipublic file. The default is null. </td><br />
</tr><br />
<br />
<tr><br />
<th>Private</th><br />
<td>File is a private file. The default is null.</td><br />
</tr><br />
<br />
<tr><br />
<th>Record Security</th><br />
<td>File has record security in effect. The default is null.</td><br />
</tr><br />
<br />
<tr><br />
<th nowrap>REMOTE FILE ACCESS PRIVILEGES</th><br />
<td>Additional OPENCTL options for Parallel Query Option/204 (PQO) sites, the following options determine how a file can be accessed remotely.</td><br />
</tr><br />
<br />
<tr><br />
<th>NO/INV/ PWD</th><br />
<td>Accessible remotely without a valid password</td><br />
</tr><br />
<br />
<tr><br />
<th>VALID PWD</th><br />
<td>Accessible remotely with a valid password.</td><br />
</tr><br />
<br />
<tr><br />
<th>GROUP MEMBER</th><br />
<td>Accessible remotely as a permanent group member.</td><br />
</tr><br />
<br />
<tr><br />
<th>DEFAULT PROCEDURE CLASS PRCLDEF</th><br />
<td>Default user class for procedures, if the file is public or semipublic. <br />
<p><br />
Valid values are 0-255. The default is 0.</p></td><br />
</tr><br />
<br />
<tr><br />
<th>DEFAULT FILE PRIVILEGES</th><br />
<td>Select default user privileges characteristics for the specified file. FILEMGMT computes a new value for the <var class="product">Model&nbsp;204</var> <var>PRIVDEF</var> parameter from your selections and displays the computed value.</td><br />
</tr><br />
<br />
<tr><br />
<th>File Manager</th><br />
<td>Default user privileges include file manager privileges. The default is X.</td><br />
</tr><br />
<br />
<tr><br />
<th>Record Security</th><br />
<td>Default user privileges allow record security Override to be overridden. The default is null.</td><br />
</tr><br />
<br />
<tr><br />
<th>View File Parms</th><br />
<td>Default user privileges allow file parameters to be viewed. The default is <code>X</code>. </td><br />
</tr><br />
<br />
<tr><br />
<th colspan="2">RETRIEVE DATA WITH PROCEDURES</th><br />
</tr><br />
<br />
<tr><br />
<th>Adhoc</th><br />
<td>Default user privileges allow data to be retrieved by ad hoc requests. The default is X.</td><br />
</tr><br />
<br />
<tr><br />
<th>Internal</th><br />
<td>Default user privileges allow data to be retrieved by internal procedures. The default is X.</td><br />
</tr><br />
<br />
<tr><br />
<th>External</th><br />
<td>Default user privileges allow data to be retrieved by external procedures. The default is X. </td><br />
</tr><br />
<br />
<tr><br />
<th colspan="2">UPDATE DATA WITH PROCEDURES</th><br />
</tr><br />
<br />
<tr><br />
<th>Adhoc</th><br />
<td>Default user privileges allow data to be updated by ad hoc requests. The default is <code>X</code>.</td><br />
</tr><br />
<br />
<tr><br />
<th>Internal</th><br />
<td>Default user privileges allow data to be updated by internal procedures. The default is <code>X</code>.</td><br />
</tr><br />
<br />
<tr><br />
<th>External</th><br />
<td>Default user privileges allow data to be updated by external procedures. The default is <code>X</code>.</td><br />
</tr><br />
<br />
<tr><br />
<th colspan="2">INTERNAL PROCEDURES</th><br />
</tr><br />
<br />
<tr><br />
<th>Display/Copy</th><br />
<td>Default user privileges allow internal procedures to be displayed, echoed, and copied. The default is <code>X</code>.</td><br />
</tr><br />
<br />
<tr><br />
<th>Define</th><br />
<td>Default user privileges allow internal procedures to be defined. The default is X.</td><br />
</tr><br />
<br />
<tr><br />
<th>Change</th><br />
<td>Default user privileges allow changes (other than deletions) to internal procedures. The default is <code>X</code>.</td><br />
</tr><br />
<br />
<tr><br />
<th>Delete</th><br />
<td>Default user privileges allow internal procedures to be deleted. The default is <code>X</code>.</td><br />
</tr><br />
<br />
<tr><br />
<th>Include</th><br />
<td>Default user privileges allow internal procedures to be included. The default is <code>X</code>.</td><br />
</tr><br />
<br />
<tr><br />
<th>DEFAULT FIELD LEVEL SECURITY</th><br />
<td>Default field level security. Valid values are 0-255. The default is 0.</td><br />
</tr><br />
<br />
<tr><br />
<th>SELLVL</th><br />
<td>Default SELECT access. </td><br />
</tr><br />
<br />
<tr><br />
<th>READLVL</th><br />
<td>Default READ access. </td><br />
</tr><br />
<br />
<tr><br />
<th>UPDTLVL</th><br />
<td>Default UPDATE access. </td><br />
</tr><br />
<br />
<tr><br />
<th>ADDLVL</th><br />
<td>Default ADD access.</td><br />
</tr><br />
</table><br />
<br />
==File parameter reset commands==<br />
<p><br />
To issue a command, press a PF key or type a command name at the prompt (===>) and press Enter.</p><br />
<br />
<table><br />
<tr class="head"><br />
<th>Key</th><br />
<th>Command</th><br />
<th>Meaning</th><br />
</tr><br />
<br />
<tr><br />
<td>F1</td><br />
<td>HELp</td><br />
<td>Displays Help text for the File Parameter Reset screens.</td><br />
</tr><br />
<br />
<tr><br />
<td>F3</td><br />
<td>QUIt</td><br />
<td>Exits from the File Parameter Reset screens and returns to the primary screen without changing any parameter values. </td><br />
</tr><br />
<br />
<tr><br />
<td>F6</td><br />
<td>COMmands </td><br />
<td>Stages the file for <var>RESET</var>. Proceeds to the [[Executing and deleting commands with FILEMGMT#Execute Commands screen|Execute Commands screen]]. This screen displays the staged commands that were generated for the file and allows you to select the commands you want to execute. </td><br />
</tr><br />
<br />
<tr><br />
<td>F7</td><br />
<td>BACkward</td><br />
<td>Screen 2 only. Returns to the first File Parameter Reset screen. </td><br />
</tr><br />
<br />
<tr><br />
<td>F8</td><br />
<td>FORward</td><br />
<td>Screen 1 only. Proceeds to the second File Parameter Reset screen.</td><br />
</tr><br />
<br />
<tr><br />
<td>F12 </td><br />
<td>END</td><br />
<td>Stages the file for <var>RESET</var>. Exits from the File Parameter Reset screen and returns to the primary screen.</td><br />
</tr><br />
</table><br />
<br />
==Controlling file access with the SECURE and DESECURE commands==<br />
<p><br />
<var>[[SECURE command: File|SECURE]]</var> and <var>[[DESECURE command: Overview of DESECURE|DESECURE]]</var> are <var class="product">Model&nbsp;204</var> commands that you can use to control file access. </p><br />
<p><br />
Securing a file ensures that a user cannot access a file illegally by running a <var class="product">Model&nbsp;204</var> program with a different password table. A special key in the password table serves as the key for securing a file. The key can be changed by the system manager with the <var>[[LOGKEY command|LOGKEY]]</var> command. </p><br />
<p><br />
When a secured file is opened, <var class="product">Model&nbsp;204</var> compares the key to a copy placed in the file by the <var>SECURE</var> command. The file is opened if the two fields match. If the fields do not match, the user is logged out and an error message is displayed on the operator's console.</p><br />
<p><br />
Existing files can be secured or desecured. Staged files can be secured or desecured, with these exceptions:</p><br />
<ul><br />
<li>Files staged for <var>SECURE</var> cannot be desecured, and conversely, files staged for <var>DESECURE</var> cannot be secured.</li><br />
<br />
<li>Files staged for <var>CREATE</var>, <var>RECREATE</var>, <var>DELETE</var>, and <var>INITIALIZE</var> can be neither secured nor desecured. </li><br />
</ul><br />
<p><br />
You must have file-level privileges of at least X'A000' (file manager and ad hoc data update) to issue <var>SECURE</var> and <var>DESECURE</var> commands. In this case, you actually need update but not retrieve privileges. (Refer to [[Model 204 security features#File security|File security]] for a discussion of these privileges.)</p><br />
<p><br />
To stage a file for the <var>SECURE</var> or <var>DESECURE</var> command:</p><br />
<ol><br />
<li>Enter the file name on the primary screen.</li><br />
<li>Select the <var>SECURE</var> or <var>DESECURE</var> command.</li><br />
<li>Press Enter.</li><br />
</ol><br />
<br />
<p>FILEMGMT displays a message confirming that the file is staged for <var>SECURE</var> or <var>DESECURE</var>. You can proceed to the [[Executing and deleting commands with FILEMGMT#Execute Commands screen|Execute Commands screen]] to execute the command.</p><br />
<br />
<br />
[[Category:FILEMGMT application subsystem]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=File_integrity_and_recovery&diff=103938File integrity and recovery2017-07-25T23:00:57Z<p>Admin: link repair</p>
<hr />
<div><div class="toclimit-3"><br />
<br />
==Overview==<br />
<p><br />
After files have been designed and loaded, one of the file manager's most important responsibilities is to maintain the integrity of the files. This topic describes some of the error conditions that threaten file structures and the steps that you can take to safeguard the files. </p><br />
<br />
==Error recovery features==<br />
<p><br />
<var class="product">Model&nbsp;204</var> provides many features to ensure the data integrity, including:</p><br />
<ul><br />
<li>Extensive command syntax checking and compiler diagnostics.</li><br />
<br />
<li>Double-checking of files and tape backups to ensure that files are correctly mounted.</li><br />
<br />
<li>SNA Communications Server (formerly VTAM) error recovery routines for data transmission from user terminals. </li><br />
<br />
<li>Trailers on each page with information such as file name, page number, and table number, which <var class="product">Model&nbsp;204</var> checks every time the page is read or written to protect against loss of integrity due to a disk error.</li><br />
</ul><br />
<p><br />
In addition, <var class="product">Model&nbsp;204</var> provides error recovery facilities as described in the following sections.</p><br />
<br />
===Transaction back out facility===<br />
<p><br />
Data integrity and logical consistency of the files are protected by the <var class="product">Model&nbsp;204</var> Transaction back out facility, which can undo the effects of incomplete transactions on file data. <var class="product">Model&nbsp;204</var> automatically backs out an incomplete transaction for a transaction back out file if a user's request is canceled, if <var class="product">Model&nbsp;204</var> detects a file problem such as a table full condition, or if <var class="product">Model&nbsp;204</var> is restarting the user.<br />
See [[Transaction back out]] for details. </p><br />
<br />
===RESTART recovery facility===<br />
<p><br />
The system manager must include a RESTART command as part of User 0's input if an installation is to use system recovery facilities.<br />
The <var>[[RESTART command|RESTART]]</var> command and [[System and media recovery]] pages discuss the syntax of this command and describe the Roll Back, Roll Forward, and Ignore features. </p><br />
<br />
===Media recovery===<br />
<p><br />
In the event of a media failure, such as a disk head crash, <var class="product">Model&nbsp;204</var> allows you to recover files using the media recovery feature. Media recovery works by restoring files from a previously made backup copy, and then using the Roll Forward feature to reapply the updates that were made to the files since the time the copy was made. </p><br />
<p class="note"><b>Note:</b><br />
The <var>[[REGENERATE command|REGENERATE]]</var> command invokes the Restore and Roll Forward facilities automatically. In a media recovery run, the RESTORE and RESTART commands are not specified. </p><br />
<br />
==FRCVOPT parameter==<br />
<p><br />
The <var>[[FRCVOPT parameter|FRCVOPT]]</var> (file recovery options) parameter determines whether or not an installation logs checkpoint and/or Roll Forward information. The system manager also must include the <var>[[RESTART command|RESTART]]</var> command in a <var class="product">Model&nbsp;204</var> job in order for recovery to run. If an installation uses the system recovery facilities, the file manager can control how files are affected. </p><br />
<p><br />
The default setting of FRCVOPT is X'00'. The file participates in checkpointing, and batch <var class="product">Model&nbsp;204</var> jobs that update the file can be run while the Online job is up. If your installation uses Roll Forward, the file participates. The back out mechanism of transaction back out is enabled. </p><br />
<p><br />
If the <var>[[FOPT parameter|FOPT]]</var> parameter is also set to X'00' (enabling lock pending updates), the file is a transaction back out file. If the FOPT setting includes the X'02' option, disabling lock pending updates, <var class="product">Model&nbsp;204</var> automatically disables transaction back out by turning on the X'08' bit of FRCVOPT. </p><br />
<br />
===FRCVOPT parameter===<br />
<p><br />
File recovery options are controlled by the FRCVOPT parameter. The possible FRCVOPT settings are: </p><br />
<table><br />
<tr class="head"><br />
<th>Bit </th><br />
<th>Meaning</th><br />
</tr><br />
<br />
<tr><br />
<td align="right"> X'80'</td><br />
<td>File cannot be updated if Roll Forward logging is not active. </td><br />
</tr><br />
<br />
<tr><br />
<td align="right"> X'40'</td><br />
<td>File cannot be updated if checkpoint logging is not active. </td><br />
</tr><br />
<br />
<tr><br />
<td align="right"> X'20'</td><br />
<td>File does not participate in checkpoint logging.</td><br />
</tr><br />
<br />
<tr><br />
<td align="right"> X'10'</td><br />
<td>Discontinuities not allowed (hold enqueuing while file is closed if the file has been updated in this run).</td><br />
</tr><br />
<br />
<tr><br />
<td align="right"> X'08'</td><br />
<td>Transaction back out is disabled. If X'01' is specified, this option is automatically set. </td><br />
</tr><br />
<br />
<tr><br />
<td align="right"> X'04'</td><br />
<td>File does not participate in Roll Forward logging.</td><br />
</tr><br />
<br />
<tr><br />
<td align="right"> X'02'</td><br />
<td>File does not participate in Roll Forward logging.</td><br />
</tr><br />
<br />
<tr><br />
<td align="right"> X'01'</td><br />
<td>All updates are reapplied to the file during Roll Forward, without regard to update unit boundaries. Because transactions are explicitly handled differently between transaction back out (X'08' off) and Roll Forward all the way (X'01' on), this option forces the X'08' option; that is, transaction back out is automatically turned off. </td><br />
</tr><br />
</table><br />
<br />
===Eliminating checkpoints and Roll Forward logging===<br />
<p><br />
You can eliminate the overhead of checkpoint and Roll Forward logging if system crashes are infrequent and if manual backup facilities provide sufficient protection. To do this, turn on the X'24' bits of FRCVOPT. This strategy also works well for scratch files.</p><br />
<br />
===Logging all changes===<br />
<p><br />
At the other extreme, you might want to log all changes for recovery purposes. You can enforce this by setting the X'C0' bits of FRCVOPT. OPEN turns off all updating if logging is not active. The X'80' and X'40' bits are ignored if the OPEN command or statement is issued by User 0 and the file privileges include file manager. This override capability is designed to allow you to run batch update jobs, such as the File Load utility, without the overhead of logging.</p><br />
<br />
===Setting and clearing the X'10' bit===<br />
<p><br />
The FRCVOPT X'10' bit (discontinuities not allowed) is somewhat independent of the recovery facilities, although preventing discontinuities is less important when checkpointing is not being used. After the file has been updated, if the X'10' bit is set, <var class="product">Model&nbsp;204</var> retains a share enqueue for the file, even if all users have closed the file. A separate retrieval job runs, but an updating job waits.</p><br />
<p><br />
To allow a specific job to run, clear the X'10' bit of FRCVOPT and then close the file. If no other users have the file open, the batch job runs. After the batch job has finished, set the X'10' bit again.</p><br />
<br />
===Crash recovery features===<br />
<p><br />
In case of failure, <var class="product">Model&nbsp;204</var> makes every effort to clean up files and shut down softly. If <var class="product">Model&nbsp;204</var> or the operating system under which it is running crashes, any <var class="product">Model&nbsp;204</var> file being updated is flagged by a special setting of the <var>[[FISTAT parameter|FISTAT]]</var> parameter. The FILE PHYSICALLY INCONSISTENT message is issued whenever the file is opened thereafter until recovery procedures have been executed. In this case, or in the case of a hard crash, integrity can be recovered using the DUMP/RESTORE utility or restart/recovery facility. </p><br />
<br />
==FISTAT parameter==<br />
<p><br />
FISTAT is a flag parameter that provides control of update completion and other file status information. Generally, the meaning of the FISTAT setting and the actual state of the file determine any special action to be taken. </p><br />
<p><br />
It is important to understand the different types of errors that can occur during processing, the effect each error has on the file and the setting of FISTAT, and the separation of updates into "update units." </p><br />
<p><br />
The possible settings of FISTAT are: </p><br />
<table><br />
<tr class="head"><br />
<th>Bit </th><br />
<th>Meaning</th><br />
</tr><br />
<br />
<tr><br />
<td align="right">X'40'</td><br />
<td>File might be logically inconsistent. (Soft restart might have occurred.) Logical inconsistencies are described in more detail in [[#Logically inconsistent files|Logically inconsistent files]].</td><br />
</tr><br />
<br />
<tr><br />
<td align="right"> X'20'</td><br />
<td>File is in deferred update mode. Either a file load program or an OPEN in deferred update mode was applied to the file, and the Z command has not yet been issued.<br />
See [[Deferred update feature]] for more information about deferred update mode. </td><br />
</tr><br />
<br />
<tr><br />
<td align="right"> X'10'</td><br />
<td>File has been recovered. This notifies you that the file is intact but that some updates might have been undone. You might need to do some additional work to get the file to its most up-to-date state. Messages that describe the last updates applied are displayed when the file is opened. </td><br />
</tr><br />
<br />
<tr><br />
<td align="right"> X'08'</td><br />
<td>File is full. One of the Tables A, B, C, or D has filled up. If Table A or C fills up, or if Table B fills up in a hashed file, a reorganization is required. Otherwise, the INCREASE command can be used to add more space.</td><br />
</tr><br />
<br />
<tr><br />
<td align="right"> X'02'</td><br />
<td>File is physically inconsistent. The file was being updated when some form of severe error or a system crash occurred. This is described in detail in [[#Hard restarts|Hard restarts]]. This setting produces the FILE PHYSICALLY INCONSISTENT message. (A hard restart might have occurred.) </td><br />
</tr><br />
<br />
<tr><br />
<td align="right"> X'01'</td><br />
<td>File is not initialized. After a file is created, it must be initialized before data can be added.<br />
See [[Initializing files]] for more information.</td><br />
</tr><br />
</table><br />
<br />
==Restarts==<br />
<p><br />
<var class="product">Model&nbsp;204</var> provides two kinds of restarts: </p><br />
<ul><br />
<li>Soft</li><br />
<li>Hard</li><br />
</ul><br />
<br />
===Soft restarts===<br />
<p><br />
Soft restarts occur when <var class="product">Model&nbsp;204</var> recognizes a severe error that occurs between (as opposed to during) active update operations. </p><br />
<br />
====Causes of soft restarts====<br />
<p><br />
Severe errors include nonrecoverable terminal I/O errors such as: </p><br />
<ul><br />
<li>Phone is hung up</li><br />
<br />
<li>No input is coming in on a thread (with the inactive thread timeout feature enabled) for a specified number of seconds. Ssee [[Defining the user environment (CCAIN)#User environment control parameters|User environment control parameters]] for information on the TIMEOUT parameter.</li><br />
<br />
<li>Full server tables</li><br />
</ul><br />
<br />
====Full server tables in transaction back out files====<br />
<p><br />
If any server tables are full and the file is a transaction back out file, <var class="product">Model&nbsp;204</var> automatically backs out the incomplete transaction without a restart and informs the user through an error message that the transaction has been backed out. Otherwise, <var class="product">Model&nbsp;204</var> performs a soft restart.</p><br />
<br />
====Effects of soft restarts====<br />
<p><br />
In a soft restart:</p><br />
<ul><br />
<li>User receives the USER RESTARTED SOFTLY message and is automatically logged out.</li><br />
<br />
<li>File-physically-inconsistent flag is cleared (unless other users are updating the file) and the file-logically-inconsistent flag is set. </li><br />
</ul><br />
<p><br />
The file is physically consistent (that is, file structural elements are in order: entries in the index correspond to entries in the data, and so on). However, there is a possibility that the file might be logically inconsistent. The restarted user might have been in the middle of an update transaction that would cause multiple updates to the file. Some updates might have been made before the soft restart occurred, while other updates were not made. </p><br />
<br />
===Hard restarts===<br />
<p><br />
Hard restarts occur for severe errors during active updating operations. </p><br />
<br />
====Causes of hard restarts====<br />
<p><br />
Hard restarts can be caused by:</p><br />
<ul><br />
<li>Disk I/O errors </li><br />
<br />
<li>Table A, B, C, or D full conditions if transaction back out is not in effect</li><br />
</ul><br />
<p><br />
For a description of how these errors are handled when transaction back out is in effect, see [[Transaction back out]].<br />
If a severe error occurs, the user receives the USER RESTARTED message and is automatically logged out. The file-physically-inconsistent flag is set. </p><br />
<br />
====Effects of hard restarts====<br />
<p><br />
One hard restart can affect other users. For example:</p><br />
<ol><br />
<li>User 1 and user 2 are each updating the same non-transaction-back out file.</li><br />
<br />
<li>User 1 updates KEY fields and gets a message that Table D is full.</li><br />
<br />
<li>File-physically-inconsistent flag (X'02') is set and user 1 is restarted. </li><br />
<br />
<li>User 1 now knows that there is a problem with the file.</li><br />
<br />
<li>User 2, however, continues updating NON-KEY fields and is not notified that Table D is full. </li><br />
<br />
<li>User 2 finishes the request and closes the file without ever knowing that the file-physically-inconsistent flag was set. </li><br />
</ol><br />
<br />
===Logically inconsistent files===<br />
<p><br />
A file is logically inconsistent when an incomplete update unit is left applied to the file. For example, consider an application that generates purchase orders. </p><br />
<p><br />
Records are generated using the User Language STORE RECORD/END STORE construct and the PO number is the internal record number ($CURREC). The internal record number (PO number) is displayed on the screen along with the input items to be added to the record (through FOR RECORD NUMBER and ADD statements) when the transaction is committed.</p><br />
<p><br />
If you enter an EOJ command and <var class="product">Model&nbsp;204</var> terminates before the transaction is committed, the file is marked logically inconsistent (FISTAT X'40' is set), because an update is active and a user is waiting for terminal input.</p><br />
<br />
===Physically inconsistent files===<br />
<p><br />
If the user is waiting for disk I/O during an ADD operation, and an EOJ is issued, it is possible that some, but not all tables were updated. In this case the file is marked physically inconsistent (FISTAT X'02' is set).</p><br />
<br />
===Preventing inconsistent files===<br />
<p><br />
In the previous examples, you could prevent the file from becoming logically or physically inconsistent by bumping all users before terminating <var class="product">Model&nbsp;204</var>.</p><br />
<br />
===File manager responsibilities===<br />
<p><br />
It is the file manager's responsibility to determine which users have been affected by a file integrity problem and notify them of the status of the file. You can use the BROADCAST FILE command described in [[ Field display and message broadcast#BROADCAST command|BROADCAST command]] to do so. </p><br />
<br />
==System failure==<br />
<p><br />
When the operating system or <var class="product">Model&nbsp;204</var> crashes during an updating request, the file-physically-inconsistent flag is set. The file might or might not actually be broken, depending on whether the modified file pages were written out before the crash. There is no way to predict whether or not this happens. Even if the pages were written out, the file might be logically inconsistent, depending on the point in the processing at which the crash occurred. </p><br />
<br />
==Premature system termination==<br />
<p><br />
<var class="product">Model&nbsp;204</var> can be terminated prematurely (by operator cancellation or because of certain error conditions) while requests are still running. When <var class="product">Model&nbsp;204</var> is prematurely terminated, modified pages are not automatically written. This means that a user might have been updating and some or all updates might not appear on the file. In addition, if any other users were updating the same file shortly before termination, their updates might not appear either, even though their requests ran to completion. </p><br />
<br />
==Request cancellation==<br />
<p><br />
If a serious user error occurs during evaluation of a User Language request, the request is canceled. Examples of serious user errors are:</p><br />
<ul><br />
<li>Incorrect use of a field name variable</li><br />
<li>Including field-level security violations</li><br />
<li>Attempt to store too many values or too long a value for a preallocated field</li><br />
</ul><br />
<p><br />
Request cancellation functions in the same manner as a soft user restart. The user is notified that the request has been canceled, and the file is marked with the flag. If the file is a transaction back out file, <var class="product">Model&nbsp;204</var> cancels the request, backs out the incomplete transaction, and does not mark the file logically inconsistent. The user is notified that the transaction has been backed out. </p><br />
<br />
==Recovery methods==<br />
<p><br />
Methods for recovering from file problems are presented in the following sections.</p><br />
<br />
===Taking the necessary precautions===<br />
<p><br />
Take the following precautions to allow your site to recover from a file problem:</p><br />
<ul><br />
<li>Use the DUMP/RESTORE utility regularly to take regular backups. If a recent DUMP of the file is available, the file can be restored to its state at the time of the dump using the RESTORE command. See [[File dumping and restoring]] for more information. </li><br />
<br />
<li>Dump the files. If journaling is ordinarily active, and all subsequent file updates are available, then you can use media recovery to restore file integrity. See [[System and media recovery]] for information about using journals to recover files. </li><br />
<br />
<li>Activate checkpointing during Online processing. In the event of system crash, <var class="product">Model&nbsp;204</var> crash, or hard restart, you can use the RESTART command to roll back to the last valid checkpoint. If journaling is also active during the Online processing, you can use the Roll Forward feature to restore as many file changes as possible. These system recovery procedures are described in [[System and media recovery]].</li><br />
</ul><br />
<p class="warn"><b>Warning:</b><br />
To ensure file integrity, Rocket Software strongly recommends that you <var class="term">never</var> reset the FISTAT (file status) parameter when it is set to the file-physically-inconsistent flag until <var class="term">just before</var> you reorganize the file. However, you must reset FISTAT before you reorganize a physically inconsistent file. </p><br />
<br />
===Reloading broken files===<br />
<p><br />
When the precautions recommended above have been neglected and the file is broken, recovery still might be possible. The safest method consists of resetting FISTAT temporarily and then running the following User Language request:</p><br />
<p class="code">USE OUTFILE<br />
BEGIN<br />
ALL: FIND ALL RECORDS<br />
END FIND<br />
PRINT.LOOP: FOR EACH RECORD IN ALL<br />
PRINT '*'<br />
PRINT ALL INFORMATION<br />
END FOR<br />
END<br />
</p><br />
<p><br />
You can then use a file load program with OUTFILE to reload the file (see the discussion of file reorganization and PAI FLOD in "Using PAI FLOD for files with varying record formats". </p><br />
<br />
==Reducing integrity problems==<br />
<p><br />
In addition to procedures used by the file and system managers for backup purposes, applications can be designed to reduce file integrity problems. </p><br />
<br />
===Using COMMIT statements for manageable update units===<br />
<p><br />
Use a COMMIT statement between each logical update so that the system can set the file-physically-inconsistent flag off and write out updated file pages frequently. Also, <var class="product">Model&nbsp;204</var> can take checkpoints only between update units. Long update units can severely inhibit the taking of checkpoints. (Update units are discussed in detail in [[#Model 204 update units|Model 204 update units]].) </p><br />
<p><br />
To accomplish transaction back outs, <var class="product">Model&nbsp;204</var> maintains a transaction back out and constraint log for each active update unit, built in the system file CCATEMP. Sizable update units can greatly increase the amount of CCATEMP space used by the system. Because insufficient CCATEMP space terminates the run, commit update units frequently to minimize the CCATEMP space requirement. </p><br />
<br />
===Updates to TBO and non-TBO files in the same request===<br />
<p><br />
You can update a non-TBO file, commit it, and then update a TBO file-or reversed file order-in the same request.</p><br />
<p><br />
Requests that attempt to update TBO and non-TBO files without an intervening COMMIT will compile, but will fail during evaluation with the following message:</p><br />
<p class="code"><b></b>*** 1 CANCELLING REQUEST; M204.2771: ATTEMPT TO UPDATE TBO AND NON-TBO FILES IN THE SAME TRANSACTION<br />
</p><br />
<br />
===Designing Host Language Interface jobs===<br />
<p><br />
For Host Language Interface jobs, set the update indicator in the IFSTRT function only when updating is really occurring, and issue the IFCHKPT call at various points during a long updating program. </p><br />
<p><br />
Retrieval-only Host Language Interface threads are not included in update units. Passing data from a retrieval-only thread to an update thread can result in logical inconsistencies to the updated file during Roll Forward.<br />
To prevent these inconsistencies, start the thread as an update thread and use a retrieval-only password to open the file, thus providing share-mode enqueuing and preventing updating from this thread.<br />
The file also is prevented from being marked physically inconsistent in the event of a hard restart or system crash. See the<var class="book">Model 204 Host Language Interface Reference Manual</var> for further description.</p><br />
<br />
==Update units and transactions==<br />
<p><br />
In general data processing terms, a transaction is a sequence of operations that access a database. The order of these operations is defined by the application or the user. </p><br />
<br />
===Model 204 transaction types===<br />
<p><br />
<var class="product">Model&nbsp;204</var> recognizes the following types of transactions: </p><br />
<table><br />
<tr class="head"><br />
<th>Type</th><br />
<th>Transactions that...</th><br />
</tr><br />
<br />
<tr><br />
<td>1</td><br />
<td>Cannot update the database</td><br />
</tr><br />
<br />
<tr><br />
<td>2</td><br />
<td>Can update the database but cannot be backed out</td><br />
</tr><br />
<br />
<tr><br />
<td>3 </td><br />
<td>Can update the database and can be backed out</td><br />
</tr><br />
</table><br />
<br />
===Model 204 update units===<br />
<p><br />
In the <var class="product">Model&nbsp;204</var> environment, the term <b>update unit</b> refers to any sequence of operations that is allowed to update the database. The two types of update transactions described above, types 2 and 3, are both update units in <var class="product">Model&nbsp;204</var>: </p><br />
<ul><br />
<li>Update units that cannot be backed out (type 2) are called <b>non-backoutable update units</b>. </li><br />
<br />
<li>Update units that can be backed out (type 3), are called <b>transactions</b> or <b>backoutable update units</b>.</li><br />
</ul><br />
<br />
====Non-backoutable update units====<br />
<p><br />
The following types of updates cannot be backed out and must be part of non-backoutable update units:</p><br />
<ul><br />
<li>Updates to non-transaction-back out files</li><br />
<li>Updates resulting from file updating commands (such as RENAME field)</li><br />
<li>Host Language functions that correspond to the updates in the previous two items </li><br />
<li>Updates resulting from the EDIT subcommands END and GO</li><br />
<li>Procedure definitions </li><br />
</ul><br />
<br />
====Backoutable update units====<br />
<p><br />
Backoutable update units are User Language updates to a transaction back out file and their Host Language Interface counterparts (record or record set updating calls). These are the only types of update operations that can occur inside a <var class="product">Model&nbsp;204</var> transaction. A transaction can either be completed so that it persists in the file, or backed out so that the update is logically undone in the file. </p><br />
<p><br />
Detailed descriptions of the boundaries of User Language backoutable and non-backoutable update units are presented in the following sections, followed by a discussion of the Host Language Interface update unit boundaries.</p><br />
<br />
===Boundaries of non-backoutable update units===<br />
<p><br />
Updating commands must be in non-backoutable update units. Some updating commands end any previous active update unit, whether backoutable or not. </p><br />
<p><br />
The following updating commands always end active update units:</p><br />
<table><br />
<tr><br />
<td><var>[[INITIALIZE command|INITIALIZE]]</var></td><br />
</tr><br />
<br />
<tr><br />
<td><var>TRANSFORM</var></td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[REDEFINE command|REDEFINE FIELD]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[RENAME FIELD command|RENAME FIELD]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[DELETE command: Field|DELETE FIELD]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[CREATE command: File|CREATE FILE]]</var> or <var>[[CREATE command: Permanent group|CREATE PERM GROUP]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[EDIT command|EDIT]]</var> <i>permanent-procedure</i> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[INCREASE command|INCREASE]]</var> +++ </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[DECREASE command|DECREASE]]</var> +++ </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[FLOD command|FLOD]]</var> +++ </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[FILELOAD command|FILELOAD]]</var> +++ </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[REGENERATE command|REGENERATE]]</var> +++ </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[REORGANIZE command|REORGANIZE]]</var> +++ </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[RESTORE command|RESTORE]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[RESTOREG command|RESTOREG]]</var></td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[Z command|Z]]</var> +++ </td><br />
</tr><br />
</table><br />
<p><br />
The commands followed by +++ cannot be issued inside a procedure.</p><br />
<br />
====Updating commands that sometimes end active update units====<br />
<p><br />
Other updating commands end the previous update unit only when that update unit is a User Language update. If a command non-backoutable update unit is in progress, the following commands are included in that non-backoutable update unit: </p><br />
<table><br />
<tr><br />
<td><var>[[SECURE command: File|SECURE]]</var></td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[BROADCAST command: Sending a file message|BROADCAST FILE]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[DEFINE command|DEFINE]]</var></td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[PROCEDURE command|PROCEDURE or PROC]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[DELETE command: Procedure|DELETE PROCEDURE]]</var> or <var>[[DELETE command: Permanent group|DELETE PERM GROUP]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[RESET command|RESET]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[RENAME PROCEDURE command|RENAME PROCEDURE]]</var> +++ </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[ASSIGN command|ASSIGN]]</var></td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[DEASSIGN command|DEASSIGN]]</var></td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[DESECURE command: Overview of DESECURE|DESECURE]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[CREATEG command|CREATEG]]</var> +++ </td><br />
</tr><br />
</table><br />
<br />
====Nonupdating commands that end active update units====<br />
<p><br />
Nonupdating commands that end any previous update unit are:</p><br />
<table><br />
<tr><br />
<td><var>[[CLOSE command|CLOSE FILE]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[ALLOCATE command|ALLOCATE]]</var></td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[FREE command|FREE]]</var></td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[DUMP command|DUMP]]</var></td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[DUMPG command|DUMPG]]</var></td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[LOGOUT or LOGOFF command|LOGOUT/LOGOFF]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[DISCONNECT command|DISCONNECT]]</var></td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[EOJ command|EOJ]]</var> +++ </td><br />
</tr><br />
</table><br />
<p><br />
When a BEGIN or MORE command follows another command that does not automatically end its own update unit (for example, DEFINE), BEGIN or MORE ends the current update unit. </p><br />
<br />
====SOUL statements that end active update units or transactions====<br />
<p><br />
SOUL statements that end the current update unit or transaction are:</p><br />
<table><br />
<tr><br />
<td><var>[[Record level locking and concurrency control#COMMIT statement|COMMIT]]</var></td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[Record level locking and concurrency control#RELEASE option|COMMIT RELEASE]]</var></td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[Data recovery#Manual backout|BACKOUT]]</var></td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[Basic request structure#Beginning and ending a request|END]]</var><br />
(only when END returns the user to include level 0 or terminal command level)</td><br />
</tr><br />
</table><br />
<br />
====Other ways to end active update units====<br />
<p><br />
Other situations that end the current update unit are:</p><br />
<ul><br />
<li>Return to terminal command level</li><br />
<br />
<li>End of an application subsystem procedure, when control is transferred through the communications global variable, unless the Auto Commit option was turned off in the subsystem definition </li><br />
<br />
<li>Request cancellation</li><br />
<br />
<li>User restart </li><br />
</ul><br />
<br />
====Starting non-backoutable update units====<br />
<p><br />
Non-backoutable update units in User Language start with the first FIND statement or the first User Language statement that performs an update operation on a file that is not a transaction back out file.</p><br />
<p><br />
In a procedure, non-backoutable update units start with the first FIND statement, the first User Language statement that performs an update operation on a non-transaction back out file, or the first updating command.<br />
Each line of input to a procedure definition is treated as a separate update unit, but only one [[System and media recovery#Understanding update units|update ID]] is assigned to a single procedure definition.</p><br />
<p><br />
Update units for the EDIT command start and end when the edited procedure is copied to the <var class="product">Model&nbsp;204</var> file during the END, GO, or SAVE subcommand. </p><br />
<br />
===Boundaries of transactions===<br />
<p><br />
A transaction (backoutable update unit) begins when the first SOUL statement performing an update operation on a transaction back out file in a User Language request or a procedure is executed. </p><br />
<br />
====SOUL statements that perform update operations====<br />
<p><br />
The SOUL statements that perform update operations are: </p><br />
<table><br />
<tr><br />
<td><var>[[Data maintenance#STORE RECORD statement|STORE RECORD]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[Data maintenance#DELETE RECORD statement|DELETE RECORD]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[Data maintenance#DELETE ALL RECORDS statement|DELETE RECORDS]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[Data maintenance#FILE RECORDS statement|FILE RECORDS]]</var></td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[Data maintenance#ADD statement|ADD]]</var> <i>fieldname</i> = <i>value</i> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[Data maintenance#DELETE statement|DELETE]]</var> <i>fieldname</i> = <i>value</i></td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[Processing multiply occurring fields and field_groups#DELETE statement|DELETE EACH]]</var> <i>fieldname</i> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[Processing multiply occurring fields and field_groups#INSERT statement|INSERT]]</var> <i>fieldname</i> = <i>value</i> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[Processing multiply occurring fields and field_groups#CHANGE statement|CHANGE]]</var> <i>fieldname</i> <var>TO</var> <i>value</i></td><br />
</tr><br />
</table><br />
<p><br />
These are the only update operations that can occur inside transactions or can be backed out. A non-backoutable update unit must end before a transaction begins.</p><br />
<br />
====Commands that end active transactions====<br />
<p><br />
Commands that end an active transaction are: </p><br />
<table><br />
<tr><br />
<td>Any file updating command</td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[CHECKPOINT command|CHECKPOINT]]</var></td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[CLOSE command|CLOSE FILE]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[RESET command|RESET]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[ALLOCATE command|ALLOCATE]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[FREE command|FREE]]</var></td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[LOGOUT or LOGOFF command|LOGOUT/LOGOFF]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[DISCONNECT command|DISCONNECT]]</var> </td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[DUMP command|DUMP]]</var></td><br />
</tr><br />
<br />
<tr><br />
<td><var>[[DUMPG command|DUMPG]]</var></td><br />
</tr><br />
</table><br />
<br />
====Other events that can end active transactions====<br />
<p><br />
Other events that end a transaction are:</p><br />
<ul><br />
<li>Return to terminal command level</li><br />
<br />
<li>End of an application subsystem procedure, when control is transferred through the communications global variable, unless the Auto Commit option was turned off in the subsystem definition </li><br />
<br />
<li>Request cancellation</li><br />
<br />
<li>User restart </li><br />
</ul><br />
<p><br />
In User Language, ending a transaction does not start a new transaction. A new transaction does not start until a User Language statement performs an update operation on a transaction back out file. </p><br />
<br />
===Host Language Interface update units===<br />
<p><br />
For details about update units in the Host Language Interface environment, see [[HLI: Transactions]].</p><br />
<br />
</div> <!-- end of toc limit div --><br />
<br />
[[Category:Model 204 files]]<br />
[[Category:Recovery]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=LOGKEY_command&diff=103937LOGKEY command2017-07-25T22:58:57Z<p>Admin: link repair</p>
<hr />
<div>==Summary==<br />
<dl><br />
<dt>Privileges<br />
<dd>System manager<br />
<dt>Function<br />
<dd>Enter or changes the password table key<br />
</dl><br />
==Format==<br />
<p class="code">LOGKEY <br />
</p><br />
==Example==<br />
<p class="code">LOGKEY<br />
89.087 16:58.51, 89.220 12:34:30 DOSRV<br />
,OS7U08,DOSRV.M204.CCASTAT<br />
<b></b>*** M204.0367: ENTER TABLE KEY OR RETURN<br />
ROSEPETE<br />
</p><br />
==Usage notes==<br />
The LOGKEY command specifies or changes the password table key. This key is stored in the <var class="product">Model&nbsp;204</var> password table and serves as the key for securing files. <var class="product">Model&nbsp;204</var> supplies a default initial key, X'04CCBFEA25186954'. <var class="product">Model&nbsp;204</var> displays data about the current status of the password table as: <br />
<p class="code">yy.ddd hh:mm:ss, yy.ddd hh:mm:ss<br />
jjjjjjjj,vvvvvv,dsn<br />
</p><br />
<br />
<b>Where:</b><br />
<table> <br />
<tr><br />
<th><var> yy.ddd hh:mm:ss</var></th><br />
<td> (first) is the date and time that the table was created.</td><br />
</tr><br />
<br />
<tr><br />
<th>yy.ddd hh:mm:ss</th><br />
<td> (second) is the date and time that the table was updated.</td><br />
</tr><br />
<br />
<tr><br />
<th>jjjjjjjj</th><br />
<td> is the name of the last job that updated the table.</td><br />
</tr><br />
<br />
<tr><br />
<th><var> vvvvvv</var></th><br />
<td> is the volume serial number for the password table data set.</td><br />
</tr><br />
<br />
<tr><br />
<th><var> dsn</var></th><br />
<td> is the data set name. </td><br />
</tr><br />
<br />
</table><br />
<p>The system prompt for a new logkey takes the following form: </p><br />
<p class="code">ENTER TABLE KEY OR RETURN<br />
[newkey]<br />
</p><br />
<p>where newkey is the new password table key (1 to 8 characters). The key cannot contain blanks, commas, or colons. If a new key is not specified, the old key is preserved.</p><br />
<p>Sometimes the system manager might want to examine the status of the password table, but might not want to change the key. When <var class="product">Model&nbsp;204</var> prompts for a new key, the system manager simply presses Return.</p><br />
<p>If the system manager specifies a new key, it is written into a special field in the password table. When a secured file is opened, the password in the file's File Control Table (FCT) is checked against this stored key. The file is opened only if the password matches this key.</p><br />
<p>After a key has been changed, files secured under the old key cannot be opened unless the old key is renewed. For a discussion of secured files, refer to the <var>[[SECURE command: File|SECURE]]</var> command and to [[Model 204 security features#File security|File security]].</p><br />
<br />
[[Category: System manager commands]]<br />
[[Category:Commands]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=$ItsRemote&diff=103766$ItsRemote2017-07-17T16:39:47Z<p>Admin: Admin moved page $Itsremote to $ItsRemote without leaving a redirect: better name</p>
<hr />
<div><p>The $ITSREMOTE function (valid in PQO only) lets you determine whether a file is remote or whether a group is scattered. The return codes are: </p><br />
<table><br />
<tr class="head"><br />
<th align="right">0</th><br />
<th>the file is not remote or the group is not scattered</th><br />
</tr><br />
<tr><br />
<td align="right">1</td><br />
<td>the file is remote or the group is scattered </td><br />
</tr><br />
</table><br />
<b>Syntax</b><br />
<p>The format for the $ITSREMOTE function is:</p><br />
<p class="code">$ITSREMOTE ({[FILE] name [AT location]<br />
<br />
| [PERM | TEMP] [GROUP] name})<br />
</p><br />
<p>where name is a %variable or a literal name of the file name, file synonym or group name. You <var class="term">must</var> enter the filename in uppercase. If you specify a null for name, <var class="product">Model&nbsp;204</var> uses the file or group context at the compilation of the statement containing the $function as the default argument.</p><br />
<b>Example</b><br />
<p class="code">BEGIN<br />
%NAME IS STRING<br />
%NAME = $READ('ENTER THE FILE OR GROUP NAME')<br />
IF $ITSREMOTE(%NAME) THEN<br />
PRINT %NAME ' IS REMOTE'<br />
ELSE <br />
PRINT %NAME ' IS NOT REMOTE'<br />
END<br />
</p><br />
[[Category:SOUL $functions]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=$ItsOpen&diff=103763$ItsOpen2017-07-17T16:33:17Z<p>Admin: Admin moved page $Itsopen to $ItsOpen without leaving a redirect: better name</p>
<hr />
<div><p><br />
The <var>$Itsopen</var> function lets you determine whether a file is open. <var>$Itsopen</var> only checks files, not groups of files. The return codes are:</p><br />
<table><br />
<tr><br />
<td>0</td><br />
<td>The file is not open.</td><br />
</tr><br />
<br />
<tr><br />
<td>1</td><br />
<td>The file is open.</td><br />
</tr><br />
</table><br />
<br />
==Syntax==<br />
<p><br />
The format for the <var>$Itsopen</var> function is:</p><br />
<p class="syntax">$Itsopen({[FILE] <span class="term">name</span> [AT <span class="term">location</span>] | [PERM | TEMP] [GROUP] <span class="term">name</span>})<br />
</p><br />
<p><br />
where <var class="term">name</var> (optional) is a %variable or a literal name of the file or group. You <b>must</b> enter the filename in uppercase. A file synonym name can also be used. </p><br />
<p><br />
If you do not enter a location (specifying a null argument), <var class="product">Model&nbsp;204</var> uses the reference context (at compile time) of the statement that calls the function.</p><br />
<br />
==Example==<br />
<p class="code">Begin<br />
%file Is String Len 8<br />
%file = $read('ENTER THE FILENAME')<br />
If $itsopen(%file) Then<br />
Print %file ' IS OPEN'<br />
Else <br />
Print %file ' IS NOT OPEN'<br />
End<br />
</p><br />
<br />
==See also==<br />
<ul><br />
<li><var>[[$Context]]</var>, which returns a number to indicate whether the context is a file or group.<br />
</ul><br />
<br />
[[Category:SOUL $functions]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=$LobReserve&diff=103717$LobReserve2017-07-12T18:29:08Z<p>Admin: Admin moved page $LOBRESERVE to $LobReserve without leaving a redirect: capitalization</p>
<hr />
<div><b>Function</b><br />
<p>The $LOBRESERVE function returns the number of bytes specified in the RESERVE n BYTES clause for a STORE or ADD statement of a BINARY-LARGE-OBJECT (BLOB) or a CHARACTER-LARGE-OBJECT (CLOB). A RESERVE n BYTES clause is used when the data being stored will be changed later to a value of n bytes. </p><br />
<p>The $LOBRESERVE function takes one argument that can be a field name or a field name variable (%%variable).</p><br />
<p class="code">$LOBRESERVE(Large-Object-fieldname | %%variable)<br />
</p><br />
[[Category:SOUL $functions]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=$LobLen&diff=103716$LobLen2017-07-12T18:27:34Z<p>Admin: Admin moved page $LOBLEN to $LobLen without leaving a redirect: capitalization</p>
<hr />
<div><p><br />
The <var>$LobLen</var> function returns the length, in bytes, of a Large Object field.</p><br />
<p><br />
<b>Syntax</b></p><br />
<p class="syntax">$LobLen(<span class="term">Large-Object-fieldname</span>)<br />
</p><br />
<br />
[[Category:SOUL $functions]]</div>Adminhttps://m204wiki.rocketsoftware.com/index.php?title=MSIR.0427_save&diff=103253MSIR.0427 save2017-06-05T15:53:05Z<p>Admin: Admin moved page MSIR.0427 to MSIR.0427 save</p>
<hr />
<div>#REDIRECT [[MSIR.0427_*%3D%3DWarning:_(product)_expires_in_(n)_days%3D%3D*]]</div>Admin