m204wiki - User contributions [en]

Record level locking and concurrency control

2025-09-05T21:49:56Z

Alex: /* Release Imagine Records statement */

<div class="toclimit-3">

==Overview==

This article discusses aspects of request design related to concurrency control in a multi-user environment and presents statements and <var class="product">Model 204</var> options that can be used to ensure logical consistency.

===Illustrating a concurrent update===

A user executing a User Language request expects that the records retrieved will not be modified by another user's concurrent request until the user's own request has completed. For example, consider these two requests being run concurrently:

User 1 
BEGIN
BLUE.CARS: FIND ALL RECORDS FOR WHICH
COLOR = BLUE
END FIND
FOR EACH RECORD IN BLUE.CARS
PRINT MAKE AND COLOR
END FOR
END


User 2
BEGIN
BLUE.BUICKS: FIND ALL RECORDS FOR WHICH
MAKE = BUICK AND COLOR = BLUE
END FIND
FOR EACH RECORD IN BLUE.BUICKS
CHANGE COLOR TO RED
END FOR
END


User 1 expects only the make and the color BLUE to be printed. User 2's request must be prevented from changing User 1's records before they are printed.

==Record locking in Model 204==

Conflicts arise when one or more users are reading a file and another user attempts to update the file or when two or more users attempt to perform file maintenance on the same records retrieved from that file. The technique used by <var class="product">Model 204</var> to prevent overlapping updates is called record level locking. 

===Record locking modes===

<var class="product">Model 204</var> can lock records as a set of records or as a single record number. <var class="product">Model 204</var> performs record level locking in two modes: 
<table>
<tr class="head">
<th>Lock mode </th>
<th>Allows... </th>
</tr>

<tr>
<td>Share </td>
<td>One or more users to read a file. Any number of users can have shared control of a record or record set concurrently. </td>
</tr>

<tr>
<td>Exclusive </td>
<td>Single user to update the file. An exclusive lock is not compatible with other exclusive locks nor with any shared locks. </td>
</tr>
</table>

All records in a record set have the same locking strength: they are all locked share, or exclusive, or they are all unlocked. 

===FIND statement records===

Records located by a FIND statement, called a record set or found set, are locked based on the FIND statement specification:
<ul>
<li><var>FIND</var>

Locks the record set in share mode
</li>
<li><var>FIND AND RESERVE</var>

Locks the record set in exclusive mode 
</li>
<li><var>FIND WITHOUT LOCK</var>

Does not lock record set
</li>
</ul>

Once obtained record set locks are kept till a RELEASE or COMMIT RELEASE statement is executed or the request ends.

==Record level locking evaluation rules==

===Request compilation and evaluation===

Record-level locking is performed in the following manner. User Language requests are processed in two phases: compilation and evaluation. All requests can be compiled regardless of the operations to be performed or of other requests being compiled or evaluated at the same time. All requests are allowed to begin the evaluation stage. 

When the evaluation involves records or sets of records, <var class="product">Model 204</var> automatically ensures that operations achieves the expected results by adhering to the following set of rules. The following User Language statements generate found sets that are processed as described.

====FIND statement====

The <var>Find</var> statement immediately locks the set of records it has retrieved in share mode. If the locking is successful, none of the records in that set can be updated by another user until the entire request, including request continuation(s), has been completed or the records have been released by some form of the <var>Release</var> statement, such as <var>Release Records In</var>..., <var>Release All Records</var>, <var>Release Commit</var>.

A <var>Find</var> statement executed in a loop releases the old found set as soon as the statement is re-executed. The final set selected by the <var>Find</var> remains locked until the end of the request. An unlabeled <var>Find</var> statement, such as a <var>Find And Print Count</var> statement, does not lock records at all.

====FIND WITHOUT LOCKS statement====

The FIND WITHOUT LOCKS statement executes a FIND statement without locking any records. The found set of records is indistinguishable from a list, except that it is referenced with an IN label clause. You must use the FIND WITHOUT LOCKS statement with caution, otherwise logical inconsistencies might occur. See [[#FIND WITHOUT LOCKS statement|FIND WITHOUT LOCKS statement]] for more information.

====FOR RECORD NUMBER statement====

The FOR RECORD NUMBER statement locks the specified record in share mode, if it was not locked by the FIND statement. The lock is kept until the end of the loop or a COMMIT statement is processed. 

====DELETE ALL RECORDS IN statement====

The DELETE ALL RECORDS IN statement temporarily locks the set of records to be deleted in exclusive mode before deletion occurs. The locking does not succeed if another user has access to any of the records through a FIND or file maintenance statement. Once a record has been deleted, the exclusive lock on the record is released, because the record no longer exists in the file. 

====ADD, CHANGE, or DELETE, DELETE RECORD, and INSERT statements====

The ADD, CHANGE, DELETE fieldname, DELETE RECORD, and INSERT statements all lock the current record in exclusive mode before updating it. The exclusive single record lock remains on the current record until it passes through the loop, unless the record has been deleted. 

Upon completion of a DELETE RECORD statement the deleted record cannot cause a record locking conflict. However, it the deleting user attempts to reference the deleted record via a previously established found set or list, the following message is issued:
M204.1266: NONEXISTENT RECORD REFERENCED


====STORE RECORD statement====

The STORE RECORD statement gets a LPU record lock for the TBO files and does not get a record lock for non-TBO files.
<ul>
<li>For TBO files, an LPU record lock, which is always exclusive, is obtained, meaning unconditionally gotten, at the beginning of the STORE RECORD processing. However, other users cannot get a record locking conflict, because the record's existence bit is not turned on until STORE RECORD processing finishes. If you store a record, you automatically obtain an LPU lock and hold it until the next COMMIT statement is processed.</li>

<li>For non-TBO files, no record lock of any kind is obtained. However, the record existence bit is not turned on until STORE RECORD processing is finished, so there are no problems with protecting the record from other users during STORE RECORD processing.</li>
</ul>

====END MORE statement====

If a request ends with END MORE, records found by that request remain locked and cannot be modified by other users. If the request ends with END, all records are released as soon as execution is completed. 

===Locking conflicts===

If <var class="product">Model 204</var> cannot lock a record, a locking conflict occurs, which are discussed in detail in [[#Handling locking conflicts|Handling locking conflicts]]. 

==FIND WITHOUT LOCKS statement==

The FIND WITHOUT LOCKS statement executes a FIND statement without locking any records. The resulting found set is indistinguishable from a list, except that it is referenced with an IN label clause.

Note: The FIND WITHOUT LOCKS feature should be used only to solve specific performance problems. Before using the FIND WITHOUT LOCKS statement, please take into account the [[#FIND WITHOUT LOCKS statement|FIND WITHOUT LOCKS statement]] following [[#Responding to a record locking conflict|Responding to a record locking conflict]].

====Syntax====

The format of the FIND WITHOUT LOCKS statement is:
{FIND WITHOUT LOCKS | FDWOL} [ALL] RECORDS
[IN label | ON [LIST] listname]
[FOR WHICH | WITH] retrieval-conditions


====Usage notes====

Issues involved with using FIND WITHOUT LOCKS include:
<ul>
<li>Logical integrity of data is at risk when another user:
<ul>
<li>Is in the midst of changing values which are related</li>
<li>Changes or deletes the field which caused the record to be found</li>
</ul></li>

<li>Physical integrity error messages or snaps are generated, including:

<ul>
<li>SICK RECORD messages are sent when extension records are deleted. The record is not really sick; temporarily it appears that way to <var class="product">Model 204</var>.</li>

<li>SICK RECORD messages are sent from FOR EACH OCCURRENCE (FEO) statements when the record is modified by another user. Again, the record is not really sick.</li>

<li>NONEXISTENT RECORD messages are sent when entire records are deleted. </li>
</ul>

<li>Examples of appropriate use of the FIND WITHOUT LOCKS statement include:
<ul>
<li>When there is one user at a time per record (for example, scratch records or bank teller applications where an account is usually modified by one teller at a time)</li>

<li>Report programs in a heavy update environment </li>
</ul>

<li>Examples of inappropriate uses of the FIND WITHOUT LOCKS, which can result in snaps, include:
<ul>
<li>Report program in a heavy delete environment (results in many
NONEXISTENT RECORD messages)</li>

<li>Retrievals in which the selection criteria can be changed by other users</li>

<li>Reuse Record Number files, except possibly scratch files keyed on the user ID </li>
</ul></li>
</ul>

==Handling locking conflicts==

A typical locking situation is as follows. The first user issues a FIND statement for a large set of records and begins printing a long report. The second user issues a FIND statement for some of the same records and tries to update them with a CHANGE statement. 

===ENQRETRY parameter===

The number of times a request automatically attempts to lock a record or set of records before notifying the user of a conflict is determined by the
<var>[[ENQRETRY parameter|ENQRETRY]]</var> parameter.
Between attempts, <var class="product">Model 204</var> waits until the record or records that were held by another user are released or until three seconds pass.


Under these circumstances, the second user must decide whether to cancel the request or try again. The second user receives a message noting that the locking failed and is queried: <var>DO YOU REALLY WANT TO TRY AGAIN?</var> The second user can respond in one of three ways:
<ul>
<li>Reply <var>N</var>, thereby cancelling the request.</li>

<li>Reply <var>Y</var> and try to lock again immediately.</li>

<li>Wait a minute or two and reply <var>Y</var>. </li>
</ul>

===Responding to a record locking conflict===

In <var class="product">Model 204</var> you can specify the action to take if, an effort to lock a set of records is unsuccessful. The following statements specify the action to take in detail.
<table>
<tr class="head">
<th>ON clause</th>
<th>Can be used for...</th>
</tr>

<tr>
<td nowrap>RECORD LOCKING CONFLICT </td>
<td>Any type of conflict, including a retrieval statement conflict, that arises during a record locking attempt.</td>
</tr>

<tr>
<td>FIND CONFLICT </td>
<td>Only a conflict that arises during the evaluation of a FIND statement or a FOR EACH RECORD statement used for retrieval. </td>
</tr>
</table>

====Syntax====

The format for these ON units is: 
[label] ON {RECORD LOCKING CONFLICT | FIND CONFLICTS}


====If both types of ON units are active====

ON RECORD LOCKING CONFLICT and ON FIND CONFLICT follow the same rules as other ON units (see [[Subroutines#ON units|ON units]]). If both ON RECORD LOCKING CONFLICT and ON FIND CONFLICT are active within a request when a conflict occurs, the conflict is handled in the following manner:
<table>
<tr class="head">
<th>If the conflict results from... </th>
<th>Clause invoked...</th>
</tr>

<tr>
<td>FIND statement or FOR EACH RECORD statement used for retrieval </td>
<td>ON FIND CONFLICT</td>
</tr>

<tr>
<td>A condition other than the FIND or FOR EACH RECORD statement used for retrieval </td>
<td nowrap>ON RECORD LOCKING CONFLICT </td>
</tr>
</table>

===CLEAR ON statement===

The definition of an ON RECORD LOCKING CONFLICT or ON FIND CONFLICT unit is cleared by the following statement: 
CLEAR ON {RECORD LOCKING CONFLICT | FIND CONFLICTS}


After a CLEAR ON RECORD LOCKING CONFLICT or CLEAR ON FIND CONFLICT statement, a record locking conflict does not invoke the corresponding ON unit.

===Pause statement===

====Purpose====

You can use the <var>Pause</var> statement to cause the request to wait a specified number of seconds and then to retry the statement that caused the evaluation of the <var>ON</var> unit. 

====Syntax====

The format of the <var>Pause</var> statement is: 
{{Template:Pause statement syntax}}
Where:
<ul>
<li><var class="term">n</var> must be in the range 0-600, allowing a maximum pause of 10 minutes. </li>

<li><var class="term">%variable</var> is interpreted as a numeric value representing the number of seconds to wait. It must be in the range 0-86400. </li>
</ul>

====Usage====

The <var>Pause</var> statement is a bumpable wait.

If <var class="term">n</var> is not specified or is specified as zero, processing stops and does not continue until the user enters a carriage return. If <var class="term">n</var> is specified, processing continues automatically after <var class="term">n</var> seconds.

If <var class="term">%variable</var> takes any non-null, non-numeric value or a numeric value in the range 0-86400, the SOUL request is canceled with the message:
M204.2650: PAUSE TIME-VARIABLE NOT IN RANGE


A variable with a null or 0 value does a terminal read. For example, <code>%a='xxx'</code> is treated as if zero was specified, and a read is issued.

Note: You should generally specify small values for <var class="term">n</var> and issue a <var>Pause</var> only when no records are held by the request. If <var class="term">n</var> is large, the request can seem to be hung. 

====See also====

The <var>[[$WakeUp]]</var> function is an alternative approach; it offers millisecond resolution pausing.

===Handling Parallel Query Option/204 record locking conflicts===

If a client request cannot complete because of a record locking conflict on the server system, the server automatically tries again to lock the record or set of records. The server tries again until it succeeds or until it has tried as many times as the value of the client thread ENQRETRY parameter. The value of the ENQRETRY parameter that is specified on the server thread has no effect on the number of retries. 

If ENQRETRY attempts to lock a record or set of records do not succeed, the server notifies the client about the conflict. If an ON RECORD LOCKING or ON FIND CONFLICT unit is active, the unit is invoked. Otherwise, the client receives a message that the locking failed, followed by a prompt asking if the client wants to try again. 

If the client enters <var>N</var>, the request is canceled. If the client enters <var>Y</var>, the server repeats the locking attempt cycle, making as many as ENQRETRY attempts before prompting again. 

==Record locking and release statements==

The following statements can place a lock on a set of records or remove the lock placed on records.
Note: To remove the lock placed on record sets, you can also use the COMMIT RELEASE for of the [[#COMMIT statement|COMMIT statement]].

===FIND AND RESERVE statement===

A User Language request can lock records in exclusive mode by using the FIND AND RESERVE statement. However, because records are exclusively locked, concurrency is reduced. 

====Syntax====

The basic format of the FIND AND RESERVE statement is:
FIND AND RESERVE [ALL] RECORDS FOR WHICH


====Example====
BEGIN
ON RECORD LOCKING CONFLICT
PRINT 'RECORD LOCKING CONFLICT OCCURRED WITH ' -
WITH $RLCUSR
PRINT 'FILE ' WITH $RLCFILE
PRINT 'RECORD ' WITH $RLCREC
END ON

POL.HLDR: IN CLIENTS FIND AND RESERVE ALL RECORDS -
FOR WHICH POLICY NO = 100015
RECTYPE = POLICYHOLDER
END FIND
OWNER.POL: IN VEHICLES FIND AND RESERVE ALL RECORDS -
FOR WHICH OWNER POLICY = 100015
END FIND
FOR EACH RECORD IN OWNER.POL
%NEW.PREMIUM = VEHICLE PREMIUM + 100
CHANGE VEHICLE PREMIUM TO %NEW.PREMIUM
%TOTAL.PREMIUM = %TOTAL.PREMIUM + %NEW.PREMIUM
END FOR
FOR EACH RECORD IN POL.HLDR
CHANGE TOTAL PREMIUM TO %TOTAL.PREMIUM
END FOR
END


In the preceding example, the first FIND AND RESERVE statement prevents access to TOTAL PREMIUM while its corresponding VEHICLE PREMIUMs are being changed. 

===Release Records statement===

Records found using the <var>Find And Reserve</var> statement are held in exclusive status until the end of the request or until they are released explicitly by the user with the <var>Release Records</var> statement. The <var>Release Records</var> statement also can be used to release records from <var>Sort</var> statements or records obtained in share status by <var>Find</var> statements issued in the regular form. Records released in this manner are no longer available to the request and might have to be found again. The original found set or list from which the sorted set was built is not affected. 

Note: To avoid producing confusing results, issue a <var>Release Records</var> statement at the end of a loop and not in the middle of one, since the statement relinquishes control of a found set. 

====Syntax====

The format of the <var>Release Records</var> statement is:
{{Template:Release Records statement syntax}}

where <var class="term">label</var> is the statement label of the FIND statement that locked the records.

The <var>Release Records</var> statement is supported in remote file and scattered group contexts.

====Processing====

The <var>Release Records</var> statement removes all:
<ul>
<li>Entries from the specified found set(s), thereby removing the record set lock</li>

<li>List entries, when issued against list(s)</li>

<li>The user's single record locks.</li>
</ul>

When the <var>Release</var> statement refers to a <var>Sort</var> statement, the space occupied by the temporary sorted record copies is released.

<var>Release Records On</var> is equivalent to the <var>Clear List</var> statement. 

===Release All Records statement===

====Description====

A <var>Release All Records</var> statement terminates the lock in share mode placed on records by the <var>Find</var> statement. <var>Release All Records</var> also clears all lists and the results of all <var>Sort</var> statements, and sets the current record number to -1. 

After a <var>Release All Records</var> statement is processed in a <var>For Each Record</var> loop, subsequent references to the current record in the loop cannot find a current record. If processing returns to the top of the loop, no new record is available, and the first statement after the end of the loop is executed. 

====Syntax====

The format of this release statement is:
{{Template:Release All Records statement syntax}}

The <var>Release All Records</var> statement is supported in remote file and scattered group contexts.

===Release Imagine Records statement===

====Description====

A <var>Release Imagine Records</var> statement is exactly like a <var>Release All Records</var> statement except:

<ul>
<li>It frees all mappings of record numbers to records for [[Imagine Transparency]] files.</li>
<li>The <var>Release All Records</var> is done on all [[Daemon class#Transactional daemons|transactional daemon]] descendants.</li>
<li>It is not allowed to be invoked on a [[Daemon class#Transactional daemons|transactional daemon]].</li>
<li>It can be followed by an optional <var>Commit</var> or <var>Backout</var> keyword to indicate that a commit or backout is to be done before the rest of <var>Release All Record</var> processing.</li>
<li>If not followed by the <var>Commit</var> or <var>Backout</var> keyword, it cancels the request if in a uncommitted transaction (there are pending updates)</li>
</ul>


Outside of being a bit more concise than having a separate <var>Backout</var> statement, doing a <code>Release Imagine Records Backout</code> does not result in a <code>M204.1096: There were no updates for backout to process</code> message if there are no updates.


[[Imagine Transparency]] record numbers are thread-specific and are assigned sequentially, starting at 1, as records are found or accessed. One can the use [[Record loops#For Record Number processing|For Record Number]] statement to access the same <var>Imagine</var> record over transaction boundaries, though the record would be re-retrieved from the broker for each transaction. This is no longer possible after a <var>Release Imagine Records</var> statement is executed. On the plus side, this clears the record number to record mapping table which would, otherwise, grow indefinitely on a logged in thread. So, for long-lived threads, it is a good idea to do a <var>Release Imagine Records</var> whenever possible, to keep the mapping table small.


Unlike <var>Model 204</var> transactions, [[Imagine Transparency]] transactions include retrieval operations. An attempt to retrieve a record that has been updated after the start of the <var>Imagine</var> transaction results in a data consistency request canceling error. If this is a concern, a <var>Release Imagine Records</var> would end the current <var>Imagine</var> transaction and a new one would be started on the next <var>Imagine</var> retrieval (or update) operation. Of course, this <var>Release Imagine Records</var> statement would have other significant application impacts, so might not be a feasible solution to avoiding data consistency errors in many cases.


The <var>Release Imagine Records</var> statement, like the <var>Imagine Transparency</var> feature, is available in <var>Model 204 V8.0</var> and later.


====Syntax====

The format of this Release Imagine Records statement is:
{{Template:Release Imagine Records statement syntax}}

===RELEASE and COMMIT RELEASE statements with global foundsets and lists===

The RELEASE statements and the COMMIT RELEASE statements empty the contents of a global found set, global sort set, or global list. The label and positions associated with a found set, sort set, or the list is still considered global, but it is empty. Global positions are not cleared by RELEASE or COMMIT RELEASE statements, however, without records there is nothing to process.

==Lock pending updates==

<var class="product">Model 204</var> provides a special facility, lock pending updates, that prevents updated records in one transaction (a sequence of file updating operations) from being used by other applications until the transaction ends. Lock pending updates ensures logical consistency without requiring the use of the FIND AND RESERVE statement. LPU locks are distinct from single record locks. 

===Processing===

If the lock pending updates option is specified, records are locked in share mode by a FIND statement. The first update to a record locks the record in exclusive mode and adds it to a set of updated locked records called the pending update pool. The record is not released from this exclusive lock at the end of the FOR EACH RECORD loop. Instead, the record is locked until the end of the transaction when the entire pending update pool is released.

===Set with the FOPT parameter===

Lock pending updates is an option of the <var>[[FOPT parameter|FOPT]]</var> parameter that is enabled or disabled on a file-by-file basis.


==Commit statement==

A <var>Commit</var> statement ends the current transaction, dequeues checkpoints, and drops all LPU locks and exclusive record locks obtained by update statements (<var>[[Add statement|Add]]</var>, <var>[[Change statement|Change]]</var>, <var>[[Data maintenance#Delete statement|Delete]]</var>) for all files participating in the transaction.
The <var>Commit</var> statement does not release record locks obtained by the <var>[[Find statement (find records)|Find]]</var> statement. The share record lock obtained by the <var>[[For Record Number statement|For Record Number]]</var> statement is not released by a <var>Commit</var> statement executed inside a loop.

The <var>Commit</var> statement is supported in remote context. If records on any remote nodes are updated, the <var>Commit</var> statement saves all remote updates on all remote nodes. Also, remote updates are committed automatically by the system when appropriate.

====Syntax====
{{Template:Commit statement syntax}}

====Example====
begin
get.rec: find all records for which
lname = 'NELSON'
end find
for each record in get.rec
add month = 'nov'
commit
print fname and lname and each month
end for
name.ct: count records in get.rec
print count in name.ct and 'records updated'
end


===Release option===

The <var>Release</var> option of the <var>Commit</var> statement performs all the operations of the <var>Commit</var> and <var>[[Release All Records statement|Release All Records]]</var> statements:
<table>
<tr class="head">
<th nowrap>After processing a 
Commit Release
statement ... </th>
<th valign="bottom">Any subsequent reference to the current...</th>
</tr>

<tr>
<td nowrap><var>[[For Each Record statement|For Each Record]]</var> loop </td>
<td>Record in the loop cannot find a current record. If processing returns to the top of the loop, no new record is available; the first statement after the end of each loop is executed.</td>
</tr>

<tr>
<td><var>[[For Each Value statement|For Each Value]]</var> loop </td>
<td>Value still obtains the last value processed. </td>
</tr>
</table>

====Usage====

To avoid confusing results, it is recommended that <var>Commit Release</var> be issued at the end of a loop and not in the middle of one.

===Release and Commit Release statements with global foundsets and lists===

The <var>Release</var> statement and the <var>Commit Release</var> statement both empty the contents of a global found set, global sort set, or global list. The label and positions associated with a found set, sort set, or the list is still considered global, but it is empty. Global positions are not cleared by <var>Release</var> or <var>Commit Release</var> statements, however, without records there is nothing to process. 

</div> 

[[Category:SOUL]]

Record level locking and concurrency control

2025-09-05T20:41:54Z

Alex: /* Release Imagine Records statement */

<div class="toclimit-3">

==Overview==

This article discusses aspects of request design related to concurrency control in a multi-user environment and presents statements and <var class="product">Model 204</var> options that can be used to ensure logical consistency.

===Illustrating a concurrent update===

A user executing a User Language request expects that the records retrieved will not be modified by another user's concurrent request until the user's own request has completed. For example, consider these two requests being run concurrently:

User 1 
BEGIN
BLUE.CARS: FIND ALL RECORDS FOR WHICH
COLOR = BLUE
END FIND
FOR EACH RECORD IN BLUE.CARS
PRINT MAKE AND COLOR
END FOR
END


User 2
BEGIN
BLUE.BUICKS: FIND ALL RECORDS FOR WHICH
MAKE = BUICK AND COLOR = BLUE
END FIND
FOR EACH RECORD IN BLUE.BUICKS
CHANGE COLOR TO RED
END FOR
END


User 1 expects only the make and the color BLUE to be printed. User 2's request must be prevented from changing User 1's records before they are printed.

==Record locking in Model 204==

Conflicts arise when one or more users are reading a file and another user attempts to update the file or when two or more users attempt to perform file maintenance on the same records retrieved from that file. The technique used by <var class="product">Model 204</var> to prevent overlapping updates is called record level locking. 

===Record locking modes===

<var class="product">Model 204</var> can lock records as a set of records or as a single record number. <var class="product">Model 204</var> performs record level locking in two modes: 
<table>
<tr class="head">
<th>Lock mode </th>
<th>Allows... </th>
</tr>

<tr>
<td>Share </td>
<td>One or more users to read a file. Any number of users can have shared control of a record or record set concurrently. </td>
</tr>

<tr>
<td>Exclusive </td>
<td>Single user to update the file. An exclusive lock is not compatible with other exclusive locks nor with any shared locks. </td>
</tr>
</table>

All records in a record set have the same locking strength: they are all locked share, or exclusive, or they are all unlocked. 

===FIND statement records===

Records located by a FIND statement, called a record set or found set, are locked based on the FIND statement specification:
<ul>
<li><var>FIND</var>

Locks the record set in share mode
</li>
<li><var>FIND AND RESERVE</var>

Locks the record set in exclusive mode 
</li>
<li><var>FIND WITHOUT LOCK</var>

Does not lock record set
</li>
</ul>

Once obtained record set locks are kept till a RELEASE or COMMIT RELEASE statement is executed or the request ends.

==Record level locking evaluation rules==

===Request compilation and evaluation===

Record-level locking is performed in the following manner. User Language requests are processed in two phases: compilation and evaluation. All requests can be compiled regardless of the operations to be performed or of other requests being compiled or evaluated at the same time. All requests are allowed to begin the evaluation stage. 

When the evaluation involves records or sets of records, <var class="product">Model 204</var> automatically ensures that operations achieves the expected results by adhering to the following set of rules. The following User Language statements generate found sets that are processed as described.

====FIND statement====

The <var>Find</var> statement immediately locks the set of records it has retrieved in share mode. If the locking is successful, none of the records in that set can be updated by another user until the entire request, including request continuation(s), has been completed or the records have been released by some form of the <var>Release</var> statement, such as <var>Release Records In</var>..., <var>Release All Records</var>, <var>Release Commit</var>.

A <var>Find</var> statement executed in a loop releases the old found set as soon as the statement is re-executed. The final set selected by the <var>Find</var> remains locked until the end of the request. An unlabeled <var>Find</var> statement, such as a <var>Find And Print Count</var> statement, does not lock records at all.

====FIND WITHOUT LOCKS statement====

The FIND WITHOUT LOCKS statement executes a FIND statement without locking any records. The found set of records is indistinguishable from a list, except that it is referenced with an IN label clause. You must use the FIND WITHOUT LOCKS statement with caution, otherwise logical inconsistencies might occur. See [[#FIND WITHOUT LOCKS statement|FIND WITHOUT LOCKS statement]] for more information.

====FOR RECORD NUMBER statement====

The FOR RECORD NUMBER statement locks the specified record in share mode, if it was not locked by the FIND statement. The lock is kept until the end of the loop or a COMMIT statement is processed. 

====DELETE ALL RECORDS IN statement====

The DELETE ALL RECORDS IN statement temporarily locks the set of records to be deleted in exclusive mode before deletion occurs. The locking does not succeed if another user has access to any of the records through a FIND or file maintenance statement. Once a record has been deleted, the exclusive lock on the record is released, because the record no longer exists in the file. 

====ADD, CHANGE, or DELETE, DELETE RECORD, and INSERT statements====

The ADD, CHANGE, DELETE fieldname, DELETE RECORD, and INSERT statements all lock the current record in exclusive mode before updating it. The exclusive single record lock remains on the current record until it passes through the loop, unless the record has been deleted. 

Upon completion of a DELETE RECORD statement the deleted record cannot cause a record locking conflict. However, it the deleting user attempts to reference the deleted record via a previously established found set or list, the following message is issued:
M204.1266: NONEXISTENT RECORD REFERENCED


====STORE RECORD statement====

The STORE RECORD statement gets a LPU record lock for the TBO files and does not get a record lock for non-TBO files.
<ul>
<li>For TBO files, an LPU record lock, which is always exclusive, is obtained, meaning unconditionally gotten, at the beginning of the STORE RECORD processing. However, other users cannot get a record locking conflict, because the record's existence bit is not turned on until STORE RECORD processing finishes. If you store a record, you automatically obtain an LPU lock and hold it until the next COMMIT statement is processed.</li>

<li>For non-TBO files, no record lock of any kind is obtained. However, the record existence bit is not turned on until STORE RECORD processing is finished, so there are no problems with protecting the record from other users during STORE RECORD processing.</li>
</ul>

====END MORE statement====

If a request ends with END MORE, records found by that request remain locked and cannot be modified by other users. If the request ends with END, all records are released as soon as execution is completed. 

===Locking conflicts===

If <var class="product">Model 204</var> cannot lock a record, a locking conflict occurs, which are discussed in detail in [[#Handling locking conflicts|Handling locking conflicts]]. 

==FIND WITHOUT LOCKS statement==

The FIND WITHOUT LOCKS statement executes a FIND statement without locking any records. The resulting found set is indistinguishable from a list, except that it is referenced with an IN label clause.

Note: The FIND WITHOUT LOCKS feature should be used only to solve specific performance problems. Before using the FIND WITHOUT LOCKS statement, please take into account the [[#FIND WITHOUT LOCKS statement|FIND WITHOUT LOCKS statement]] following [[#Responding to a record locking conflict|Responding to a record locking conflict]].

====Syntax====

The format of the FIND WITHOUT LOCKS statement is:
{FIND WITHOUT LOCKS | FDWOL} [ALL] RECORDS
[IN label | ON [LIST] listname]
[FOR WHICH | WITH] retrieval-conditions


====Usage notes====

Issues involved with using FIND WITHOUT LOCKS include:
<ul>
<li>Logical integrity of data is at risk when another user:
<ul>
<li>Is in the midst of changing values which are related</li>
<li>Changes or deletes the field which caused the record to be found</li>
</ul></li>

<li>Physical integrity error messages or snaps are generated, including:

<ul>
<li>SICK RECORD messages are sent when extension records are deleted. The record is not really sick; temporarily it appears that way to <var class="product">Model 204</var>.</li>

<li>SICK RECORD messages are sent from FOR EACH OCCURRENCE (FEO) statements when the record is modified by another user. Again, the record is not really sick.</li>

<li>NONEXISTENT RECORD messages are sent when entire records are deleted. </li>
</ul>

<li>Examples of appropriate use of the FIND WITHOUT LOCKS statement include:
<ul>
<li>When there is one user at a time per record (for example, scratch records or bank teller applications where an account is usually modified by one teller at a time)</li>

<li>Report programs in a heavy update environment </li>
</ul>

<li>Examples of inappropriate uses of the FIND WITHOUT LOCKS, which can result in snaps, include:
<ul>
<li>Report program in a heavy delete environment (results in many
NONEXISTENT RECORD messages)</li>

<li>Retrievals in which the selection criteria can be changed by other users</li>

<li>Reuse Record Number files, except possibly scratch files keyed on the user ID </li>
</ul></li>
</ul>

==Handling locking conflicts==

A typical locking situation is as follows. The first user issues a FIND statement for a large set of records and begins printing a long report. The second user issues a FIND statement for some of the same records and tries to update them with a CHANGE statement. 

===ENQRETRY parameter===

The number of times a request automatically attempts to lock a record or set of records before notifying the user of a conflict is determined by the
<var>[[ENQRETRY parameter|ENQRETRY]]</var> parameter.
Between attempts, <var class="product">Model 204</var> waits until the record or records that were held by another user are released or until three seconds pass.


Under these circumstances, the second user must decide whether to cancel the request or try again. The second user receives a message noting that the locking failed and is queried: <var>DO YOU REALLY WANT TO TRY AGAIN?</var> The second user can respond in one of three ways:
<ul>
<li>Reply <var>N</var>, thereby cancelling the request.</li>

<li>Reply <var>Y</var> and try to lock again immediately.</li>

<li>Wait a minute or two and reply <var>Y</var>. </li>
</ul>

===Responding to a record locking conflict===

In <var class="product">Model 204</var> you can specify the action to take if, an effort to lock a set of records is unsuccessful. The following statements specify the action to take in detail.
<table>
<tr class="head">
<th>ON clause</th>
<th>Can be used for...</th>
</tr>

<tr>
<td nowrap>RECORD LOCKING CONFLICT </td>
<td>Any type of conflict, including a retrieval statement conflict, that arises during a record locking attempt.</td>
</tr>

<tr>
<td>FIND CONFLICT </td>
<td>Only a conflict that arises during the evaluation of a FIND statement or a FOR EACH RECORD statement used for retrieval. </td>
</tr>
</table>

====Syntax====

The format for these ON units is: 
[label] ON {RECORD LOCKING CONFLICT | FIND CONFLICTS}


====If both types of ON units are active====

ON RECORD LOCKING CONFLICT and ON FIND CONFLICT follow the same rules as other ON units (see [[Subroutines#ON units|ON units]]). If both ON RECORD LOCKING CONFLICT and ON FIND CONFLICT are active within a request when a conflict occurs, the conflict is handled in the following manner:
<table>
<tr class="head">
<th>If the conflict results from... </th>
<th>Clause invoked...</th>
</tr>

<tr>
<td>FIND statement or FOR EACH RECORD statement used for retrieval </td>
<td>ON FIND CONFLICT</td>
</tr>

<tr>
<td>A condition other than the FIND or FOR EACH RECORD statement used for retrieval </td>
<td nowrap>ON RECORD LOCKING CONFLICT </td>
</tr>
</table>

===CLEAR ON statement===

The definition of an ON RECORD LOCKING CONFLICT or ON FIND CONFLICT unit is cleared by the following statement: 
CLEAR ON {RECORD LOCKING CONFLICT | FIND CONFLICTS}


After a CLEAR ON RECORD LOCKING CONFLICT or CLEAR ON FIND CONFLICT statement, a record locking conflict does not invoke the corresponding ON unit.

===Pause statement===

====Purpose====

You can use the <var>Pause</var> statement to cause the request to wait a specified number of seconds and then to retry the statement that caused the evaluation of the <var>ON</var> unit. 

====Syntax====

The format of the <var>Pause</var> statement is: 
{{Template:Pause statement syntax}}
Where:
<ul>
<li><var class="term">n</var> must be in the range 0-600, allowing a maximum pause of 10 minutes. </li>

<li><var class="term">%variable</var> is interpreted as a numeric value representing the number of seconds to wait. It must be in the range 0-86400. </li>
</ul>

====Usage====

The <var>Pause</var> statement is a bumpable wait.

If <var class="term">n</var> is not specified or is specified as zero, processing stops and does not continue until the user enters a carriage return. If <var class="term">n</var> is specified, processing continues automatically after <var class="term">n</var> seconds.

If <var class="term">%variable</var> takes any non-null, non-numeric value or a numeric value in the range 0-86400, the SOUL request is canceled with the message:
M204.2650: PAUSE TIME-VARIABLE NOT IN RANGE


A variable with a null or 0 value does a terminal read. For example, <code>%a='xxx'</code> is treated as if zero was specified, and a read is issued.

Note: You should generally specify small values for <var class="term">n</var> and issue a <var>Pause</var> only when no records are held by the request. If <var class="term">n</var> is large, the request can seem to be hung. 

====See also====

The <var>[[$WakeUp]]</var> function is an alternative approach; it offers millisecond resolution pausing.

===Handling Parallel Query Option/204 record locking conflicts===

If a client request cannot complete because of a record locking conflict on the server system, the server automatically tries again to lock the record or set of records. The server tries again until it succeeds or until it has tried as many times as the value of the client thread ENQRETRY parameter. The value of the ENQRETRY parameter that is specified on the server thread has no effect on the number of retries. 

If ENQRETRY attempts to lock a record or set of records do not succeed, the server notifies the client about the conflict. If an ON RECORD LOCKING or ON FIND CONFLICT unit is active, the unit is invoked. Otherwise, the client receives a message that the locking failed, followed by a prompt asking if the client wants to try again. 

If the client enters <var>N</var>, the request is canceled. If the client enters <var>Y</var>, the server repeats the locking attempt cycle, making as many as ENQRETRY attempts before prompting again. 

==Record locking and release statements==

The following statements can place a lock on a set of records or remove the lock placed on records.
Note: To remove the lock placed on record sets, you can also use the COMMIT RELEASE for of the [[#COMMIT statement|COMMIT statement]].

===FIND AND RESERVE statement===

A User Language request can lock records in exclusive mode by using the FIND AND RESERVE statement. However, because records are exclusively locked, concurrency is reduced. 

====Syntax====

The basic format of the FIND AND RESERVE statement is:
FIND AND RESERVE [ALL] RECORDS FOR WHICH


====Example====
BEGIN
ON RECORD LOCKING CONFLICT
PRINT 'RECORD LOCKING CONFLICT OCCURRED WITH ' -
WITH $RLCUSR
PRINT 'FILE ' WITH $RLCFILE
PRINT 'RECORD ' WITH $RLCREC
END ON

POL.HLDR: IN CLIENTS FIND AND RESERVE ALL RECORDS -
FOR WHICH POLICY NO = 100015
RECTYPE = POLICYHOLDER
END FIND
OWNER.POL: IN VEHICLES FIND AND RESERVE ALL RECORDS -
FOR WHICH OWNER POLICY = 100015
END FIND
FOR EACH RECORD IN OWNER.POL
%NEW.PREMIUM = VEHICLE PREMIUM + 100
CHANGE VEHICLE PREMIUM TO %NEW.PREMIUM
%TOTAL.PREMIUM = %TOTAL.PREMIUM + %NEW.PREMIUM
END FOR
FOR EACH RECORD IN POL.HLDR
CHANGE TOTAL PREMIUM TO %TOTAL.PREMIUM
END FOR
END


In the preceding example, the first FIND AND RESERVE statement prevents access to TOTAL PREMIUM while its corresponding VEHICLE PREMIUMs are being changed. 

===Release Records statement===

Records found using the <var>Find And Reserve</var> statement are held in exclusive status until the end of the request or until they are released explicitly by the user with the <var>Release Records</var> statement. The <var>Release Records</var> statement also can be used to release records from <var>Sort</var> statements or records obtained in share status by <var>Find</var> statements issued in the regular form. Records released in this manner are no longer available to the request and might have to be found again. The original found set or list from which the sorted set was built is not affected. 

Note: To avoid producing confusing results, issue a <var>Release Records</var> statement at the end of a loop and not in the middle of one, since the statement relinquishes control of a found set. 

====Syntax====

The format of the <var>Release Records</var> statement is:
{{Template:Release Records statement syntax}}

where <var class="term">label</var> is the statement label of the FIND statement that locked the records.

The <var>Release Records</var> statement is supported in remote file and scattered group contexts.

====Processing====

The <var>Release Records</var> statement removes all:
<ul>
<li>Entries from the specified found set(s), thereby removing the record set lock</li>

<li>List entries, when issued against list(s)</li>

<li>The user's single record locks.</li>
</ul>

When the <var>Release</var> statement refers to a <var>Sort</var> statement, the space occupied by the temporary sorted record copies is released.

<var>Release Records On</var> is equivalent to the <var>Clear List</var> statement. 

===Release All Records statement===

====Description====

A <var>Release All Records</var> statement terminates the lock in share mode placed on records by the <var>Find</var> statement. <var>Release All Records</var> also clears all lists and the results of all <var>Sort</var> statements, and sets the current record number to -1. 

After a <var>Release All Records</var> statement is processed in a <var>For Each Record</var> loop, subsequent references to the current record in the loop cannot find a current record. If processing returns to the top of the loop, no new record is available, and the first statement after the end of the loop is executed. 

====Syntax====

The format of this release statement is:
{{Template:Release All Records statement syntax}}

The <var>Release All Records</var> statement is supported in remote file and scattered group contexts.

===Release Imagine Records statement===

====Description====

A <var>Release Imagine Records</var> statement is exactly like a <var>Release All Records</var> statement except:

<ul>
<li>It frees all mappings of record numbers to records for [[Imagine Transparency]] files.</li>
<li>The <var>Release All Records</var> is done on all [[Daemon class#Transactional daemons|transactional daemon]] descendants.</li>
<li>It is not allowed to be invoked on a [[Daemon class#Transactional daemons|transactional daemon]].</li>
<li>It can be followed by an optional <var>Commit</var> or <var>Backout</var> keyword to indicate that a commit or backout is to be done before the rest of <var>Release All Record</var> processing.</li>
<li>If not followed by the <var>Commit</var> or <var>Backout</var> keyword, it cancels the request if in a uncommitted transaction (there are pending updates)</li>
</ul>


Outside of being a bit more concise than having a separate <var>Backout</var> statement, doing a <code>Release Imagine Records Backout</code> does not result in a <code>M204.1096: There were no updates for backout to process</code> message if there are no updates.


[[Imagine Transparency]] record numbers are thread-specific and are assigned sequentially, starting at 1, as records are found or accessed. One can the use [[Record loops#For Record Number processing|For Record Number]] statement to access the same <var>Imagine</var> record over transaction boundaries, though the record would be re-retrieved from the broker for each transaction. This is no longer possible after a <var>Release Imagine Records</var> statement is executed. On the plus side, this clears the record number to record mapping table which would, otherwise, grow indefinitely on a logged in thread. So, for long-lived threads, it is a good idea to do a <var>Release Imagine Records</var> whenever possible, to keep the mapping table small.


Unlike <var>Model 204</var> transactions, [[Imagine Transparency]] transactions include retrieval operations. An attempt to retrieve a record that has been updated after the start of the <var>Imagine</var> transaction results in a data consistency request canceling error. If this is a concern, a <var>Release Imagine Records</var> would end the current <var>Imagine</var> transaction and a new one would be started on the next <var>Imagine</var> retrieval (or update) operation. Of course, this <var>Release Imagine Records</var> statement would have other significant application impacts, so might not be a feasible solution to avoiding data consistency errors in many cases.


====Syntax====

The format of this Release Imagine Records statement is:
{{Template:Release Imagine Records statement syntax}}

===RELEASE and COMMIT RELEASE statements with global foundsets and lists===

The RELEASE statements and the COMMIT RELEASE statements empty the contents of a global found set, global sort set, or global list. The label and positions associated with a found set, sort set, or the list is still considered global, but it is empty. Global positions are not cleared by RELEASE or COMMIT RELEASE statements, however, without records there is nothing to process.

==Lock pending updates==

<var class="product">Model 204</var> provides a special facility, lock pending updates, that prevents updated records in one transaction (a sequence of file updating operations) from being used by other applications until the transaction ends. Lock pending updates ensures logical consistency without requiring the use of the FIND AND RESERVE statement. LPU locks are distinct from single record locks. 

===Processing===

If the lock pending updates option is specified, records are locked in share mode by a FIND statement. The first update to a record locks the record in exclusive mode and adds it to a set of updated locked records called the pending update pool. The record is not released from this exclusive lock at the end of the FOR EACH RECORD loop. Instead, the record is locked until the end of the transaction when the entire pending update pool is released.

===Set with the FOPT parameter===

Lock pending updates is an option of the <var>[[FOPT parameter|FOPT]]</var> parameter that is enabled or disabled on a file-by-file basis.


==Commit statement==

A <var>Commit</var> statement ends the current transaction, dequeues checkpoints, and drops all LPU locks and exclusive record locks obtained by update statements (<var>[[Add statement|Add]]</var>, <var>[[Change statement|Change]]</var>, <var>[[Data maintenance#Delete statement|Delete]]</var>) for all files participating in the transaction.
The <var>Commit</var> statement does not release record locks obtained by the <var>[[Find statement (find records)|Find]]</var> statement. The share record lock obtained by the <var>[[For Record Number statement|For Record Number]]</var> statement is not released by a <var>Commit</var> statement executed inside a loop.

The <var>Commit</var> statement is supported in remote context. If records on any remote nodes are updated, the <var>Commit</var> statement saves all remote updates on all remote nodes. Also, remote updates are committed automatically by the system when appropriate.

====Syntax====
{{Template:Commit statement syntax}}

====Example====
begin
get.rec: find all records for which
lname = 'NELSON'
end find
for each record in get.rec
add month = 'nov'
commit
print fname and lname and each month
end for
name.ct: count records in get.rec
print count in name.ct and 'records updated'
end


===Release option===

The <var>Release</var> option of the <var>Commit</var> statement performs all the operations of the <var>Commit</var> and <var>[[Release All Records statement|Release All Records]]</var> statements:
<table>
<tr class="head">
<th nowrap>After processing a 
Commit Release
statement ... </th>
<th valign="bottom">Any subsequent reference to the current...</th>
</tr>

<tr>
<td nowrap><var>[[For Each Record statement|For Each Record]]</var> loop </td>
<td>Record in the loop cannot find a current record. If processing returns to the top of the loop, no new record is available; the first statement after the end of each loop is executed.</td>
</tr>

<tr>
<td><var>[[For Each Value statement|For Each Value]]</var> loop </td>
<td>Value still obtains the last value processed. </td>
</tr>
</table>

====Usage====

To avoid confusing results, it is recommended that <var>Commit Release</var> be issued at the end of a loop and not in the middle of one.

===Release and Commit Release statements with global foundsets and lists===

The <var>Release</var> statement and the <var>Commit Release</var> statement both empty the contents of a global found set, global sort set, or global list. The label and positions associated with a found set, sort set, or the list is still considered global, but it is empty. Global positions are not cleared by <var>Release</var> or <var>Commit Release</var> statements, however, without records there is nothing to process. 

</div> 

[[Category:SOUL]]

Record level locking and concurrency control

2025-09-05T20:21:34Z

Alex: /* Release Imagine Records statement */

<div class="toclimit-3">

==Overview==

This article discusses aspects of request design related to concurrency control in a multi-user environment and presents statements and <var class="product">Model 204</var> options that can be used to ensure logical consistency.

===Illustrating a concurrent update===

A user executing a User Language request expects that the records retrieved will not be modified by another user's concurrent request until the user's own request has completed. For example, consider these two requests being run concurrently:

User 1 
BEGIN
BLUE.CARS: FIND ALL RECORDS FOR WHICH
COLOR = BLUE
END FIND
FOR EACH RECORD IN BLUE.CARS
PRINT MAKE AND COLOR
END FOR
END


User 2
BEGIN
BLUE.BUICKS: FIND ALL RECORDS FOR WHICH
MAKE = BUICK AND COLOR = BLUE
END FIND
FOR EACH RECORD IN BLUE.BUICKS
CHANGE COLOR TO RED
END FOR
END


User 1 expects only the make and the color BLUE to be printed. User 2's request must be prevented from changing User 1's records before they are printed.

==Record locking in Model 204==

Conflicts arise when one or more users are reading a file and another user attempts to update the file or when two or more users attempt to perform file maintenance on the same records retrieved from that file. The technique used by <var class="product">Model 204</var> to prevent overlapping updates is called record level locking. 

===Record locking modes===

<var class="product">Model 204</var> can lock records as a set of records or as a single record number. <var class="product">Model 204</var> performs record level locking in two modes: 
<table>
<tr class="head">
<th>Lock mode </th>
<th>Allows... </th>
</tr>

<tr>
<td>Share </td>
<td>One or more users to read a file. Any number of users can have shared control of a record or record set concurrently. </td>
</tr>

<tr>
<td>Exclusive </td>
<td>Single user to update the file. An exclusive lock is not compatible with other exclusive locks nor with any shared locks. </td>
</tr>
</table>

All records in a record set have the same locking strength: they are all locked share, or exclusive, or they are all unlocked. 

===FIND statement records===

Records located by a FIND statement, called a record set or found set, are locked based on the FIND statement specification:
<ul>
<li><var>FIND</var>

Locks the record set in share mode
</li>
<li><var>FIND AND RESERVE</var>

Locks the record set in exclusive mode 
</li>
<li><var>FIND WITHOUT LOCK</var>

Does not lock record set
</li>
</ul>

Once obtained record set locks are kept till a RELEASE or COMMIT RELEASE statement is executed or the request ends.

==Record level locking evaluation rules==

===Request compilation and evaluation===

Record-level locking is performed in the following manner. User Language requests are processed in two phases: compilation and evaluation. All requests can be compiled regardless of the operations to be performed or of other requests being compiled or evaluated at the same time. All requests are allowed to begin the evaluation stage. 

When the evaluation involves records or sets of records, <var class="product">Model 204</var> automatically ensures that operations achieves the expected results by adhering to the following set of rules. The following User Language statements generate found sets that are processed as described.

====FIND statement====

The <var>Find</var> statement immediately locks the set of records it has retrieved in share mode. If the locking is successful, none of the records in that set can be updated by another user until the entire request, including request continuation(s), has been completed or the records have been released by some form of the <var>Release</var> statement, such as <var>Release Records In</var>..., <var>Release All Records</var>, <var>Release Commit</var>.

A <var>Find</var> statement executed in a loop releases the old found set as soon as the statement is re-executed. The final set selected by the <var>Find</var> remains locked until the end of the request. An unlabeled <var>Find</var> statement, such as a <var>Find And Print Count</var> statement, does not lock records at all.

====FIND WITHOUT LOCKS statement====

The FIND WITHOUT LOCKS statement executes a FIND statement without locking any records. The found set of records is indistinguishable from a list, except that it is referenced with an IN label clause. You must use the FIND WITHOUT LOCKS statement with caution, otherwise logical inconsistencies might occur. See [[#FIND WITHOUT LOCKS statement|FIND WITHOUT LOCKS statement]] for more information.

====FOR RECORD NUMBER statement====

The FOR RECORD NUMBER statement locks the specified record in share mode, if it was not locked by the FIND statement. The lock is kept until the end of the loop or a COMMIT statement is processed. 

====DELETE ALL RECORDS IN statement====

The DELETE ALL RECORDS IN statement temporarily locks the set of records to be deleted in exclusive mode before deletion occurs. The locking does not succeed if another user has access to any of the records through a FIND or file maintenance statement. Once a record has been deleted, the exclusive lock on the record is released, because the record no longer exists in the file. 

====ADD, CHANGE, or DELETE, DELETE RECORD, and INSERT statements====

The ADD, CHANGE, DELETE fieldname, DELETE RECORD, and INSERT statements all lock the current record in exclusive mode before updating it. The exclusive single record lock remains on the current record until it passes through the loop, unless the record has been deleted. 

Upon completion of a DELETE RECORD statement the deleted record cannot cause a record locking conflict. However, it the deleting user attempts to reference the deleted record via a previously established found set or list, the following message is issued:
M204.1266: NONEXISTENT RECORD REFERENCED


====STORE RECORD statement====

The STORE RECORD statement gets a LPU record lock for the TBO files and does not get a record lock for non-TBO files.
<ul>
<li>For TBO files, an LPU record lock, which is always exclusive, is obtained, meaning unconditionally gotten, at the beginning of the STORE RECORD processing. However, other users cannot get a record locking conflict, because the record's existence bit is not turned on until STORE RECORD processing finishes. If you store a record, you automatically obtain an LPU lock and hold it until the next COMMIT statement is processed.</li>

<li>For non-TBO files, no record lock of any kind is obtained. However, the record existence bit is not turned on until STORE RECORD processing is finished, so there are no problems with protecting the record from other users during STORE RECORD processing.</li>
</ul>

====END MORE statement====

If a request ends with END MORE, records found by that request remain locked and cannot be modified by other users. If the request ends with END, all records are released as soon as execution is completed. 

===Locking conflicts===

If <var class="product">Model 204</var> cannot lock a record, a locking conflict occurs, which are discussed in detail in [[#Handling locking conflicts|Handling locking conflicts]]. 

==FIND WITHOUT LOCKS statement==

The FIND WITHOUT LOCKS statement executes a FIND statement without locking any records. The resulting found set is indistinguishable from a list, except that it is referenced with an IN label clause.

Note: The FIND WITHOUT LOCKS feature should be used only to solve specific performance problems. Before using the FIND WITHOUT LOCKS statement, please take into account the [[#FIND WITHOUT LOCKS statement|FIND WITHOUT LOCKS statement]] following [[#Responding to a record locking conflict|Responding to a record locking conflict]].

====Syntax====

The format of the FIND WITHOUT LOCKS statement is:
{FIND WITHOUT LOCKS | FDWOL} [ALL] RECORDS
[IN label | ON [LIST] listname]
[FOR WHICH | WITH] retrieval-conditions


====Usage notes====

Issues involved with using FIND WITHOUT LOCKS include:
<ul>
<li>Logical integrity of data is at risk when another user:
<ul>
<li>Is in the midst of changing values which are related</li>
<li>Changes or deletes the field which caused the record to be found</li>
</ul></li>

<li>Physical integrity error messages or snaps are generated, including:

<ul>
<li>SICK RECORD messages are sent when extension records are deleted. The record is not really sick; temporarily it appears that way to <var class="product">Model 204</var>.</li>

<li>SICK RECORD messages are sent from FOR EACH OCCURRENCE (FEO) statements when the record is modified by another user. Again, the record is not really sick.</li>

<li>NONEXISTENT RECORD messages are sent when entire records are deleted. </li>
</ul>

<li>Examples of appropriate use of the FIND WITHOUT LOCKS statement include:
<ul>
<li>When there is one user at a time per record (for example, scratch records or bank teller applications where an account is usually modified by one teller at a time)</li>

<li>Report programs in a heavy update environment </li>
</ul>

<li>Examples of inappropriate uses of the FIND WITHOUT LOCKS, which can result in snaps, include:
<ul>
<li>Report program in a heavy delete environment (results in many
NONEXISTENT RECORD messages)</li>

<li>Retrievals in which the selection criteria can be changed by other users</li>

<li>Reuse Record Number files, except possibly scratch files keyed on the user ID </li>
</ul></li>
</ul>

==Handling locking conflicts==

A typical locking situation is as follows. The first user issues a FIND statement for a large set of records and begins printing a long report. The second user issues a FIND statement for some of the same records and tries to update them with a CHANGE statement. 

===ENQRETRY parameter===

The number of times a request automatically attempts to lock a record or set of records before notifying the user of a conflict is determined by the
<var>[[ENQRETRY parameter|ENQRETRY]]</var> parameter.
Between attempts, <var class="product">Model 204</var> waits until the record or records that were held by another user are released or until three seconds pass.


Under these circumstances, the second user must decide whether to cancel the request or try again. The second user receives a message noting that the locking failed and is queried: <var>DO YOU REALLY WANT TO TRY AGAIN?</var> The second user can respond in one of three ways:
<ul>
<li>Reply <var>N</var>, thereby cancelling the request.</li>

<li>Reply <var>Y</var> and try to lock again immediately.</li>

<li>Wait a minute or two and reply <var>Y</var>. </li>
</ul>

===Responding to a record locking conflict===

In <var class="product">Model 204</var> you can specify the action to take if, an effort to lock a set of records is unsuccessful. The following statements specify the action to take in detail.
<table>
<tr class="head">
<th>ON clause</th>
<th>Can be used for...</th>
</tr>

<tr>
<td nowrap>RECORD LOCKING CONFLICT </td>
<td>Any type of conflict, including a retrieval statement conflict, that arises during a record locking attempt.</td>
</tr>

<tr>
<td>FIND CONFLICT </td>
<td>Only a conflict that arises during the evaluation of a FIND statement or a FOR EACH RECORD statement used for retrieval. </td>
</tr>
</table>

====Syntax====

The format for these ON units is: 
[label] ON {RECORD LOCKING CONFLICT | FIND CONFLICTS}


====If both types of ON units are active====

ON RECORD LOCKING CONFLICT and ON FIND CONFLICT follow the same rules as other ON units (see [[Subroutines#ON units|ON units]]). If both ON RECORD LOCKING CONFLICT and ON FIND CONFLICT are active within a request when a conflict occurs, the conflict is handled in the following manner:
<table>
<tr class="head">
<th>If the conflict results from... </th>
<th>Clause invoked...</th>
</tr>

<tr>
<td>FIND statement or FOR EACH RECORD statement used for retrieval </td>
<td>ON FIND CONFLICT</td>
</tr>

<tr>
<td>A condition other than the FIND or FOR EACH RECORD statement used for retrieval </td>
<td nowrap>ON RECORD LOCKING CONFLICT </td>
</tr>
</table>

===CLEAR ON statement===

The definition of an ON RECORD LOCKING CONFLICT or ON FIND CONFLICT unit is cleared by the following statement: 
CLEAR ON {RECORD LOCKING CONFLICT | FIND CONFLICTS}


After a CLEAR ON RECORD LOCKING CONFLICT or CLEAR ON FIND CONFLICT statement, a record locking conflict does not invoke the corresponding ON unit.

===Pause statement===

====Purpose====

You can use the <var>Pause</var> statement to cause the request to wait a specified number of seconds and then to retry the statement that caused the evaluation of the <var>ON</var> unit. 

====Syntax====

The format of the <var>Pause</var> statement is: 
{{Template:Pause statement syntax}}
Where:
<ul>
<li><var class="term">n</var> must be in the range 0-600, allowing a maximum pause of 10 minutes. </li>

<li><var class="term">%variable</var> is interpreted as a numeric value representing the number of seconds to wait. It must be in the range 0-86400. </li>
</ul>

====Usage====

The <var>Pause</var> statement is a bumpable wait.

If <var class="term">n</var> is not specified or is specified as zero, processing stops and does not continue until the user enters a carriage return. If <var class="term">n</var> is specified, processing continues automatically after <var class="term">n</var> seconds.

If <var class="term">%variable</var> takes any non-null, non-numeric value or a numeric value in the range 0-86400, the SOUL request is canceled with the message:
M204.2650: PAUSE TIME-VARIABLE NOT IN RANGE


A variable with a null or 0 value does a terminal read. For example, <code>%a='xxx'</code> is treated as if zero was specified, and a read is issued.

Note: You should generally specify small values for <var class="term">n</var> and issue a <var>Pause</var> only when no records are held by the request. If <var class="term">n</var> is large, the request can seem to be hung. 

====See also====

The <var>[[$WakeUp]]</var> function is an alternative approach; it offers millisecond resolution pausing.

===Handling Parallel Query Option/204 record locking conflicts===

If a client request cannot complete because of a record locking conflict on the server system, the server automatically tries again to lock the record or set of records. The server tries again until it succeeds or until it has tried as many times as the value of the client thread ENQRETRY parameter. The value of the ENQRETRY parameter that is specified on the server thread has no effect on the number of retries. 

If ENQRETRY attempts to lock a record or set of records do not succeed, the server notifies the client about the conflict. If an ON RECORD LOCKING or ON FIND CONFLICT unit is active, the unit is invoked. Otherwise, the client receives a message that the locking failed, followed by a prompt asking if the client wants to try again. 

If the client enters <var>N</var>, the request is canceled. If the client enters <var>Y</var>, the server repeats the locking attempt cycle, making as many as ENQRETRY attempts before prompting again. 

==Record locking and release statements==

The following statements can place a lock on a set of records or remove the lock placed on records.
Note: To remove the lock placed on record sets, you can also use the COMMIT RELEASE for of the [[#COMMIT statement|COMMIT statement]].

===FIND AND RESERVE statement===

A User Language request can lock records in exclusive mode by using the FIND AND RESERVE statement. However, because records are exclusively locked, concurrency is reduced. 

====Syntax====

The basic format of the FIND AND RESERVE statement is:
FIND AND RESERVE [ALL] RECORDS FOR WHICH


====Example====
BEGIN
ON RECORD LOCKING CONFLICT
PRINT 'RECORD LOCKING CONFLICT OCCURRED WITH ' -
WITH $RLCUSR
PRINT 'FILE ' WITH $RLCFILE
PRINT 'RECORD ' WITH $RLCREC
END ON

POL.HLDR: IN CLIENTS FIND AND RESERVE ALL RECORDS -
FOR WHICH POLICY NO = 100015
RECTYPE = POLICYHOLDER
END FIND
OWNER.POL: IN VEHICLES FIND AND RESERVE ALL RECORDS -
FOR WHICH OWNER POLICY = 100015
END FIND
FOR EACH RECORD IN OWNER.POL
%NEW.PREMIUM = VEHICLE PREMIUM + 100
CHANGE VEHICLE PREMIUM TO %NEW.PREMIUM
%TOTAL.PREMIUM = %TOTAL.PREMIUM + %NEW.PREMIUM
END FOR
FOR EACH RECORD IN POL.HLDR
CHANGE TOTAL PREMIUM TO %TOTAL.PREMIUM
END FOR
END


In the preceding example, the first FIND AND RESERVE statement prevents access to TOTAL PREMIUM while its corresponding VEHICLE PREMIUMs are being changed. 

===Release Records statement===

Records found using the <var>Find And Reserve</var> statement are held in exclusive status until the end of the request or until they are released explicitly by the user with the <var>Release Records</var> statement. The <var>Release Records</var> statement also can be used to release records from <var>Sort</var> statements or records obtained in share status by <var>Find</var> statements issued in the regular form. Records released in this manner are no longer available to the request and might have to be found again. The original found set or list from which the sorted set was built is not affected. 

Note: To avoid producing confusing results, issue a <var>Release Records</var> statement at the end of a loop and not in the middle of one, since the statement relinquishes control of a found set. 

====Syntax====

The format of the <var>Release Records</var> statement is:
{{Template:Release Records statement syntax}}

where <var class="term">label</var> is the statement label of the FIND statement that locked the records.

The <var>Release Records</var> statement is supported in remote file and scattered group contexts.

====Processing====

The <var>Release Records</var> statement removes all:
<ul>
<li>Entries from the specified found set(s), thereby removing the record set lock</li>

<li>List entries, when issued against list(s)</li>

<li>The user's single record locks.</li>
</ul>

When the <var>Release</var> statement refers to a <var>Sort</var> statement, the space occupied by the temporary sorted record copies is released.

<var>Release Records On</var> is equivalent to the <var>Clear List</var> statement. 

===Release All Records statement===

====Description====

A <var>Release All Records</var> statement terminates the lock in share mode placed on records by the <var>Find</var> statement. <var>Release All Records</var> also clears all lists and the results of all <var>Sort</var> statements, and sets the current record number to -1. 

After a <var>Release All Records</var> statement is processed in a <var>For Each Record</var> loop, subsequent references to the current record in the loop cannot find a current record. If processing returns to the top of the loop, no new record is available, and the first statement after the end of the loop is executed. 

====Syntax====

The format of this release statement is:
{{Template:Release All Records statement syntax}}

The <var>Release All Records</var> statement is supported in remote file and scattered group contexts.

===Release Imagine Records statement===

====Description====

A <var>Release Imagine Records</var> statement is exactly like a <var>Release All Records</var> statement except:

<ul>
<li>It frees all mappings of record numbers to records for [[Imagine Transparency]] files.</li>
<li>The <var>Release All Records</var> is done on all [[Daemon class#Transactional daemons|transactional daemon]] descendants.</li>
<li>It is not allowed to be invoked on a [[Daemon class#Transactional daemons|transactional daemon]].</li>
<li>It can be followed by an optional <var>Commit</var> or <var>Backout</var> keyword to indicate that a commit or backout is to be done before the rest of <var>Release All Record</var> processing.</li>
<li>If not followed by the <var>Commit</var> or <var>Backout</var> keyword, it cancels the request if in a uncommitted transaction (there are pending updates)</li>
</ul>


Outside of being a bit more concise than having a separate <var>Backout</var> statement, doing a <code>Release Imagine Records Backout</code> does not result in a <code>M204.1096: There were no updates for backout to process</code> message if there are no updates.


[[Imagine Transparency]] record numbers are thread-specific and are assigned sequentially, starting at 1, as records are found or accessed. One can the use [[Record loops#For Record Number processing|For Record Number]] statement to access the same <var>Imagine</var> record over transaction boundaries, though the record would be re-retrieved from the broker for each transaction. This is no longer possible after a <var>Release Imagine Records</var> statement is executed. On the plus side, this clears the record number to record mapping table which would, otherwise, grow indefinitely on a logged in thread. So, for long-lived threads, it is a good idea to do a <var>Release Imagine Records</var> whenever possible, to keep the mapping table small.


====Syntax====

The format of this Release Imagine Records statement is:
{{Template:Release Imagine Records statement syntax}}

===RELEASE and COMMIT RELEASE statements with global foundsets and lists===

The RELEASE statements and the COMMIT RELEASE statements empty the contents of a global found set, global sort set, or global list. The label and positions associated with a found set, sort set, or the list is still considered global, but it is empty. Global positions are not cleared by RELEASE or COMMIT RELEASE statements, however, without records there is nothing to process.

==Lock pending updates==

<var class="product">Model 204</var> provides a special facility, lock pending updates, that prevents updated records in one transaction (a sequence of file updating operations) from being used by other applications until the transaction ends. Lock pending updates ensures logical consistency without requiring the use of the FIND AND RESERVE statement. LPU locks are distinct from single record locks. 

===Processing===

If the lock pending updates option is specified, records are locked in share mode by a FIND statement. The first update to a record locks the record in exclusive mode and adds it to a set of updated locked records called the pending update pool. The record is not released from this exclusive lock at the end of the FOR EACH RECORD loop. Instead, the record is locked until the end of the transaction when the entire pending update pool is released.

===Set with the FOPT parameter===

Lock pending updates is an option of the <var>[[FOPT parameter|FOPT]]</var> parameter that is enabled or disabled on a file-by-file basis.


==Commit statement==

A <var>Commit</var> statement ends the current transaction, dequeues checkpoints, and drops all LPU locks and exclusive record locks obtained by update statements (<var>[[Add statement|Add]]</var>, <var>[[Change statement|Change]]</var>, <var>[[Data maintenance#Delete statement|Delete]]</var>) for all files participating in the transaction.
The <var>Commit</var> statement does not release record locks obtained by the <var>[[Find statement (find records)|Find]]</var> statement. The share record lock obtained by the <var>[[For Record Number statement|For Record Number]]</var> statement is not released by a <var>Commit</var> statement executed inside a loop.

The <var>Commit</var> statement is supported in remote context. If records on any remote nodes are updated, the <var>Commit</var> statement saves all remote updates on all remote nodes. Also, remote updates are committed automatically by the system when appropriate.

====Syntax====
{{Template:Commit statement syntax}}

====Example====
begin
get.rec: find all records for which
lname = 'NELSON'
end find
for each record in get.rec
add month = 'nov'
commit
print fname and lname and each month
end for
name.ct: count records in get.rec
print count in name.ct and 'records updated'
end


===Release option===

The <var>Release</var> option of the <var>Commit</var> statement performs all the operations of the <var>Commit</var> and <var>[[Release All Records statement|Release All Records]]</var> statements:
<table>
<tr class="head">
<th nowrap>After processing a 
Commit Release
statement ... </th>
<th valign="bottom">Any subsequent reference to the current...</th>
</tr>

<tr>
<td nowrap><var>[[For Each Record statement|For Each Record]]</var> loop </td>
<td>Record in the loop cannot find a current record. If processing returns to the top of the loop, no new record is available; the first statement after the end of each loop is executed.</td>
</tr>

<tr>
<td><var>[[For Each Value statement|For Each Value]]</var> loop </td>
<td>Value still obtains the last value processed. </td>
</tr>
</table>

====Usage====

To avoid confusing results, it is recommended that <var>Commit Release</var> be issued at the end of a loop and not in the middle of one.

===Release and Commit Release statements with global foundsets and lists===

The <var>Release</var> statement and the <var>Commit Release</var> statement both empty the contents of a global found set, global sort set, or global list. The label and positions associated with a found set, sort set, or the list is still considered global, but it is empty. Global positions are not cleared by <var>Release</var> or <var>Commit Release</var> statements, however, without records there is nothing to process. 

</div> 

[[Category:SOUL]]

Record level locking and concurrency control

2025-09-05T20:08:58Z

Alex: /* Release All Records statement */

<div class="toclimit-3">

==Overview==

This article discusses aspects of request design related to concurrency control in a multi-user environment and presents statements and <var class="product">Model 204</var> options that can be used to ensure logical consistency.

===Illustrating a concurrent update===

A user executing a User Language request expects that the records retrieved will not be modified by another user's concurrent request until the user's own request has completed. For example, consider these two requests being run concurrently:

User 1 
BEGIN
BLUE.CARS: FIND ALL RECORDS FOR WHICH
COLOR = BLUE
END FIND
FOR EACH RECORD IN BLUE.CARS
PRINT MAKE AND COLOR
END FOR
END


User 2
BEGIN
BLUE.BUICKS: FIND ALL RECORDS FOR WHICH
MAKE = BUICK AND COLOR = BLUE
END FIND
FOR EACH RECORD IN BLUE.BUICKS
CHANGE COLOR TO RED
END FOR
END


User 1 expects only the make and the color BLUE to be printed. User 2's request must be prevented from changing User 1's records before they are printed.

==Record locking in Model 204==

Conflicts arise when one or more users are reading a file and another user attempts to update the file or when two or more users attempt to perform file maintenance on the same records retrieved from that file. The technique used by <var class="product">Model 204</var> to prevent overlapping updates is called record level locking. 

===Record locking modes===

<var class="product">Model 204</var> can lock records as a set of records or as a single record number. <var class="product">Model 204</var> performs record level locking in two modes: 
<table>
<tr class="head">
<th>Lock mode </th>
<th>Allows... </th>
</tr>

<tr>
<td>Share </td>
<td>One or more users to read a file. Any number of users can have shared control of a record or record set concurrently. </td>
</tr>

<tr>
<td>Exclusive </td>
<td>Single user to update the file. An exclusive lock is not compatible with other exclusive locks nor with any shared locks. </td>
</tr>
</table>

All records in a record set have the same locking strength: they are all locked share, or exclusive, or they are all unlocked. 

===FIND statement records===

Records located by a FIND statement, called a record set or found set, are locked based on the FIND statement specification:
<ul>
<li><var>FIND</var>

Locks the record set in share mode
</li>
<li><var>FIND AND RESERVE</var>

Locks the record set in exclusive mode 
</li>
<li><var>FIND WITHOUT LOCK</var>

Does not lock record set
</li>
</ul>

Once obtained record set locks are kept till a RELEASE or COMMIT RELEASE statement is executed or the request ends.

==Record level locking evaluation rules==

===Request compilation and evaluation===

Record-level locking is performed in the following manner. User Language requests are processed in two phases: compilation and evaluation. All requests can be compiled regardless of the operations to be performed or of other requests being compiled or evaluated at the same time. All requests are allowed to begin the evaluation stage. 

When the evaluation involves records or sets of records, <var class="product">Model 204</var> automatically ensures that operations achieves the expected results by adhering to the following set of rules. The following User Language statements generate found sets that are processed as described.

====FIND statement====

The <var>Find</var> statement immediately locks the set of records it has retrieved in share mode. If the locking is successful, none of the records in that set can be updated by another user until the entire request, including request continuation(s), has been completed or the records have been released by some form of the <var>Release</var> statement, such as <var>Release Records In</var>..., <var>Release All Records</var>, <var>Release Commit</var>.

A <var>Find</var> statement executed in a loop releases the old found set as soon as the statement is re-executed. The final set selected by the <var>Find</var> remains locked until the end of the request. An unlabeled <var>Find</var> statement, such as a <var>Find And Print Count</var> statement, does not lock records at all.

====FIND WITHOUT LOCKS statement====

The FIND WITHOUT LOCKS statement executes a FIND statement without locking any records. The found set of records is indistinguishable from a list, except that it is referenced with an IN label clause. You must use the FIND WITHOUT LOCKS statement with caution, otherwise logical inconsistencies might occur. See [[#FIND WITHOUT LOCKS statement|FIND WITHOUT LOCKS statement]] for more information.

====FOR RECORD NUMBER statement====

The FOR RECORD NUMBER statement locks the specified record in share mode, if it was not locked by the FIND statement. The lock is kept until the end of the loop or a COMMIT statement is processed. 

====DELETE ALL RECORDS IN statement====

The DELETE ALL RECORDS IN statement temporarily locks the set of records to be deleted in exclusive mode before deletion occurs. The locking does not succeed if another user has access to any of the records through a FIND or file maintenance statement. Once a record has been deleted, the exclusive lock on the record is released, because the record no longer exists in the file. 

====ADD, CHANGE, or DELETE, DELETE RECORD, and INSERT statements====

The ADD, CHANGE, DELETE fieldname, DELETE RECORD, and INSERT statements all lock the current record in exclusive mode before updating it. The exclusive single record lock remains on the current record until it passes through the loop, unless the record has been deleted. 

Upon completion of a DELETE RECORD statement the deleted record cannot cause a record locking conflict. However, it the deleting user attempts to reference the deleted record via a previously established found set or list, the following message is issued:
M204.1266: NONEXISTENT RECORD REFERENCED


====STORE RECORD statement====

The STORE RECORD statement gets a LPU record lock for the TBO files and does not get a record lock for non-TBO files.
<ul>
<li>For TBO files, an LPU record lock, which is always exclusive, is obtained, meaning unconditionally gotten, at the beginning of the STORE RECORD processing. However, other users cannot get a record locking conflict, because the record's existence bit is not turned on until STORE RECORD processing finishes. If you store a record, you automatically obtain an LPU lock and hold it until the next COMMIT statement is processed.</li>

<li>For non-TBO files, no record lock of any kind is obtained. However, the record existence bit is not turned on until STORE RECORD processing is finished, so there are no problems with protecting the record from other users during STORE RECORD processing.</li>
</ul>

====END MORE statement====

If a request ends with END MORE, records found by that request remain locked and cannot be modified by other users. If the request ends with END, all records are released as soon as execution is completed. 

===Locking conflicts===

If <var class="product">Model 204</var> cannot lock a record, a locking conflict occurs, which are discussed in detail in [[#Handling locking conflicts|Handling locking conflicts]]. 

==FIND WITHOUT LOCKS statement==

The FIND WITHOUT LOCKS statement executes a FIND statement without locking any records. The resulting found set is indistinguishable from a list, except that it is referenced with an IN label clause.

Note: The FIND WITHOUT LOCKS feature should be used only to solve specific performance problems. Before using the FIND WITHOUT LOCKS statement, please take into account the [[#FIND WITHOUT LOCKS statement|FIND WITHOUT LOCKS statement]] following [[#Responding to a record locking conflict|Responding to a record locking conflict]].

====Syntax====

The format of the FIND WITHOUT LOCKS statement is:
{FIND WITHOUT LOCKS | FDWOL} [ALL] RECORDS
[IN label | ON [LIST] listname]
[FOR WHICH | WITH] retrieval-conditions


====Usage notes====

Issues involved with using FIND WITHOUT LOCKS include:
<ul>
<li>Logical integrity of data is at risk when another user:
<ul>
<li>Is in the midst of changing values which are related</li>
<li>Changes or deletes the field which caused the record to be found</li>
</ul></li>

<li>Physical integrity error messages or snaps are generated, including:

<ul>
<li>SICK RECORD messages are sent when extension records are deleted. The record is not really sick; temporarily it appears that way to <var class="product">Model 204</var>.</li>

<li>SICK RECORD messages are sent from FOR EACH OCCURRENCE (FEO) statements when the record is modified by another user. Again, the record is not really sick.</li>

<li>NONEXISTENT RECORD messages are sent when entire records are deleted. </li>
</ul>

<li>Examples of appropriate use of the FIND WITHOUT LOCKS statement include:
<ul>
<li>When there is one user at a time per record (for example, scratch records or bank teller applications where an account is usually modified by one teller at a time)</li>

<li>Report programs in a heavy update environment </li>
</ul>

<li>Examples of inappropriate uses of the FIND WITHOUT LOCKS, which can result in snaps, include:
<ul>
<li>Report program in a heavy delete environment (results in many
NONEXISTENT RECORD messages)</li>

<li>Retrievals in which the selection criteria can be changed by other users</li>

<li>Reuse Record Number files, except possibly scratch files keyed on the user ID </li>
</ul></li>
</ul>

==Handling locking conflicts==

A typical locking situation is as follows. The first user issues a FIND statement for a large set of records and begins printing a long report. The second user issues a FIND statement for some of the same records and tries to update them with a CHANGE statement. 

===ENQRETRY parameter===

The number of times a request automatically attempts to lock a record or set of records before notifying the user of a conflict is determined by the
<var>[[ENQRETRY parameter|ENQRETRY]]</var> parameter.
Between attempts, <var class="product">Model 204</var> waits until the record or records that were held by another user are released or until three seconds pass.


Under these circumstances, the second user must decide whether to cancel the request or try again. The second user receives a message noting that the locking failed and is queried: <var>DO YOU REALLY WANT TO TRY AGAIN?</var> The second user can respond in one of three ways:
<ul>
<li>Reply <var>N</var>, thereby cancelling the request.</li>

<li>Reply <var>Y</var> and try to lock again immediately.</li>

<li>Wait a minute or two and reply <var>Y</var>. </li>
</ul>

===Responding to a record locking conflict===

In <var class="product">Model 204</var> you can specify the action to take if, an effort to lock a set of records is unsuccessful. The following statements specify the action to take in detail.
<table>
<tr class="head">
<th>ON clause</th>
<th>Can be used for...</th>
</tr>

<tr>
<td nowrap>RECORD LOCKING CONFLICT </td>
<td>Any type of conflict, including a retrieval statement conflict, that arises during a record locking attempt.</td>
</tr>

<tr>
<td>FIND CONFLICT </td>
<td>Only a conflict that arises during the evaluation of a FIND statement or a FOR EACH RECORD statement used for retrieval. </td>
</tr>
</table>

====Syntax====

The format for these ON units is: 
[label] ON {RECORD LOCKING CONFLICT | FIND CONFLICTS}


====If both types of ON units are active====

ON RECORD LOCKING CONFLICT and ON FIND CONFLICT follow the same rules as other ON units (see [[Subroutines#ON units|ON units]]). If both ON RECORD LOCKING CONFLICT and ON FIND CONFLICT are active within a request when a conflict occurs, the conflict is handled in the following manner:
<table>
<tr class="head">
<th>If the conflict results from... </th>
<th>Clause invoked...</th>
</tr>

<tr>
<td>FIND statement or FOR EACH RECORD statement used for retrieval </td>
<td>ON FIND CONFLICT</td>
</tr>

<tr>
<td>A condition other than the FIND or FOR EACH RECORD statement used for retrieval </td>
<td nowrap>ON RECORD LOCKING CONFLICT </td>
</tr>
</table>

===CLEAR ON statement===

The definition of an ON RECORD LOCKING CONFLICT or ON FIND CONFLICT unit is cleared by the following statement: 
CLEAR ON {RECORD LOCKING CONFLICT | FIND CONFLICTS}


After a CLEAR ON RECORD LOCKING CONFLICT or CLEAR ON FIND CONFLICT statement, a record locking conflict does not invoke the corresponding ON unit.

===Pause statement===

====Purpose====

You can use the <var>Pause</var> statement to cause the request to wait a specified number of seconds and then to retry the statement that caused the evaluation of the <var>ON</var> unit. 

====Syntax====

The format of the <var>Pause</var> statement is: 
{{Template:Pause statement syntax}}
Where:
<ul>
<li><var class="term">n</var> must be in the range 0-600, allowing a maximum pause of 10 minutes. </li>

<li><var class="term">%variable</var> is interpreted as a numeric value representing the number of seconds to wait. It must be in the range 0-86400. </li>
</ul>

====Usage====

The <var>Pause</var> statement is a bumpable wait.

If <var class="term">n</var> is not specified or is specified as zero, processing stops and does not continue until the user enters a carriage return. If <var class="term">n</var> is specified, processing continues automatically after <var class="term">n</var> seconds.

If <var class="term">%variable</var> takes any non-null, non-numeric value or a numeric value in the range 0-86400, the SOUL request is canceled with the message:
M204.2650: PAUSE TIME-VARIABLE NOT IN RANGE


A variable with a null or 0 value does a terminal read. For example, <code>%a='xxx'</code> is treated as if zero was specified, and a read is issued.

Note: You should generally specify small values for <var class="term">n</var> and issue a <var>Pause</var> only when no records are held by the request. If <var class="term">n</var> is large, the request can seem to be hung. 

====See also====

The <var>[[$WakeUp]]</var> function is an alternative approach; it offers millisecond resolution pausing.

===Handling Parallel Query Option/204 record locking conflicts===

If a client request cannot complete because of a record locking conflict on the server system, the server automatically tries again to lock the record or set of records. The server tries again until it succeeds or until it has tried as many times as the value of the client thread ENQRETRY parameter. The value of the ENQRETRY parameter that is specified on the server thread has no effect on the number of retries. 

If ENQRETRY attempts to lock a record or set of records do not succeed, the server notifies the client about the conflict. If an ON RECORD LOCKING or ON FIND CONFLICT unit is active, the unit is invoked. Otherwise, the client receives a message that the locking failed, followed by a prompt asking if the client wants to try again. 

If the client enters <var>N</var>, the request is canceled. If the client enters <var>Y</var>, the server repeats the locking attempt cycle, making as many as ENQRETRY attempts before prompting again. 

==Record locking and release statements==

The following statements can place a lock on a set of records or remove the lock placed on records.
Note: To remove the lock placed on record sets, you can also use the COMMIT RELEASE for of the [[#COMMIT statement|COMMIT statement]].

===FIND AND RESERVE statement===

A User Language request can lock records in exclusive mode by using the FIND AND RESERVE statement. However, because records are exclusively locked, concurrency is reduced. 

====Syntax====

The basic format of the FIND AND RESERVE statement is:
FIND AND RESERVE [ALL] RECORDS FOR WHICH


====Example====
BEGIN
ON RECORD LOCKING CONFLICT
PRINT 'RECORD LOCKING CONFLICT OCCURRED WITH ' -
WITH $RLCUSR
PRINT 'FILE ' WITH $RLCFILE
PRINT 'RECORD ' WITH $RLCREC
END ON

POL.HLDR: IN CLIENTS FIND AND RESERVE ALL RECORDS -
FOR WHICH POLICY NO = 100015
RECTYPE = POLICYHOLDER
END FIND
OWNER.POL: IN VEHICLES FIND AND RESERVE ALL RECORDS -
FOR WHICH OWNER POLICY = 100015
END FIND
FOR EACH RECORD IN OWNER.POL
%NEW.PREMIUM = VEHICLE PREMIUM + 100
CHANGE VEHICLE PREMIUM TO %NEW.PREMIUM
%TOTAL.PREMIUM = %TOTAL.PREMIUM + %NEW.PREMIUM
END FOR
FOR EACH RECORD IN POL.HLDR
CHANGE TOTAL PREMIUM TO %TOTAL.PREMIUM
END FOR
END


In the preceding example, the first FIND AND RESERVE statement prevents access to TOTAL PREMIUM while its corresponding VEHICLE PREMIUMs are being changed. 

===Release Records statement===

Records found using the <var>Find And Reserve</var> statement are held in exclusive status until the end of the request or until they are released explicitly by the user with the <var>Release Records</var> statement. The <var>Release Records</var> statement also can be used to release records from <var>Sort</var> statements or records obtained in share status by <var>Find</var> statements issued in the regular form. Records released in this manner are no longer available to the request and might have to be found again. The original found set or list from which the sorted set was built is not affected. 

Note: To avoid producing confusing results, issue a <var>Release Records</var> statement at the end of a loop and not in the middle of one, since the statement relinquishes control of a found set. 

====Syntax====

The format of the <var>Release Records</var> statement is:
{{Template:Release Records statement syntax}}

where <var class="term">label</var> is the statement label of the FIND statement that locked the records.

The <var>Release Records</var> statement is supported in remote file and scattered group contexts.

====Processing====

The <var>Release Records</var> statement removes all:
<ul>
<li>Entries from the specified found set(s), thereby removing the record set lock</li>

<li>List entries, when issued against list(s)</li>

<li>The user's single record locks.</li>
</ul>

When the <var>Release</var> statement refers to a <var>Sort</var> statement, the space occupied by the temporary sorted record copies is released.

<var>Release Records On</var> is equivalent to the <var>Clear List</var> statement. 

===Release All Records statement===

====Description====

A <var>Release All Records</var> statement terminates the lock in share mode placed on records by the <var>Find</var> statement. <var>Release All Records</var> also clears all lists and the results of all <var>Sort</var> statements, and sets the current record number to -1. 

After a <var>Release All Records</var> statement is processed in a <var>For Each Record</var> loop, subsequent references to the current record in the loop cannot find a current record. If processing returns to the top of the loop, no new record is available, and the first statement after the end of the loop is executed. 

====Syntax====

The format of this release statement is:
{{Template:Release All Records statement syntax}}

The <var>Release All Records</var> statement is supported in remote file and scattered group contexts.

===Release Imagine Records statement===

====Description====

A <var>Release Imagine Records</var> statement is exactly like a <var>Release All Records</var> statement except:

<ul>
<li>It frees all mappings of record numbers to records for [[Imagine Transparency]] files.</li>
<li>The <var>Release All Records</var> is done on all [[Daemon class#Transactional daemons|transactional daemon]] descendants.</li>
<li>It is not allowed to be invoked on a [[Daemon class#Transactional daemons|transactional daemon]].</li>
<li>It can be followed by an optional <var>Commit</var> or <var>Backout</var> keyword to indicate that a commit or backout is to be done before the rest of <var>Release All Record</var> processing.</li>
<li>If not followed by the <var>Commit</var> or <var>Backout</var> keyword, it cancels the request if in a uncommitted transaction (there are pending updates)</li>
</ul>

====Syntax====

The format of this Release Imagine Records statement is:
{{Template:Release Imagine Records statement syntax}}

===RELEASE and COMMIT RELEASE statements with global foundsets and lists===

The RELEASE statements and the COMMIT RELEASE statements empty the contents of a global found set, global sort set, or global list. The label and positions associated with a found set, sort set, or the list is still considered global, but it is empty. Global positions are not cleared by RELEASE or COMMIT RELEASE statements, however, without records there is nothing to process.

==Lock pending updates==

<var class="product">Model 204</var> provides a special facility, lock pending updates, that prevents updated records in one transaction (a sequence of file updating operations) from being used by other applications until the transaction ends. Lock pending updates ensures logical consistency without requiring the use of the FIND AND RESERVE statement. LPU locks are distinct from single record locks. 

===Processing===

If the lock pending updates option is specified, records are locked in share mode by a FIND statement. The first update to a record locks the record in exclusive mode and adds it to a set of updated locked records called the pending update pool. The record is not released from this exclusive lock at the end of the FOR EACH RECORD loop. Instead, the record is locked until the end of the transaction when the entire pending update pool is released.

===Set with the FOPT parameter===

Lock pending updates is an option of the <var>[[FOPT parameter|FOPT]]</var> parameter that is enabled or disabled on a file-by-file basis.


==Commit statement==

A <var>Commit</var> statement ends the current transaction, dequeues checkpoints, and drops all LPU locks and exclusive record locks obtained by update statements (<var>[[Add statement|Add]]</var>, <var>[[Change statement|Change]]</var>, <var>[[Data maintenance#Delete statement|Delete]]</var>) for all files participating in the transaction.
The <var>Commit</var> statement does not release record locks obtained by the <var>[[Find statement (find records)|Find]]</var> statement. The share record lock obtained by the <var>[[For Record Number statement|For Record Number]]</var> statement is not released by a <var>Commit</var> statement executed inside a loop.

The <var>Commit</var> statement is supported in remote context. If records on any remote nodes are updated, the <var>Commit</var> statement saves all remote updates on all remote nodes. Also, remote updates are committed automatically by the system when appropriate.

====Syntax====
{{Template:Commit statement syntax}}

====Example====
begin
get.rec: find all records for which
lname = 'NELSON'
end find
for each record in get.rec
add month = 'nov'
commit
print fname and lname and each month
end for
name.ct: count records in get.rec
print count in name.ct and 'records updated'
end


===Release option===

The <var>Release</var> option of the <var>Commit</var> statement performs all the operations of the <var>Commit</var> and <var>[[Release All Records statement|Release All Records]]</var> statements:
<table>
<tr class="head">
<th nowrap>After processing a 
Commit Release
statement ... </th>
<th valign="bottom">Any subsequent reference to the current...</th>
</tr>

<tr>
<td nowrap><var>[[For Each Record statement|For Each Record]]</var> loop </td>
<td>Record in the loop cannot find a current record. If processing returns to the top of the loop, no new record is available; the first statement after the end of each loop is executed.</td>
</tr>

<tr>
<td><var>[[For Each Value statement|For Each Value]]</var> loop </td>
<td>Value still obtains the last value processed. </td>
</tr>
</table>

====Usage====

To avoid confusing results, it is recommended that <var>Commit Release</var> be issued at the end of a loop and not in the middle of one.

===Release and Commit Release statements with global foundsets and lists===

The <var>Release</var> statement and the <var>Commit Release</var> statement both empty the contents of a global found set, global sort set, or global list. The label and positions associated with a found set, sort set, or the list is still considered global, but it is empty. Global positions are not cleared by <var>Release</var> or <var>Commit Release</var> statements, however, without records there is nothing to process. 

</div> 

[[Category:SOUL]]

Release Imagine Records statement

2025-09-05T19:51:05Z

Alex: Redirected page to Record level locking and concurrency control#Release Imagine Records statement

#REDIRECT [[Record level locking and concurrency control#Release Imagine Records statement]]

Statement syntax

2025-09-05T19:49:03Z

Alex: /* Release All Records */

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.

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. 
External Call Facility (ECF) statements are listed under <var>[[#External|External]]</var>.

Various other [[List of Model 204 commands|Model 204 commands]] also have effects on the results of a SOUL request. 

The following notations prefix some of the statements in the presentation of the SOUL syntax: 
<nowiki>*
**
+
++
C
</nowiki>

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.

  
<div id="User Language statements"></div> 
<div id="SOUL statements"></div> <div id="SOUL syntax"></div>



===[[Add statement|Add]]===
<table class="noBorder">
<tr>
<td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]]</td>
<td>{{Template:Add fieldname statement syntax}}</td></tr>
</table>

<table class="noBorder">
<tr><td style="padding:0em">{{Template:Add lob-fieldname statement syntax}} </td></tr>
</table>

===[[Array statement|Array]]===

Array [arrayname] Occurs {n | Unknown}
Depending On {itemname | %variable}
[After {itemname | arrayname}
| At {position | itemname | imagename1 | arrayname}]


===[[Assert statement|Assert]]===

{{Template:Assert statement syntax}}

===[[Report generation#Audit statement|Audit]]===

Audit [[#Print specification syntax|print-specifications]]


===[[Audit All Fieldgroup Information statement|Audit All Fieldgroup Information]] (AAFGI)===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td>
<td>{{Template:AAFGI statement syntax}} </td></tr>
</table>

===[[Report generation#Audit All Information statement|Audit All Information]]===

<table class="noBorder">
<tr><td>{{Template:Audit All Information statement syntax}} </td></tr>
</table>

===Backout===
<table class="noBorder">
<tr><td/>
<td>[[Backout statement|Backout]] </td></tr>
</table>

===BYPASS===

BYPASS [PENDING STATEMENT] 

===CALL===

CALL {label | subname
[([expression | %variable | [LIST] listname] [,...])]}


===[[Data maintenance#Change statement|Change]]===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td>
<td>{{Template:Change fieldname statement syntax (basic)}} </td></tr>
</table>

<table class="noBorder">
<tr>
<td style="padding:0em">{{Template:Change lob-fieldname statement syntax}} </td></tr>
</table>

===[[Global_features#Using_the_CLEAR_statement|CLEAR]]===

{{Template:Clear statement syntax}}

===CLEAR LIST===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*)]] </td>
<td>[[Lists#Clearing a list|CLEAR LIST]] listname </td></tr>
</table>

===CLEAR ON===

{{Template:Clear On statement syntax}}

===CLEAR TAG===

CLEAR TAG {screenname | %screenname:inputname}


===[[Close statement (external I/O)|Close]]===

<table class="noBorder">
<tr><td>{{Template:Close statement (external I/O) syntax}} </td></tr>
</table>

===CLOSE PROCESS===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+C)]] </td>
<td>CLOSE PROCESS {cid | processname | %variable} [SYNCLEVEL | FLUSH | %variable] </td></tr>
</table>

CLOSE PROCESS
{cid | processname | %variable}
[SYNCLEVEL | CONFIRM | FLUSH | ERROR | %variable]


===[[Commit statement|Commit]]===

{{Template:Commit statement syntax}}

===[[Horizon SOUL interface#Confirm statement|Confirm]]===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td>
<td>{{Template:Confirm statement syntax}} </td></tr>
</table>

===[[Horizon SOUL interface#Confirmed statement|Confirmed]]===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td>
<td>{{Template:Confirmed statement syntax}} </td></tr>
</table>

===CONTINUE===

CONTINUE

===COUNT OCCURRENCES OF===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td>
<td>COUNT OCCURRENCES OF fieldname</td></tr>
</table>

===COUNT RECORDS===

COUNT RECORDS {IN label | ON [LIST] listname}

===[[Declare statement|Declare]]===

[[[Using variables and values in computation#Declaring|Declare]]] declaration



where <var class="term">declaration</var> is one of the following: 

<div style="margin-left: 20px; background-color: #fBfBfB;">
<ul style="font-family: Consolas,monospace; display:table;">
<li>Label labelname [Global | Common]
</li>

<li>[[Lists#DECLARE LIST syntax|List]] listname [In [File | [Perm | Temp] Group]] name] At location [Global | Common]
</li>

<li><var>Image</var> block:
{{Template:Image statement syntax}} </li>

<li>{{Template:Menu statement syntax}} </li>

<li>{{Template:Screen statement syntax}} </li>

<li>%variable [Is] {Fixed [Dp n] | Float} [Array (d1 [,d2 [,d3]])] 
[[[Initial clause in %variable declaration|Initial]](numeric-expression)] [Static] [Common]
</li>

<li>%variable [Is] String [Len n] [Dp {n | *}] [Array (d1 [,d2[,d3]])] 
[No Field Save] [Common] 
[[[Initial clause in %variable declaration|Initial]]('EBCDIC-string' | expression)] [Static]
</li>

<li>[[Subroutines#DECLARE SUBROUTINE statement|Subroutine]] subname [(type [Input | Output | Input Output] [,...])]

where <var class="term">type</var> is one of the following: 
<ul>
<li>Scalar %variable of the following format:
{String [Len] n [DP {n | *}] | [Fixed [Dp n] | Float]} 
</li>

<li>Array %variable of the following format:
{String [Len n] [Dp [n | *}] [Array (* [,*[,*]]) [No Field Save]] 
| [Fixed [Dp n] | Float] [Array (* [,*[,*]])]} 
</li>

<li>A list of records of the following format:
[List] [In {File | [Perm | Temp] Group} name] 
</li></ul>
</ul>

</div> 

===DEFAULT CURSOR===

DEFAULT CURSOR [READ | REREAD | PRINT]
{ITEMID n | itemname | ROW n COLUMN m}


===DEFAULT===

DEFAULT {TITLE
| PROMPT
| INPUT [DEBLANK | NODEBLANK] [PAD WITH 'c'] [LEN m [DP [k | *}]] [UPCASE | NOCASE]
| [TAG [attributes] [WITH 'c']}
[[READ] attributes] [REREAD attributes] [PRINT attributes]

DEFAULT SKIP n POSITIONS[S]
[INITIAL {NULL | character | BLANK}]

DEFAULT [TYPE]
{STRING | BINARY | PACKED | ZONED | FLOAT | EFORMAT}
{LEN {n | UNKNOWN} | BITS n | DIGITS n}
[DP {k | *}] [BP n]
[SIGNED | UNSIGNED] [PAD {BLANK | character | NULL}]
[STRIP | NOSTRIP] [JUSTIFY {LEFT | RIGHT}]
[INITIAL {BLANK | ZERO | NULL | literal}]


===DELETE===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td>
<td>[[Data maintenance#DELETE statement|DELETE]] fieldname [([[Processing_multiply_occurring_fields_and_field_groups#DELETE_statement_rules|subscript]])] [= value | (expression)]
</td></tr>
</table>

<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td>
<td>[[Data maintenance#Deleting a field group|DELETE FIELDGROUP]] [fieldgroupname] [([[Processing_multiply_occurring_fields_and_field_groups#DELETE_statement_rules|subscript]])] [= value | (expression)]
</td></tr>
</table>

===DELETE EACH===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td>
<td>DELETE EACH fieldname </td></tr>
</table>

===[[Data maintenance#DELETE RECORD statement|DELETE RECORD]]===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td>
<td>DELETE RECORD </td></tr>
</table>

===DELETE RECORDS===

DELETE [ALL] RECORDS {IN label | ON [LIST] listname}


===END BLOCK===

END BLOCK label 

===End===

END {FIND | IF | FOR | ON | REPEAT | STORE | SUBROUTINE} [label]

END {ARRAY | IMAGE | MENU | SCREEN}

[[End statement|End]] [MORE | NORUN | USE]...

===END UPDATE===

END UPDATE

===[[External statement|External]]===

{{Template:External statement syntax}}

===FILE RECORDS===

FILE RECORDS {IN label | ON [LIST] listname}
UNDER fieldname = {value | (expression)}


===[[Find Records statement|Find Records]]===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*)]] </td>
<td>{FIND [[ALL] RECORDS] | FD } [IN label | ON [LIST] listname] [FOR WHICH | WITH] [[#Retrieval condition syntax|retrieval-conditions]]</td></tr>
</table>

===[[Find And Reserve statement|Find And Reserve]]===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*)]] </td>
<td>{FIND AND RESERVE [[ALL] RECORDS] | FDR} [IN label | ON [LIST] listname] [FOR WHICH | WITH] [[#Retrieval condition syntax|retrieval-conditions]] </td></tr>
</table>

===[[Value loops#Find All Values statement|Find Values Of (FDV)]]===
<table class="noBorder">
<tr>
<td style="padding:0em">{{Template: Find Values Of statement syntax}} </td></tr>
</table>

===FIND AND PRINT COUNT===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*)]] </td>
<td>{Find And Print Count | FPC} [[[#Retrieval condition syntax|retrieval-conditions]]]
</td></tr>
</table>

===[[Find Records statement|Find Without Locks]]===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*)]] </td>
<td>{Find Without Locks [[ALL] Records] | FDWOL} [In label | On [LIST] listname]
[For Which | With] [[#Retrieval condition syntax|retrieval-conditions]]</td></tr>
</table>

===FLUSH PROCESS===

FLUSH PROCESS {cid | processname | %variable}

===FOR EACH OCCURRENCE===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td>
<td>FOR {EACH | k} {OCCURRENCE | OCCURRENCES} OF fieldname </td></tr>
</table>

===[[Record loops#For Each Record statement|For Each Record]]===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*)]] </td>
<td>{{Template:For Each Record statement syntax}}</td></tr>
</table>
Note: For <var class="term">retrieval-conditions</var>, see [[#Retrieval condition syntax|Retrieval condition syntax]], below. 

===FOR EACH VALUE OF===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*)]] </td>
<td>FOR {EACH | k} {VALUE | VALUES} OF fieldname [FROM {value1 | (expression1)}] [TO {value2 | (expression2)}] [[NOT] LIKE pattern] [IN [ASCENDING | DESCENDING] [CHARACTER | NUMERICAL] [RIGHT-ADJUSTED] ORDER]
</td></tr>
</table>

===FOR EACH VALUE IN===

FOR {EACH | k} {VALUE | VALUES} IN label 

===FOR RECORD NUMBER===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*)]] </td>
<td>FOR RECORD NUMBER {value | (expression)}
</td></tr>
</table>

===FOR RECORD NUMBER IN===

FOR RECORD NUMBER {value | IN label} [OPTIMIZING FNV]


===[[For %i statement|For %var From %exp1 To %exp2 By %exp3]]===
<table class="noBorder">
<tr>
<td style="padding:0em">{{Template:For %i statement syntax}} </td></tr>
</table>

Note: The <var>By</var> clause, when omitted, defaults to a value of 1. 

===[[Images#Identify statement|Identify]]===

<table class="noBorder" display="table-column">
<tr><td>{{Template:Identify statement syntax}} </td></tr>
</table>

===[[If statement|If]]...Then...ElseIf...Else===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(C)]] </td>
<td>If expression Then [statement] [statement] ... [ ElseIf expression Then [statement] [statement] ... ] ... [ Else [statement] [statement] ... ] End If
</td></tr>
</table>

===[[Image statement or block|Image]]===
<var>Image</var> block:
<table class="noBorder">
<tr><td style="padding:0em">{{Template:Image statement syntax}}</td></tr>
</table>

===INCLUDE===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*, C)]] </td>
<td>INCLUDE procedurename </td></tr>
</table>

===INPUT===

INPUT inputname [AT [COLUMN] n]
[TO [COLUMN] m | [LEN m] DP {k | *}]]
[UPCASE | NOCASE] [DEFAULT 'value']
[DEBLANK | NODEBLANK] [PAD WITH 'c']
[REQUIRED | ALPHA | ALPHANUM | MUSTFILL
| ONEOF literal [, literal]...
| [NUMERIC] [RANGE lo [TO] hi [AND lo [TO] hi] ...]
| VERIFY 'characters']...
[[READ] attributes] [REREAD attributes] [PRINT attributes]
[TAG [attributes] [WITH 'c']] [ITEMID n]


===INSERT===

INSERT fieldname [(subscript)] = {value | (expression)}


===[[Horizon SOUL interface#Invite statement|Invite]]===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td>
<td>{{Template:Invite statement syntax}} </td></tr>
</table>

===IS===

itemname IS [TYPE]
{STRING | BINARY | PACKED | ZONED | FLOAT | EFORMAT}
{LEN {n | UNKNOWN} | BITS n | DIGITS n
| TO position}
[DP {k | *}] [BP n] [SIGNED | UNSIGNED]
[PAD {BLANK | character | NULL}] [STRIP | NOSTRIP]
[ALIGN]
[JUSTIFY {LEFT | RIGHT}]
[INITIAL {BLANK | ZERO | NULL | value}]
[AFTER {itemname | arrayname}
| AT {position | itemname | imagename1 | arrayname}]
[OCCURS {n [DEPENDING ON {itemname | %variable}]
| UNKNOWN}]


===JUMP TO===

JUMP TO label

JUMP TO (label1 [, label2] ...) expression

===[[Loop End statement|Loop End]]===

[[Loop End statement|Loop End]] 

===[[Loop Next statement|Loop Next]]===

[[Loop Next statement|Loop Next]]

===MAX PFKEY===
MAX PFKEY n 

===[[Menu statement or block|Menu]]===
<table class="noBorder">
<tr>
<td>{{Template: Menu statement syntax}} </td></tr>
</table>

===MODIFY===

MODIFY {%menuname:itemname | %screenname:itemname}
[TO] attributes [[FOR] {ALL | READ | REREAD | TAB
| PRINT}]


===MODIFY BUFFER===

MODIFY BUFFER [SIZE=n
| %variable [PRESERVE | NOPRESERVE]]
[FILL [X'nn'] | CLEAR]


===NEW PAGE===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(C)]] </td>
<td>NEW PAGE </td></tr>
</table>

===[[Note statement|Note]]===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td>
<td>Note {fieldname [(subscript)]} </td></tr>
</table>
Note 'string'


===[[On statement|On]]===

[[On statement|On]] {Attention | Error | Field Constraint Conflict
| Find Conflict | Missing File | Missing Member
| Record Locking Conflict}
statements
End On [label]


===Open===

{{Template:Open (External I/O) statement syntax}}

 
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(C)]] </td>
<td>{{Template:Open and OpenC statements syntax}} </td></tr>
</table>

===OPEN PROCESS===

OPEN PROCESS {processname | %variable}
[CID {name | %variable}] 

<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td>
<td>OPEN PROCESS {processname | %variable} [CID {name | %variable}] {outbound-options | inbound-options}
</td></tr>
</table>

<div style="margin-left: 30px; background-color: #fBfBfB;">

where <var class="term">outbound-options</var> are:
<ul style="font-family: Consolas,monospace">
<li>[AT DESTINATION] [WITH] [USERID {%variable | 'string'}]

<li>[PASSWORD {%variable | 'string'}]

<li>[{ACCOUNT | PROFILE {%%variable | 'string'}]

<li>[INITIAL {DATA 'string' | DATA %variable | IMAGE imagename] ...]
</ul>

and <var class="term">inbound-options</var> are:

<ul style="font-family: Consolas,monospace">
<li>ACCEPT [INITIAL {DATA %variable | IMAGE image} ...] </li>
</ul>

</div> 

===[[Pause statement|Pause]]===

{{Template:Pause statement syntax}}

===PLACE RECORD ON===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td>
<td>[[Lists#PLACE RECORD and REMOVE RECORD statements|PLACE RECORD ON]] [LIST] listname
</td></tr>
</table>

===PLACE RECORDS===

PLACE RECORDS {IN label | ON [LIST] listname1} ON [LIST] listname2


===Position===

POSITION {FOUNDSET foundsortset_name | LIST list_name} [AT] position_name

Note: Use the above form of the <var>Position</var> statement with <var>For</var> loop processing; see [[Global features#Position statement|Position statement]].

POSITION {ext-filename | %variable}
AT KEY operator{value | %variable}

Note: Use the above form of the <var>Position</var> statement with external file processing using images; see [[Images#Position statement|Position statement]].

===[[Full-screen feature|PREPARE]]===

PREPARE
{[[[Images#PrepareStmtImage|IMAGE]]] imagename | [[[Full-screen feature#PrepareStmtMenu|MENU]]] menuname
| [[[Full-screen feature#PrepareStmtScrn|SCREEN]]] screenname}


===Print===

Print [[#Print specification syntax|printSpecifications]] 

===Print All Fieldgroup Information (PAFGI)===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td>
<td>{{Template:PAFGI statement syntax}} </td></tr>
</table>

===[[Print All Information statement|Print All Information]] or [[PAI statement|PAI]]===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td>
<td>{{Template:PAI statement syntax}} </td></tr>
</table>

===PRINT MENU===

PRINT [MENU] menuname [ALERT]
[TITLE {'text' | %variable} [AT [COLUMN] n]
[TO [COLUMN] m | LEN m] [attributes]]


===PRINT SCREEN===

PRINT SCREEN screenname [ALERT] [[WITH] CURSOR]
[TITLE {'text' | %variable} [AT [COLUMN] n]
[TO [COLUMN] m | LEN m] [attributes]]


===[[Horizon SOUL interface#Query Process statement|Query Process]]===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td>
<td>{{Template:Query Process statement syntax}} </td></tr>
</table>

===[[Read Image statement|Read Image]]===

{{Template:Read Image statement syntax}}

===READ menuname===

READ [MENU] menuname [ALERT]
[TITLE ['text' | %variable} [AT [COLUMN] n]
[TO [COLUMN] m | LEN m] [attributes]]


===READ screenname===

READ [SCREEN] screenname [ALERT] [NO REREAD] [ [WITH] CURSOR]
[TITLE {'text' | %variable} [AT [COLUMN] n]
[TO [COLUMN] m | LEN m] [attributes]]


===RECEIVE IMAGE===

RECEIVE {IMAGE imagename | %variable}
FROM {cid | processname | %variable} [RESULT %variable] 

<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td>
<td>RECEIVE {IMAGE imagename | %variable} FROM {cid | processname | %variable} RESULT %variable
</td></tr>
</table>

===[[Release All Records statement|Release All Records]]===

{{Template:Release All Records statement syntax}}

===[[Release Imagine Records statement|Release Imagine Records]]===

{{Template:Release Imagine Records statement syntax}}

===[[Release Position statement|Release Position]]===

<table class="noBorder">
<tr><td>{{Template:Release Position statement syntax}} </td></tr>
</table>

===[[Release Records statement|Release Records]]===

{{Template:Release Records statement syntax}}

===[[Remember statement|Remember]]===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td>
<td>{{Template:Remember statement syntax}}</td></tr>
</table>

===REMOVE RECORD FROM===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(**)]] </td>
<td>[[Lists#PLACE RECORD and REMOVE RECORD statements|REMOVE RECORD FROM]] [LIST] listname
</td></tr>
</table>

===REMOVE RECORDS===

REMOVE RECORDS {IN label | ON [LIST] listname}
FROM [LIST] listname2


===REPEAT===

REPEAT [FOREVER | n TIMES | WHILE expression]


===REREAD===

REREAD [SCREEN] screenname [ALERT] [[WITH] CURSOR]
[TITLE {'text' | %variable} [AT [COLUMN] n]
[TO [COLUMN] m | LEN m] [attributes]]


===RESET===

RESET {HEADER | TRAILER} m


===[[Exceptions#Rethrow statement|Rethrow]]===

{{Template:Rethrow statement syntax}}

===RETRY===

RETRY [PENDING STATEMENT]


===RETURN===

RETURN


===[[Screen statement or block|Screen]]===

{{Template:Screen statement syntax}}

===SEND===

SEND {IMAGE imagename | 'string' | %variable}
TO {cid | processname | %variable}
[REQSEND %variable]
[FLUSH]

(+)SEND {IMAGE imagename | 'string' | %variable}
TO {cid | processname | %variable}
[FLUSH | CONFIRM]
[REQSEND %variable]


===[[Horizon SOUL interface#Send Error statement|Send Error]]===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td>
<td>{{Template:Send Error statement syntax}} </td></tr>
</table>

===SET===

SET {HEADER | TRAILER} m [[#Print specification syntax|print-specifications]]


===[[SetText statement|SetText]]===

{{Template:SetText statement syntax}}

===SIGNAL PROCESS===

SIGNAL PROCESS
{cid | [processname | %variable} {nnn | %variable} 

<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td>
<td>SIGNAL PROCESS {cid | [processname | %variable}
</td></tr>
</table>

===[[Sirius Case statement|Sirius Case]] directive===

<table class="noBorder">
<tr><td style="font-family:monoface; padding:0px">[[Statement syntax#Notation conventions|(C)]] </td>
<td>{{Template:Sirius Case statement syntax}} </td></tr>
</table>

===SKIP LINES===

SKIP n LINE[S]


===[[Skip Position statement|Skip Position]]===

<table class="noBorder">
<tr><td>{{Template:Skip Position statement syntax}} </td></tr>
</table>

===SORT RECORDS===

SORT [k] RECORDS {IN label | ON [LIST] listname}
BY key [AND key] ...


<div style="margin-left: 20px; background-color: #fBfBfB;">

where <var class="term">key</var> is:
<ul style="font-family: Consolas,monospace">
<li>key = fieldname 
[VALUE {[ASCENDING | DESCENDING] 
[CHARACTER | NUMERICAL] | RIGHT-ADJUSTED]} ...] </li>
</ul>

</div> 

===SORT RECORD KEYS===

SORT [k] RECORD KEYS
{IN label | ON [LIST] listname}
BY key [AND key] ...


<div style="margin-left: 20px; background-color: #fBfBfB;">

where <var class="term">key</var> is:
<ul style="font-family: Consolas,monospace">
<li>key = fieldname 
[VALUE {[ASCENDING | DESCENDING] 
[CHARACTER | NUMERICAL] | [RIGHT-ADJUSTED]} ...] </li>
</ul>

</div>

===SORT VALUE IN===

SORT VALUE IN label [IN [ASCENDING | DESCENDING]
[CHARACTER | NUMERICAL] | [RIGHT-ADJUSTED] ORDER]


===STOP===

<table class="noBorder">
<tr>
<td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(C)]]</td>
<td>STOP [IF COUNT IN label EXCEEDS n]
</td></tr>
</table>

===STORE RECORD===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(*)]] </td>
<td>STORE RECORD [sort or hash key value] fieldname1=[value1 | (expression1)] [fieldname2=(expression)] ... [THEN CONTINUE statement statement ...] END STORE
</td></tr>
</table>

===SUBROUTINE===

SUBROUTINE

SUBROUTINE subname
[(formal-parameter [INPUT | OUTPUT | INPUT OUTPUT] [,...])]


<div style="margin-left: 20px; background-color: #fBfBfB;">

where <var class="term">formal-parameter</var> is one of the following:
<ul style="font-family: Consolas,monospace">
<li>%variable [IS STRING [LEN n] [DP {n | *}] [ARRAY (*[,*[,*]]) [NO FS]] 
| IS {FIXED [DP n] | FLOAT} [ARRAY (*[,*[,*]])]]

<li>LIST listname [IN [FILE | [PERM | TEMP] GROUP] name]
</ul>
</div>

===TAG===

TAG %screenname:inputname [attributes] [WITH 'c']


===[[Horizon SOUL interface#Test Receipt statement|Test Receipt]]===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td>
<td>{{Template:Test Receipt statement syntax}} </td></tr>
</table>

===TITLE===

TITLE {'text' | promptname}
[AT [COLUMN] n] [TO [COLUMN] m | [LEN m]
[DP {k | *}]]
[DEFAULT 'value']
[[READ] attributes] [REREAD attributes] [PRINT attributes]


===[[Trace statement|Trace]]===

{{Template:Trace statement syntax}}

Note: The output of the <var>Trace</var> statement is controlled by the <var>[[ULTRACE parameter|ULTRACE]]</var> parameter.

===[[Program Communication facilities#TRANSFER statement format and execution|TRANSFER]]===

TRANSFER [CONTROL] TO PROCESS {processname | %variable}
[WITH] [USERID {string | '%variable'}]
[PASSWORD {variable | 'string'}]
[ACCOUNT {%variable | 'string'}]
[PASSING {IMAGE imagename | 'string' | %variable}]


===UPDATE RECORD===

UPDATE RECORD

===VARIABLES ARE===

VARIABLES ARE
{FIXED [DP n] | FLOAT
| STRING [LEN n] [DP {n | *}]
| UNDEFINED}


===Declare %variable===

[DECLARE] %variable [IS]
{FIXED [DP n] | FLOAT} [ARRAY (d1[,d2[,d3]])]
[COMMON]

[DECLARE] %variable [IS]
STRING [LEN n] [DP {n | *}] [ARRAY (d1[,d2[d3]])]
[NO FIELD SAVE] [COMMON]
%variable [(subscript)] = expression


===WAIT===
<table class="noBorder">
<tr><td style="font-family:monoface; padding-right:0px">[[Statement syntax#Notation conventions|(+)]] </td>
<td>WAIT [{n | %variable} SEC[S]] [FOR] {ANY RECEIPT RETURN %variable | RECEIPT {cid | processname | %variable}}
</td></tr>
</table>

===[[Write Image statement|Write Image]]===

<table class="noBorder">
<tr><td>{{Template:Write Image statement syntax}} </td></tr>
</table>

==Other syntax==

===Names, numbers, literals, comments===

<ul>
<li>Names (for example, %variables, labels): see [[Model 204 naming conventions]]
<li>Other constructs: see [[Basic request structure]] (which also discusses some rules for statement labels)
</ul>

===Value specification syntax===

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:
<ul>
<li>Literal number or string </li>
<li><var>VALUE IN</var> clause of the form:
VALUE [IN] label

</li>
<li>%variable</li>
</ul>

===Retrieval condition syntax===

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.

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 (()):

[Not] phrase [{And | Or | Nor} [Not] phrase] ...


Where: 

<var class="term">phrase</var> can be constructed from these options: 
<ul style="font-family: Consolas,monospace">
<li><var class="term">fieldname</var> = [Not] value </li>

<li><var class="term">fieldname</var> Like pattern </li>

<li><var class="term">fieldname</var> Is [Not] {Present | Like 'pattern'} </li>

<li><var class="term">fieldname</var> Is [Not] {[Numerically | Alphabetically] 
[Eq | = | Ne | ¬= | Greater Than | Gt | > | Less Than | Lt | < | Le | <= | Ge | >= | Before | After] value} </li>

<li><var class="term">fieldname</var> Is [Not] {[Numerically | Alphabetically] 
{In Range [From | After] value1 {To | [And] Before} 
value2 | Between value1 And value2} </li>

<li>[[Record retrievals#FILE$ condition|File$]] {filename | =} </li>

<li>Find$ <var class="term">label</var> </li>

<li>[[Lists#Using the LIST$ condition|List$]] listname </li>

<li>[[Record retrievals#LOCATION$ condition|Location$]] {location | =} </li>

<li>[[#Point$|Point$]] <var class="term">value</var> </li>

<li>[[#Sfl$ and Sfge$|Sfge$]] <var class="term">value</var> </li>

<li>[[#Sfl$ and Sfge$|Sfl$]] <var class="term">value</var> </li>
</ul>

where <var class="term">value</var> can be: 
<ul>
<li>A literal number or string</li>

<li>A %variable </li>

<li><var>Value</var> {([[#Use of expressions|expression]]) | [<var>In</var>] label}

<var class="term">label</var> points to an existing value set. If an <var>Eq Value In value_set</var> clause, value set values are treated as Boolean OR, for example:

field = value1 OR field = value2 OR.... 

If an <var>Ne Value In value_set</var> clause, values are treated as Boolean AND: 
field <> value1 AND field <> value2 AND.... 

See also [[Basic SOUL statements and commands#Processing a VALUE IN clause|Processing a VALUE IN clause]].</li>
</ul>

Notes:
<ul>
<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>

<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>

<li>In addition to the discussions in the subsections that follow, see [[Record retrievals]] for a comprehensive description of retrieval conditions. </li>
</ul>

====Omitting repeated first words====

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:
List$ A And Not List$ B


can be written:
List$ A And Not B


And:
x Is 13 Or x Is Less Than 7


can be written:
x Is 13 Or Is Less Than 7


====Omitting duplicated equal signs====

Duplicated equal signs can be omitted. For example, the expression:
a = 3 Or a = 5 Or a = 40


is equivalent to:
a = 3 Or 5 Or 40


====Use of parentheses====

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:
Not (a = 2 Or List$ y)
a = 1 And (b = 2 OR c = 3)


====Use of expressions====

[[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: 

=====Point$=====
Point$ Value(expression)

Where:

<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>. 

Example: 

This example finds the first <code>MA</code> record on file, and then counts the number of records from this point in the file:
FD1:

IN ICSCUST FPC STATE = MA
END FIND
FOR 1 RECORD IN FD1
PRINT 'CURREC = ' WITH $CURREC
PRINT '>= POINT$'
FD2:
IN ICSCUST FPC POINT$ VALUE($CURREC)
END FIND
END FOR


=====Sfl$ and Sfge$=====
Sfl$ Value(expression)


Or:
Sfge$ Value(expression)

Where:

<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>. 

Example:

FOR %CT FROM 1 TO 10
IN EXPRESS STORE RECORD ($EDITN(%CT,'999'))
ORD1 = (%REC WITH %CT)
ORD2 = (%CT * 2)
ORD4 = (%CT * 4)
END STORE
END FOR
COMMIT
FOR %CT FROM 1 TO 5
PRINT 'LESS THAN ' WITH %CT
FD1:
IN EXPRESS FPC SFL$ VALUE($EDITN(%CT,'999'))
END FIND
PRINT 'GREATER THAN OR EQUAL TO ' WITH %CT
FD2:
IN EXPRESS FPC SFGE$ VALUE($EDITN(%CT,'999'))
END FIND
END FOR


=====Eq Value=====
fieldname Eq Value(expression)

Where:

<var class="term">expression</var> is a function call, string concatenation, arithmetic operation, SOUL construct, or Boolean expression. 

Example:

FD: IN FILE PEOPLE FD
LAST EQ VALUE($READ('LAST NAME?') )
END FIND


===Print specification syntax===

A <var>Print</var>, <var>Set</var>, <var>Audit</var>, or <var>Trace</var> statement contains print specifications of the following form:

[term] [And | Tab | With]...[[term] [And | Tab | With] ...] ... [...]

Where:

<var class="term">term</var> can be constructed as follows:
{'string' | %variable | Count In label | Occurrence In label | Value in term | function}
[At [Column] m] [To [Column] n] 

Or, if the statement is within a record loop:

{{Each | term} fieldname | *Record | *Id}
[At [Column] m] [To [Column] n}


Note: 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 n]] statements for fields. 

===Expression syntax===

The following syntax can be used in: 
<ul>
<li>Assignment statements </li>
<li>Conditional <var>If</var> statements and <var>ElseIf</var> clauses

In the simplified syntax for an <var>If</var> statement, which is:
If condition Then statements


<var class="term">condition</var> expands to the syntax described in this section. </li>

<li>Computed <var>Jump To</var> statements </li>

<li>Subscripts </li>

<li>Function arguments </li>

<li>A value in parenthesis in SOUL "DML" statements, for example:
Add <var class="term">fieldname</var> = (<var class="term">expression</var>)
</ul>

=====Syntax=====
{operand | (expression)} [operator {operand | (expression)}] ...

Where:
<ul>
<li><var class="term">operand</var> can be constructed as follows:
[+ | - | Not]
{'string' | %variable | number
| fieldname [(subscript)] Is [Not] Present
| Count In label | Occurrence In label
| Value In label
| function}
</li>

<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>

<li><var class="term">operator</var> may be one of the following:
<table style="table-layout: fixed">
<tr>
<td>+   </td>
<td>=</td>
<td>EQ</td>
<td>And</td>
</tr>

<tr>
<td>-</td>
<td>,=   </td>
<td>NE  </td>
<td>AndIf</td>
</tr>

<tr>
<td>*</td>
<td>></td>
<td>GT</td>
<td>Or</td>
</tr>

<tr>
<td>/</td>
<td><</td>
<td>LT</td>
<td>OrIf</td>
</tr>

<tr>
<td> </td>
<td>>=</td>
<td>GE</td>
<td>With (Note: this can also be achieved via [[Implicit concatenation]])</td>
</tr>

<tr>
<td> </td>
<td><=</td>
<td>LE</td>
<td>Is [Not] Present (Note: applied either to a field or to an [[Methods#optionalParams|optional or default method parameter]])</td>
</tr>

<tr>
<td> </td>
<td> </td>
<td> </td>
<td>Is [Not] Like</td>
</tr>
</table>
<blockquote class="note">Notes:
<ul>
<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>

<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>

<li>The <var>AndIf</var> and <var>OrIf</var> operators are called "short circuit", because, at a given precedence level, if the value of the conditional expression has been fully determined, the remainder at that level is not evaluated. For example:
%sex eq 'M' and (%ht lt 5.2 orIf %ht gt 6.5)
If the value of <code>%ht</code> is less than 5.2, the final comparison -- <code>%ht gt 6.5</code> -- is never evaluated (that holds regardless of what had been coded as the final comparison).
With the same value of <code>%ht</code>, if the <code>Or</code> operator had been used, then that final comparison is always evaluated.
</li>
<li>For more information about operators, see [[Using variables and values in computation#Operators|Operators]]. </li>
</ul>
</blockquote ></li>
</ul>

===In clause syntax===

The SOUL statements on this page whose syntax display is preceded by an asterisk (<tt>*</tt>) support an <var>In</var> clause. 

The three basic forms of the <var>In</var> clause are: 

In [Permanent | Temporary ] Group groupname
Member [%member | [filename [At {location | =}]]

In file1 [,file2] ...

In {$Curfile | $Update}

The form <var>In $Curfile</var> can be used only within a record loop.

====In Group Member limitations====

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:
<ul>
<li><var>Clear List</var></li>

<li><var>Find All Records</var> (and its variants)</li>

<li><var>Find All Values</var></li>

<li><var>For Record Number</var> (or <var>FRN</var>)</li>

<li><var>Store Record</var> </li>
</ul>

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.

====Using an In clause in a Begin...End block====

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. 

===Subscript syntax===

A subscript has the format: 

=====Syntax=====
(subscript1 [,subscript2 [,subscript3]] )

Where:

<var class="term">subscript1</var>, <var class="term">subscript2</var>, and <var class="term">subscript3</var> can be any expression. 

==SOUL macros==
There are [[SOUL macro facility|additional facilities]] supporting <var class="product">SOUL</var>
macro statements. Macro statements allow code to be conditionally compiled.

As an example, in the following SOUL fragment, the <var>Recordset</var> object declaration would be for the file <code>AVEBURY</code>:
!def henge avebury
...
%sites is object recordset in file ?!HENGE


==Terminal display attributes==

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:

<table>
<caption>List of attributes</caption>
<tr>
<td>BLINK</td>
</tr>
<tr>
<td>BLUE</td>
</tr>
<tr>
<td>BRIGHT</td>
</tr>
<tr>
<td>DIM</td>
</tr>
<tr>
<td>GREEN</td>
</tr>
<tr>
<td>INV[IS[BLE]] </td>
</tr>
<tr>
<td>NOBLINK</td>
</tr>
<tr>
<td>NOREV[ERSE]</td>
</tr>
<tr>
<td>NOU[NDER]SCORE</td>
</tr>
<tr>
<td>PINK</td>
</tr>
<tr>
<td>PROT[ECTED]</td>
</tr>
<tr>
<td>RED</td>
</tr>
<tr>
<td>REV[ERSE]</td>
</tr>
<tr>
<td>TURQUOISE</td>
</tr>
<tr>
<td>[UNDER]SCORE</td>
</tr>
<tr>
<td>UNPROT[ECTED]</td>
</tr>
<tr>
<td>VIS[IBLE]</td>
</tr>
<tr>
<td>WHITE</td>
</tr>
<tr>
<td>YELLOW </td>
</tr>
</table>

==Notation conventions==

This page uses the following syntax notation conventions: 

<table>
<tr class="head">
<th>Syntax notation </th>
<th>Indicates that...</th>
</tr>

<tr>
<td>Single asterisk (*) </td>
<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>
</tr>

<tr>
<td>Two asterisks (**) </td>
<td>Construct can appear only within a record loop.</td>
</tr>

<tr>
<td>Plus sign (+) </td>
<td>Construct requires the optional [[Horizon]] feature.</td>
</tr>

<tr>
<td nowrap>Two plus signs (++) </td>
<td>Construct requires the optional User Language to Database 2 feature.</td>
</tr>

<tr>
<td>C</td>
<td>The (first) keyword of the statement is also a <var class="product">Model 204</var> command; the command's wiki page will be, for example, 'OPEN command'.

<var class="product">Model 204</var> commands are listed alphabetically and documented in [[List of Model 204 commands]]. </td>
</tr>

<tr>
<td>Lowercase italic </td>
<td>Constructs are replaced with variable information.</td>
</tr>
</table>

<ul>
<li>A field name (%%) variable can be used anywhere fieldname appears. The %%variable can contain its own subscript, separate from the field name subscript.
Note: 
The subscript of an array element must be specified before a field name subscript. </li>

<li>The lowercase constructs — retrieval-conditions, print-specifications, expression, subscript, attribute, and type — are discussed separately following the syntax summaries, beginning with [[#Value specification syntax|Value specification syntax]]. </li>

<li>For more Model 204 notation conventions, see [[Notation conventions]].</li>
</ul>

[[Category:SOUL]]

Template:Release Imagine Records statement syntax

2025-09-05T18:51:34Z

Alex:

[[Record level locking and concurrency control#Release Imagine Records statement|Release Imagine Records]] [Backout | Commit]

Template:Release Imagine Records statement syntax

2025-09-05T18:48:55Z

Alex: Created page with "Release Imagine Records"

[[Record level locking and concurrency control#Release Imagine Records statement|Release Imagine Records]]

Regex processing

2025-09-04T14:10:34Z

Alex: /* Look-around subexpressions */

<var class="product">SOUL</var> includes support for '''regular expression'''
("regex") processing in multiple $functions and O-O methods.
This support is modeled closely on Perl's regular expression implementation.

==Overview==
SOUL $functions and methods offer the following variety of tasks you
can accomplish using a regex.
<ul>
<li>Simple matching:
<ul>
<li>You can determine whether and where a single regex pattern
matches within a single input string.
See the <var>[[RegexMatch (String function)|RegexMatch]]</var> and <var>[[UnicodeRegexMatch (Unicode function)|UnicodeRegexMatch]]</var> intrinsic functions. </li>

<li>You can apply a single regex to a <var>Stringlist</var> to find one item. See the <var>[[RegexLocate and RegexLocateUp (Stringlist functions)|RegexLocate]]</var> and
<var>[[RegexLocate and RegexLocateUp (Stringlist functions)|RegexLocateUp]]</var> <var>Stringlist</var> functions. </li>

<li>You can apply a single regex to a <var>Stringlist</var> to find all
matching items and place them on a <var>Stringlist</var>.
See the <var>[[RegexSubset (Stringlist function)|RegexSubset]]</var> <var>Stringlist</var> function. </li>
</ul></li>

<li>Capturing:
<ul>
<li>You can append to a <var>Stringlist</var> the characters in an input string that are matched by regex capturing groups.
See the <var>[[RegexCapture (Stringlist function)|RegexCapture]]</var> <var>Stringlist</var> function. </li>
</ul></li>

<li>Searching and replacing:
<ul>
<li>You can replace the matched characters in a single
input string with a specified string, one or many times.
See the <var>[[RegexReplace (String function)|RegexReplace]]</var> and <var>[[UnicodeRegexReplace (Unicode function)|UnicodeRegexReplace]]</var> intrinsic functions. </li>

<li>You can find the characters in a single string
that are matched by one of a set (<var>Stringlist</var>) of regexes, and replace
the matched characters with a string from a corresponding set (<var>Stringlist</var>).
See the <var>[[RegexReplaceCorresponding (Stringlist function)|RegexReplaceCorresponding]]</var> <var>Stringlist</var> function. </li>
</ul></li>

<li>Splitting:
<ul>
<li>You can use a regex repeatedly to separate a given input string
into the substrings that are
matched by the regex and the substrings that are not matched, and
append to a Stringlist either or both of these sets of substrings
(in combination or not with the subset of matched substrings
that are captured.
See the <var>[[RegexSplit (Stringlist function)|RegexSplit]]</var> <var>Stringlist</var> function.
and <var>[[RegexSplit (String function)|RegexSplit]]</var> intrinsic <var>String</var> function. </li>
</ul></li>
</ul>

Many tools implement regular expressions, each with its own variation
of supported features.
The following sections describe the SOUL regex support.
<ul>
<li>[[#Regex rules|Regex rules]] discusses the symbols and grammar of SOUL regex. </li>

<li>[[#Common regex options|Common regex options]] and [[#XML Schema mode|XML Schema mode]] discuss options that modify the
interpretation of a specified regex, which are available to some or all of the SOUL regex $functions and methods. </li>

<li>[[#SOUL programming considerations|SOUL programming considerations]] discusses aspects of using regex in SOUL programs. </li>
</ul>

===Distinction from SOUL Is Like pattern matching===
The use of regex processing conforms to the common matching processing provided in contemporary languages such as Perl, PHP, Python, Java, and so on. In addition to this, several constructs in SOUL, such as the <var>Find</var> and <var>If</var> statements, provide a pattern matching construct using an <var>Is Like</var> clause. The rules for <var>Is Like</var> are discussed in the syntax for [[Is Like pattern matching#likeSyntax|Is like patterns]].

==Regex rules==
When a regular expression is said to "match a string," what is meant is
that a substring of characters within the string
fit (are matched by) the pattern specified by the regex.
The "rules" observed by SOUL for regex formation and matching
are primarily those followed
by the Perl programing language (as described, for example, in
''Programming Perl'', by Larry Wall et al,
published by O'Reilly Media, Inc.; 3rd edition, July 14, 2000).
An additional reference is
''Mastering Regular Expressions'', by Jeffrey E. F. Friedl,
published by O'Reilly Media, Inc. (2nd edition, July 15, 2002).
In terms of the type of regex engine described in this book, the Model 204
regex processing is considered NFA (not DFA, and not POSIX NFA).

Highlights of the SOUL regex support are discussed in the following
subsections, especially noting where SOUL rules differ from Perl's.
If a regex feature is not mentioned below, you should assume it is supported by SOUL to the extent that it is supported in Perl.

===Online web resources; regex character set===
A Google search of 'regex' will yield many pages, and you will find some that are well suited to your task; it is difficult to provide a "one size fits all" recommendation.

However, here is one link that provides a one-page illustration of regex features, with extremely brief indications of their purpose:

http://web.mit.edu/hackl/www/lab/turkshop/slides/regex-cheatsheet.pdf

And here is a clip from that page (as of January 24, 2019) listing the characters which have special meaning in regex (any other character in a regex matches the character itself):

Special characters
<ul>
<li>The following 6 characters
{}[]()
<li>and the following 8 characters
^$.|*+?\
<li>and <code>-</code> inside <code>[</code>...<code>]</code>
</ul>
have special meaning in regex, so they
must be "escaped" with <code>\</code> to match them.
Ex: <code>\.</code> matches the period <code>.</code> and
<code>\\</code>
matches the
backslash <code>\</code>


The above 15 metacharacters are those that can be escaped in Model 204 regex, as described in the [[#esc|table below]].

===Expression constituents===
This section describes elements that constitute the actual expression pattern.
The next section describes features that modify or affect a specified pattern.
These sections describe the default case where the optional
[[#XML Schema mode|XML Schema mode]] processing is ''not'' in effect.

These features are discussed:
<ul>
<li>[[#Escape sequences|Escape sequences]]
<li>[[#Character classes|Character classes]]
<li>[[#Greedy and non-greedy quantifiers|Greedy and non-greedy quantifiers]]
<li>[[#Capturing groups|Capturing groups]]
<li>[[#Look-around subexpressions|Look-around subexpressions]]
<li>[[#Alternatives|Alternatives]]
</ul>

====Escape sequences====
The only escape sequences allowed in a Model 204 regex are those
for metacharacters
and those that are "shorthands" for special characters or character classes, as specified below.

These metacharacter escapes are allowed in regex arguments:

<table class="thJustBold">
<tr>
<th valign="top">\ .</th>
<td>Period (or dot); see [[#Mode modifiers|Mode modifiers]] for difference from Perl on what is matched by an un-escaped period
</td></tr>

<tr>
<th>\ [</th>
<td>Left square bracket
</td></tr>

<tr>
<th>\ ]</th>
<td>Right square bracket
</td></tr>

<tr>
<th>\ (</th>
<td>Left, or opening, parenthesis
</td></tr>

<tr>
<th>\ )</th>
<td>Right, or closing, parenthesis
</td></tr>

<tr>
<th>\*</th>
<td>Star, or asterisk
</td></tr>

<tr>
<th>\ -</th>
<td>Hyphen
</td></tr>

<tr>
<th>\ {</th>
<td>Left curly bracket
</td></tr>

<tr>
<th nowrap>\ }</th>
<td>Right curly bracket
</td></tr>

<tr>
<th>\ |</th>
<td>Vertical bar
</td></tr>

<tr>
<th>\\</th>
<td>Backslash
</td></tr>

<tr>
<th>\+</th>
<td>Plus sign
</td></tr>

<tr>
<th>\?</th>
<td>Question mark
</td></tr>

<tr>
<th>\$</th>
<td>Dollar sign
</td></tr>

<tr>
<th valign="top">\^</th>
<td>Caret, or circumflex
'''Note:''' A caret is used in this documentation to represent the character that the keyboard program translates to X'5F'; this may be a not sign (<tt>¬</tt>) on your system.</td></tr>
</table>

These character shorthands are allowed:
<table class="thJustBold">
<tr><th>\n</th>
<td>Linefeed (X'25')
</td></tr>

<tr><th>\r</th>
<td>Carriage return (X'0D')
</td></tr>

<tr><th>\t</th>
<td>Horizontal tab (X'05')
</table>

These class shorthands are allowed:
<table class="thJustBold">
<tr><th valign="top">\b</th>
<td>Word boundary anchor (a position between a \w character and a non-\w character) — but not supported as a backspace character or within a character class.</td></tr>

<tr><th valign="top">\B</th>
<td>The inverse of \b: any position that is not a word boundary anchor.
</td></tr>

<tr><th valign="top">\c</th>
<td>Legal name character; equivalent to <code>[\-_:.A-Za-z0-9]</code>
</td></tr>

<tr><th valign="top">\C</th>
<td>Non-legal name character; equivalent to <code>[^\-_:.A-Za-z0-9]</code>
</td></tr>

<tr><th valign="top">\d</th>
<td>Digit; equivalent to <code>[0-9]</code>
</td></tr>

<tr><th valign="top">\D</th>
<td>Non-digit; equivalent to <code>[^0-9]</code>
</td></tr>

<tr><th valign="top">\i</th>
<td>Legal start-of-name character; equivalent to <code>[_:A-Za-z]</code>
</td></tr>

<tr><th valign="top">\I</th>
<td>Non-legal start-of-name character; equivalent to <code>[^_:A-Za-z]</code>
</td></tr>

<tr><th valign="top">\s</th>
<td>Whitespace character; equivalent to <code>[ \r\n\t]</code>
</td></tr>

<tr><th valign="top">\S</th>
<td>Non-whitespace; equivalent to <code>[^ \r\n\t]</code>
</td></tr>

<tr><th valign="top">\w</th>
<td>Any letter (uppercase or lowercase), any digit, or the underscore.
</td></tr>

<tr><th valign="top">\W</th>
<td>The inverse of \w: any non-letter or non-digit except the underscore.
</td></tr>
</table>

====Character classes====
In character classes (which "match any character in the square
brackets"):
<ul>
<li>The only ranges allowed are subsets of uppercase letters,
lowcase letters, or digits.
For example, <code>[A-z]</code> is
'''not''' legal; <code>[A-Za-z]</code> '''is''' legal; <code>[a-9]</code>
is '''not''' legal.

Because of the gaps in the EBCDIC encoding, you can specify <code>[A-Z]</code>,
but internally that is converted to <code>[A-IJ-RS-Z]</code>;
and similarly for <code>[a-z]</code>. </li>

<li>Multi-character escape sequences
(for example, <code>\s</code>, <code>\c</code>)
are allowed within character classes.
However, they are '''not''' allowed as either side in a range. </li>

<li>An unescaped hyphen (<code>-</code>) is allowed
if it occurs as the first character (or the second, if the first
is <code>^</code>) or as the last character in a character class expression.
An escaped hyphen (<code>\-</code>) is allowed in all positions.

All the following are allowed: 
[-A-Z158]
[^-A-Z158]
[158A-Z-]
[158A-Z0-]


But <code>[A-F-K]</code> is '''not''' allowed.
And a hyphen is not allowed as the left or right character
in the range expression itself
(<code>["--]</code>, for example, is '''not''' allowed). </li>

<li>Some bracket characters (<code>[</code> or <code>]</code>,
from any of the several character codes that produce a left or right square bracket in EBCDIC) do not have to be escaped.
A bracket character does ''not'' require a preceding escape character if it is:
<ul>
<li>A right bracket (<code>]</code>) that is outside of, not part of,
a character class expression.
So, <code>(1]9)</code> matches <code>0001]9zzz</code>. </li>

<li>A right bracket that is the first character — or
the second, if the first is a caret (<code>^</code>) —
in a character class expression.
So, <code>[]xxx]</code> and <code>[^]xxx]</code> are legal. </li>

<li>A left bracket that occurs anywhere in a character class expression.
So, <code>[abc[]</code> is legal and matches any of these four
characters: <code>a b c [</code>

A left bracket that occurs outside of a character class expression must always be escaped. </li>
</ul></li>

Although not required, escape characters may be used in the cases cited above.
</ul>

====Greedy and non-greedy quantifiers====
Both greedy and non-greedy matching are supported.
That is, if there is more than one plausible match for a greedy quantifier
(<code>*</code>, <code>+</code>, <code>?</code>, <code>{min,max}</code>),
which govern how many input string characters the
preceding regex item may try to match), the longest one is selected.
In contrast, the non-greedy (aka "lazy")
quantifiers (<code>*?</code>, <code>+?</code>, <code>??</code>, <code>{min,max}?</code>)
select the minimum number of characters needed to satisfy a match.

For example, in SOUL methods and $functions, the regex <code><.+></code>
greedily matches
the entire input string <code><tag1 att=x><tag2 att=y><tag3 att=z></code>, although its set of plausible matches
also includes <code><tag1 att=x></code> and <code><tag2 att=y></code>.

The regex <code><.+?></code>, however, lazily matches just <code><tag1 att=x></code>,
the shortest of the plausible matches.
'''Note:'''
Since <code>??</code> is a <var class="product">Model 204</var> dummy string signifier,
you may need to use a SOUL expression such as
<code>'?' With '?'</code> if you want to use the <code>??</code> quantifier. 

Understanding greediness becomes more important when the string
that a regex matches is being replaced by another string. See the [[RegexReplace (String function)#greedy|greedy example]] for the <var>RegexReplace</var> function.

====Capturing groups====
<ul>
<li>Before Model 204 7.9 extraction of repeating capture groups from a string is
different in Perl and SOUL.
If there are multiple matches by a repeated group, Perl replaces each capture with the next one, ending up with only the final capture.
In Model 204 7.8 and earlier, SOUL saves each capture and concatenates them when finished.

For example, if this is the ''regex'': 
9([A-Z])*9


And this is the input string: 
xxx9ABCDEF9yyy


In both the <var class="product">SOUL</var> and Perl,
the "greedy quantifier" <code>*</code> matches as many times as it can,
stopping at the second <code>9</code>.
The resulting capture in SOUL $functions and methods is <code>ABCDEF</code>,
the concatenation of six one-character matches.
In Perl, the resulting capture is <code>F</code>. 

In Model 204 7.9, capturing group processing was changed to be consistent with Perl and pretty much all regular expression implementations. If one really wants or needs the old behavior, it can usually be achieved by embedding the entire repeated search string in parentheses. On can change the regex above to:

9([A-Z]*)9


and <code>ABCDEF</code> would be captured for string <code>"xxx9ABCDEF9yyy"</code>.

</li>

<li>A subexpression that is a validly formed capturing group
that is nested within a
non-capturing subexpression is still a capturing group.
The regex <code>(?:[1-9]*(a+))</code> matches <code>123aa</code> and
captures <code>aa</code>. </li>
</ul>

====Back references====

In Model 204 7.9, back references are supported. For example, the regular expression <code>(....)\1+</code> would match any string where there was a repetition of any two character pair so that in string <code>"My dog said bow-wow-wow-wow-wow!"</code> it would match <code>"-wow-wow-wow-wow"</code>.


====Look-around subexpressions====
Look-ahead and look-behind subexpressions are supported
as of Model 204 V7.9.

The supported parenthesized subexpression sequences that begin
with a question mark are the following, which are all non-capturing:
<table>
<tr><td>(?:</td>
<td>Denotes a non-capturing group</td></tr>
<tr><td>(?=</td>
<td>Denotes a positive look-ahead</td></tr>
<tr><td>(?!</td>
<td>Denotes a negative look-ahead</td></tr>
<tr><td>(?<=</td>
<td>Denotes a positive look-behind</td></tr>
<tr><td>(?<!</td>
<td>Denotes a negative look-behind</td></tr>
</table>

====Alternatives====
Alternatives (indicated by <code>|</code>) are evaluated from
left to right,
and evaluation is "short-circuited" (that is, it stops as soon as it finds a match).

Empty expressions, for example, empty alternatives, are supported.
The following regex matches <code>A9</code>, <code>B9</code>, and <code>9</code>,
capturing respectively <code>A</code>, <code>B</code>, and the null string:
(A|B|)9

An empty alternative (like the <code>|</code>, above, that is followed only by the closing parenthesis) is always True.

===Features that affect the whole expression===

====Unicode====
Unicode is supported by the <var>[[UnicodeRegexMatch (Unicode function)|UnicodeRegexMatch]]</var> and <var>[[UnicodeRegexReplace (Unicode function)|UnicodeRegexReplace]]</var> functions.

====Locales====
Locales are not supported.

====Mode modifiers====
Mode modifiers are settings that influence how a regex is applied.
SOUL mode modifiers apply to the entire regex; none can be applied to
part of a regex.
<ul>
<li>In SOUL regex, the dot (<code>.</code>) metacharacter matches any character except for a carriage return or linefeed.
'''Note:'''
In Perl, which does not consider a carriage return an end-of-line character,
a dot always matches a carriage return as well. 

To initiate dot-matches-all mode, in which dot matches '''any'''
character, Perl uses an <code>s</code> character after the regex-ending <code>/</code>.
SOUL regex $functions and methods have an "options" argument
that can initiate this mode (value <code>S</code>), as described
in [[#Common regex options|Common regex options]]. </li>

<li>Perl supports a case-insensitive matching mode
that you can apply globally (<code>i</code> after the regex-ending <code>/</code>) or partially
(started by <code>(?i)</code> and ended by <code>(?-i)</code>)) to a regex.
SOUL provides only a global case-insensitivity switch, which does
'''not''' use the Perl signifier.
Instead, SOUL uses an "options" argument
to initiate case-insensitive matching (value <code>I</code>), as described, below, in [[#Common regex options|Common regex options]]. </li>

<li>In multi-line mode, the caret (<code>^</code>) and
dollar sign (<code>$</code>) anchor characters may match a position wherever
a newline character occurs in the target string — they are not
restricted to matching only at the beginning and end of the string.
To enter this mode, Perl uses an <code>m</code> after the regex-ending <code>/</code>.
SOUL uses an "options" argument to initiate this mode (value <code>M</code>), as described, below,
in [[#Common regex options|Common regex options]]. </li>

<li>In Perl, comments may be included in a regex between the number sign (<code>#</code>) and a newline.
SOUL does not recognize this convention, and the number-sign character
is '''not''' a metacharacter. </li>
</ul>

==Common regex options==
SOUL regex $functions and methods have an optional "options" argument that
lets you invoke one or more operating modes that modify how the regex is applied.
In most cases, the functionality provided by the option is similar to
what Perl provides, but Perl uses a different notation to invoke it.

The options argument is a string of one or more of the following single-letter options.
Not all options are available to all regex $functions and methods.
— the individual $function and method descriptions list the
options available to that function or method.
<table class="thJustBold">

<tr><th>A</th>
<td>Replace as is (for methods and $functions that provide replacement substrings for matched substrings.

If this mode is specified, the replacement string is copied as is.
No escapes are recognized; a <code>$n</code> combination
is interpreted as a literal and '''not''' as a special marker;
and so on. </td></tr>

<tr><th>C</th>
<td>XML Schema mode. See, below, [[#XML Schema mode|XML Schema mode]]. </td></tr>

<tr><th>G</th>
<td>Global replacement of matched substrings (for methods and $functions that provide replacement substrings for matched substrings).

If this mode is '''not''' specified, a replacement string replaces the first matched substring only.
In G mode, every occurrence of the match is replaced. </td></tr>

<tr><th>I</th>
<td>Do case-insensitive matching between the input string(s) and the regex. Treat the uppercase and lowercase variants of letters as equivalent. </td></tr>

<tr><th>M</th>
<td>Multi-line mode. If this mode is '''not''' specified, a caret (<code>^</code>) or a not sign (<code>¬</code>) — whichever key your keyboard program translates to X'5F' — matches only the position at the very start of the string, and dollar sign (<code>$</code>) matches only the position at the very end. (This documentation uses the caret.)

The caret and dollar sign are position-identifying characters known
as "anchors," which match the beginning and end, respectively,
of a line or string. They do not match any text. 

In M mode, a caret '''also''' matches the position immediately
after any end-of-line indicator
(carriage return, linefeed, carriage-return/linefeed),
and a dollar sign '''also'''
matches the position immediately before any end-of-line indicator. 

M mode is ignored if option C (XML Schema mode) is also specified, since
caret and dollar sign are not metacharacters in C mode. </td></tr>

<tr><th>S</th>
<td>Dot-All mode. If this mode is '''not''' specified, a dot (<code>.</code>), also called a point, matches any single character except X'0D' (carriage return) and X'25' (linefeed). In Dot-All mode, a dot also matches carriage return and linefeed characters. </td></tr>

<tr><th>T</th>
<td>Trace regular expression evaluation. This option, available in Model 204 V7.9 and later, sends trace lines to the terminal, a USE dataset, and/or the audit trail for each atom (essentially, each step) of regular expression processing. This can be useful in determining why a regular expression is producing the results that it does and perhaps provide hints as to how performance of a particular regular expression can be improved.</td></tr>

</table>

==XML Schema mode==
An optional "options" argument lets you invoke XML Schema mode.
In this mode (not available in Perl),
the regex matching is done according to the rules for
regular expressions in the W3C XML Schema language specification
(the [http://www.w3.org/TR/xmlschema-2/#regexs Regular Expressions appendix] in Part 2 of the XML Schema recommenation).

This mode is designed for testing regexes for suitability for
validating strings in a schema document
(an XML document that constitutes an XML schema).
Although it is available in most of the SOUL regex $functions
and methods, it is intended primarily for matching and not for capturing
or replacing.

The SOUL regex rules described in [[#Regex rules|Regex rules]]
still apply in XML Schema mode, except:
<ul>
<li>In a regex, no characters are recognized as anchors, and
any regex is treated as if it is anchored at both ends.
The entire regex must match the entire target string (although
you can construct an unanchored match, as described in the
"Regular Expressions" appendix).

The regex <code>ABC</code> in XML Schema mode is equivalent
to <code>^(?:ABC)$</code> in non-XML Schema mode, where
the <code>(?:</code> indicates a "non-capturing" group.

Related to this, or as a consequence of this implicit anchoring:
<ul>
<li>The usual anchoring-atoms, <code>^</code> and <code>$</code>, are
treated as ordinary characters in a regex, and you may ''not'' escape them. </li>

<li>If the multi-line mode option (see [[#Common regex options|Common regex options]]) is specified along with XML Schema mode,
multi-line mode is ignored. </li>
</ul></li>

<li>The two-character sequence <code>(?</code> is not valid in a regex.
You can use a pair of parentheses for grouping, but capturing is not part of the
XML Schema regex specification, nor are non-capturing and look-aheads, whose indicators begin with a <code>(?</code> sequence.

If you specify the XML Schema mode option in a $function or method
that makes use of capturing (or replacing), however, any capturing groups
you use in the regex or replacement string(s) '''do''' perform
their usual operation.</li>

<li>A bracket character (<code>[</code> or <code>]</code>
requires a preceding escape character if it is:
<ul>
<li>A right bracket (<code>]</code>) that is outside of, not part of,
a character class expression.
So, <code>(1\]9)</code> matches <code>0001]9zzz</code>, but <code>(1]9)</code> is ''not'' allowed. </li>

<li>A right bracket that is the first character — or
the second, if the first is a caret (<code>^</code>) —
in a character class expression.
So, <code>[\]xxx]</code> and <code>[^\]xxx]</code> are allowed.</li>

<li>A left bracket that occurs anywhere in a character class expression.
So, <code>[abc\[]</code> is allowed.

A left bracket that
occurs outside of a character class expression must always be escaped.</li>
</ul>

These cases are compiler errors unless the cited bracket characters are escaped.</li>

<li>Character class subtraction is supported.
You can exclude a subset of characters from the characters
already designated to be in the class.
This is only allowed in XML Schema mode, and it is ''not'' allowed in Perl.

This feature lets you specify a character class like the following,
which matches anything from A to Z except D, I, O, Q, U, or V: 
[A-Z-[DIOQUV]]


You can also nest subtractions, as in:
[\w-[A-Z-[DIOQUV]]]


Characters immediately after the right bracket of a subtracted character
class are '''not''' allowed.
<code>[A-Z-[DIOQUV]abc]</code> is an ''invalid'' character class. 

You can also subtract a negated character class:
<code>[A-Z-[^DIOQUV]]</code> is ''valid''. </li>

<li>If the Dot-All mode or case-insensitive mode option (see [[#Common regex options|Common regex options]])
is specified along with XML Schema mode, Dot-All mode or case-insensitive mode works as usual. </li>
</ul>

==SOUL programming considerations==
These are issues of note when writing regex requests:
<ul>
<li>SOUL regex processing can use considerable user stack (PDL) space and STBL space:
<ul>
<li>A program running with a relatively small (less than 3000) setting of the
<var class="product">Model 204</var> <var>LPDLST</var> parameter is subject to a user restart due to PDL overflow,
even with relatively simple regular expressions.
Regular expression compilation and evaluation can sometimes be recursive, with each level of
recursion using a certain amount of PDL space.
For certain complex regular expressions, a large amount of PDL space may be used.

To reset <var>LPDLST</var>, you can use, for example, <code>UTABLE LPDLST 3000</code>.</li>

<li>In general, there must be at least 8500 bytes available in STBL (some
routines use less).
Using <code>UTABLE LSTBL 9000</code> is sufficient if the rest of the
User Language program requires almost no STBL space. </li>
</ul></li>

<li>A question mark character (<code>?</code>) is a reserved character, or metacharacter, in a regex expression.
As pointed out in a preceding subsection, the <code>??</code> character
combination in a SOUL regex is ambiguous, meaning either a regex quantifier or a SOUL dummy string.
In that case, the dummy string interpretation prevails, and you must
use an expression like <code>'?' With '?'</code> to code the regex quantifier.

Similarly, the SOUL dummy-string signifiers <code>?$</code> and <code>?&</code>
take precedence if those character sequences occur in a regex.
To use <code>?$</code> or <code>?&</code>
in a regex, you must use one or two escape characters,
respectively, after the question mark. </li>

<li>A caret (<code>^</code>) is used in this documentation to represent
the character that the keyboard program translates to X'5F'; this may be
a not sign (<code>¬</code>) on your system.</li>
</ul>

[[Category:Regular expression processing]]
[[Category:Overviews]]

IMGPREF parameter

2025-08-05T19:52:30Z

Alex: Created page with "{{Template:IMGOPT parameter subtitle}} ==Summary== <dl> <dt>Default value <dd>1 <dt>Parameter type <dd>User <dt>Where set <dd>User resettable <dt>Related products <dd>Imagine Transparency <dt>Introduced <dd><var class="product">Model 204 V8.0</var> </dl> ==Description== This parameter affects processing of finds for <var>Imagine Transparency</var> requests. When a <var>Find</var> request is sent to a <var>Transparency</var> broker, the broker will respond..."

{{Template:IMGOPT parameter subtitle}}
==Summary==
<dl>
<dt>Default value
<dd>1
<dt>Parameter type
<dd>User
<dt>Where set
<dd>User resettable
<dt>Related products
<dd>[[Imagine Transparency]]
<dt>Introduced
<dd><var class="product">Model 204 V8.0</var>
</dl>

==Description==

This parameter affects processing of finds for <var>Imagine Transparency</var> requests.

When a <var>Find</var> request is sent to a <var>Transparency</var> broker, the broker will respond with a list zero or more records thaty satisfy the criteria. To process those records, a separate request might need to be sent to the broker to retrieve each record. But, usually, a <var>Find</var> is immediately followed by a <var>For</var> loop on the matching records, so it can be useful for the broker to "prefetch" some number of records that satisfy the <var>Find</var> criteria, reducing the latency and CPU overhead of processing the extra record retrieval request. The default value of 1 should be fine for most applications though, if many finds in an application match many records, and all records are usually scanned, one might improve performance with a larger <var>IMGPREF</var>. The main downside of a large <var>IMGPREF</var> might be that records that are never scanned (because of early exit from <var>For</var> loops) might be sent from the broker to <var>Model 204</var>.



[[Category:User parameters]]
[[Category:Parameters]]

IMGOPT parameter

2025-08-05T19:43:02Z

Alex: Created page with "{{Template:IMGOPT parameter subtitle}} ==Summary== <dl> <dt>Default value <dd>X'00' <dt>Parameter type <dd>User <dt>Where set <dd>User resettable <dt>Related products <dd>Imagine Transparency <dt>Introduced <dd><var class="product">Model 204 V8.0</var> </dl> ==Description== This parameter affects processing for <var>Imagine Transparency</var> requests. The bits have the following meanings: <table> <tr class="head"><th>Settings</th><th>Meaning</th>..."

{{Template:IMGOPT parameter subtitle}}
==Summary==
<dl>
<dt>Default value
<dd>X'00'
<dt>Parameter type
<dd>User
<dt>Where set
<dd>User resettable
<dt>Related products
<dd>[[Imagine Transparency]]
<dt>Introduced
<dd><var class="product">Model 204 V8.0</var>
</dl>

==Description==

This parameter affects processing for <var>Imagine Transparency</var> requests.


The bits have the following meanings:
<table>
<tr class="head"><th>Settings</th><th>Meaning</th></tr>
<tr><th align="right"><var>X'01'</var></th>
<td>Push updates to the broker at the end of any <var>For</var> loop where there are pending updates. Normally, updates are deferred until there is a normal interaction with the broker such as for an <var>Find</var> or <var>Commit</var>. While this is very efficient in that it reduces the number of interactions with the broker, it can make it difficult to diagnose problems applying <var>Transparency</var> updates since any errors will occur well after the update, making it difficult to determine where a problematic update came from. By setting <code>IMGOPT X'01'</code>, broker errors will be reflected to <var>Model 204</var> very close to the location of the update.
</td></tr>
<tr><th align="right"><var>X'02'</var></th>
<td>Produce a stack trace for any messages resulting from [[IMGTRACE parameter|IMGTRACE]] settings. While <var>IMGTRACE</var> can be useful in debugging problems when using <var>Transparency</var>, one might get trace data but find it difficult to associate it with the source code that produced that data. Setting <code>IMGOPT X'02'</code> makes it easy to identify the source of any <var>IMGTRACE</var> data.
</td></tr>
</table>

[[Category:User parameters]]
[[Category:Parameters]]

IMAGINE command

2025-07-30T10:52:54Z

Alex: /* Syntax for IMAGINE */

{{DISPLAYTITLE:IMAGINE command}}
Move Model 204 data to Imagine

This command provides the facilities to extract <var>Model 204</var> data and load it into <var>Imagine</var>.

==Summary==
<dl>
<dt>Privileges</dt>
<dd>File manager</dd>
<dt>Function</dt>
<dd>provides the facilities to extract <var>Model 204</var> data and load it into <var>Imagine</var>.</dd>
</dl>

==Syntax for IMAGINE==
IMAGINE SYNC | EXTRACT [ASYNC] [MAXERR e] [MAXPENDING m] [RECORDNUMBER r] [NOCOMMIT] [TICK t]


Where:
<ul>
<li><var class="term">SYNC</var> indicates that data is to be extracted and the <var>Model 204</var> file and <var>Imagine</var> are to be kept in sync after the command.</li>
<li><var class="term">EXTRACT</var> indicates that data is to be extracted but the <var>Model 204</var> file and <var>Imagine</var> are not to be kept in sync after the command.</li>
<li><var class="term">ASYNC</var> indicates that the actual extract is to be performed on a daemon. In this mode, the command returns immediately after some preliminary setup. The advantage of this mode is that it frees up the issuing thread for other commands. The disadvantage is that one must look elsewhere to determine when the request completed and whether or not it was successful.</li>
<li><var class="term">MAXERR</var> indicates the maximum number of record data errors allowed before the extract is aborted. One might wish to set this to a high value for an extract intended to scan a file for data integrity errors. Because records are sent asynchronously in batches, it's quite possible for the actual number of errors to exceed the <var>MAXERROR</var> value. <var>MAXERROR</var> defaults to 50.</li>
<li><var class="term">MAXPENDING</var> indicates the maximum number of uncommitted record sends to be allowed in the extract. Setting this to a low value could result in reduced transfer rates because of network latency. <var>MAXPENDING</var> defaults to 4095.</li>
<li><var class="term">NOCOMMIT</var> indicates that the data is to be sent to Imagine and processed, but not committed. This provides a way of validating that a file can be loaded into <var>Imagine</var> without actually doing so. This option makes no sense for a SYNC extract, so is only allowed with <code>IMAGINE EXTRACT</code>.</li>
<li><var class="term">RECORDNUMBER</var> indicates the record number of the single record to be sent to Imagine. This might be useful for problem diagnosis or resending fixed up records that failed on an initial extract. This option makes no sense for a SYNC extract so is only allowed with <code>IMAGINE EXTRACT</code>. Other options (except <var>NOCOMMIT</var>) are ignored if <var>RECORDNUMBER</var> is specified.</li>
<li><var class="term">TICK</var> indicates the number of records between progress messages (M204.3073) to the journal. This parameter also sets the frequency of progress messages on <var>Imagine</var>. <var>TICK</var> defaults to 100000.</li>
</ul>

There is also a format of the IMAGINE command:
IMAGINE ENDSYNC


That indicates a SYNC or EXTRACT for the file should be terminated.

===Syntax notes===

The IMAGINE command operates on the context file which is either the current file or one
explicitly specified before the command as in:

IN FILE FOOBAR EXTRACT NOCOMMIT


==Example==

To put file FOO into sync mode, one can do:

OPEN FILE FOO
IMAGINE SYNC TICK 200000
The <var>TICK</var> keyword indicates that a M204.3073 message should be issued every 200,000
records. If one wishes to see these messages on the operator console, one can do:
MSGCTL M204.3073 OPR


Note that the actual extraction of records is done on a daemon thread created by the
IMAGINE command so the thread that issued the IMAGINE command would return fairly
quickly. Also note that this means that there is no terminal for M204.3073 (or other)
messages issued during the extract to appear, so one needs to look in the journal
for errors, should they occur.

==Usage notes==

To obtain a consistent view of the file on <var>Imagine</var>, the IMAGINE command
first quiesces the file; that is, ensures that no updating transactions that had
updated the file are active. This will usually take less than a second, but a long
running transaction that had updated the file could make this take quite a while.
As such, it is recommended that the IMAGINE command be issued at a relatively quiet
time in terms of file updates.


Once the extraction process has begun, whether <var>SYNC</var>, <var>EXTRACT</var>,
or <var>NOCOMMIT</var>, any other thread that wishes to update a record in the file
being extracted, cannot update the record until it has been copied to <var>Imagine</var> and
committed. If it has already been done at the time of the commit, no wait is required.
However, if the record has not been copied to and committed to <var>Imagine</var> the
thread would send a request to the extracting daemon to immediately send the record to
<var>Imagine</var> (if not already sent) and then to wake the updating thread when that
record is committed on <var>Imagine</var>. This can cause a slight delay in update
processing so, again, the recommendation is for extracts to be done at relatively quiet
times for a file.


If a file is in SYNC mode, once a record has been sent to <var>Imagine</var>, any updates
to the file are sent to <var>Imagine</var> (via a broker connection) and those updates
must be committed for the transaction to succeed. That is, if some error occurs on
<var>Imagine</var> for a SYNC update, the request would be cancelled and the transaction
backed out. Note that this processing occurs even after the file has been fully extracted,
and the extracting daemon is no longer active. This ensures that the SYNC'ed file will
remain consistent between <var>Model 204</var> and <var>Imagine</var> making it feasible
to switch the file to transparency mode with a minimal outage.


For a plain EXTRACT (as opposed to SYNC), updates to records in the file after they have
committed in <var>Imagine</var> are not sent to <var>Imagine</var>, so the file can
get out of synch between <var>Model 204</var> and <var>Imagine</var>. However, by not
allowing any records to be updated in the file during the EXTRACT process until they
have been committed on <var>Imagine</var>, the file on <var>Imagine</var> will be ensured
to be a consistent view of the file as of the point in the <code>IMAGINE EXTRACT</code>
command where updates to the file had been quiesced.


==See also==
<ul>
<li>[[Imagine Transparency]]</li>
</ul>

[[Category: File manager commands]]
[[Category:Commands]]

IMAGINE command

2025-07-09T14:29:56Z

Alex: /* Syntax for IMAGINE */

{{DISPLAYTITLE:IMAGINE command}}
Move Model 204 data to Imagine

This command provides the facilities to extract <var>Model 204</var> data and load it into <var>Imagine</var>.

==Summary==
<dl>
<dt>Privileges</dt>
<dd>File manager</dd>
<dt>Function</dt>
<dd>provides the facilities to extract <var>Model 204</var> data and load it into <var>Imagine</var>.</dd>
</dl>

==Syntax for IMAGINE==
IMAGINE SYNC | EXTRACT [NOCOMMIT] [TICK t] [MAXPENDING m] [MAXERR e] [ASYNC]


Where:
<ul>
<li><var class="term">SYNC</var> indicates that data is to be extracted and the <var>Model 204</var> file and <var>Imagine</var> are to be kept in sync after the command.</li>
<li><var class="term">EXTRACT</var> indicates that data is to be extracted but the <var>Model 204</var> file and <var>Imagine</var> are not to be kept in sync after the command.</li>
<li><var class="term">NOCOMMIT</var> indicates that the data is to be sent to Imagine and processed, but not committed. This provides a way of validating that a file can be loaded into <var>Imagine</var> without actually doing so. This option makes no sense for a SYNC extract so is only allowed with <code>IMAGINE EXTRACT</code>.</li>
<li><var class="term">TICK</var> indicates the number of records between progress messages (M204.3073) to the journal. This parameter also sets the frequency of progress messages on <var>Imagine</var>. <var>TICK</var> defaults to 100000.</li>
<li><var class="term">MAXPENDING</var> indicates the maximum number of uncommitted record sends to be allowed in the extract. Setting this to a low value could result in reduced transfer rates because of network latency. <var>MAXPENDING</var> defaults to 4095.</li>
<li><var class="term">MAXERR</var> indicates the maximum number of record data errors allowed before the extract is aborted. One might wish to set this to a high value for an extract intended to scan a file for data integrity errors. Because records are sent asynchronously in batches, it's quite possible for the actual number of errors to exceed the <var>MAXERROR</var> value. <var>MAXERROR</var> defaults to 50.</li>
<li><var class="term">ASYNC</var> indicates that the actual extract is to be performed on a daemon. In this mode, the command returns immediately after some preliminary setup. The advantage of this mode is that it frees up the issuing thread for other commands. The disadvantage is that one must look elsewhere to determine when the request completed and whether or not it was successful.</li>
</ul>

There is also a format of the IMAGINE command:
IMAGINE ENDSYNC


That indicates a SYNC or EXTRACT for the file should be terminated.

===Syntax notes===

The IMAGINE command operates on the context file which is either the current file or one
explicitly specified before the command as in:

IN FILE FOOBAR EXTRACT NOCOMMIT


==Example==

To put file FOO into sync mode, one can do:

OPEN FILE FOO
IMAGINE SYNC TICK 200000
The <var>TICK</var> keyword indicates that a M204.3073 message should be issued every 200,000
records. If one wishes to see these messages on the operator console, one can do:
MSGCTL M204.3073 OPR


Note that the actual extraction of records is done on a daemon thread created by the
IMAGINE command so the thread that issued the IMAGINE command would return fairly
quickly. Also note that this means that there is no terminal for M204.3073 (or other)
messages issued during the extract to appear, so one needs to look in the journal
for errors, should they occur.

==Usage notes==

To obtain a consistent view of the file on <var>Imagine</var>, the IMAGINE command
first quiesces the file; that is, ensures that no updating transactions that had
updated the file are active. This will usually take less than a second, but a long
running transaction that had updated the file could make this take quite a while.
As such, it is recommended that the IMAGINE command be issued at a relatively quiet
time in terms of file updates.


Once the extraction process has begun, whether <var>SYNC</var>, <var>EXTRACT</var>,
or <var>NOCOMMIT</var>, any other thread that wishes to update a record in the file
being extracted, cannot update the record until it has been copied to <var>Imagine</var> and
committed. If it has already been done at the time of the commit, no wait is required.
However, if the record has not been copied to and committed to <var>Imagine</var> the
thread would send a request to the extracting daemon to immediately send the record to
<var>Imagine</var> (if not already sent) and then to wake the updating thread when that
record is committed on <var>Imagine</var>. This can cause a slight delay in update
processing so, again, the recommendation is for extracts to be done at relatively quiet
times for a file.


If a file is in SYNC mode, once a record has been sent to <var>Imagine</var>, any updates
to the file are sent to <var>Imagine</var> (via a broker connection) and those updates
must be committed for the transaction to succeed. That is, if some error occurs on
<var>Imagine</var> for a SYNC update, the request would be cancelled and the transaction
backed out. Note that this processing occurs even after the file has been fully extracted,
and the extracting daemon is no longer active. This ensures that the SYNC'ed file will
remain consistent between <var>Model 204</var> and <var>Imagine</var> making it feasible
to switch the file to transparency mode with a minimal outage.


For a plain EXTRACT (as opposed to SYNC), updates to records in the file after they have
committed in <var>Imagine</var> are not sent to <var>Imagine</var>, so the file can
get out of synch between <var>Model 204</var> and <var>Imagine</var>. However, by not
allowing any records to be updated in the file during the EXTRACT process until they
have been committed on <var>Imagine</var>, the file on <var>Imagine</var> will be ensured
to be a consistent view of the file as of the point in the <code>IMAGINE EXTRACT</code>
command where updates to the file had been quiesced.


==See also==
<ul>
<li>[[Imagine Transparency]]</li>
</ul>

[[Category: File manager commands]]
[[Category:Commands]]

JANUS DEFINE

2025-06-23T02:08:33Z

Alex:

{{DISPLAYTITLE:JANUS DEFINE}}
Define and set characteristics of a Janus port

==Overview==

The <var>JANUS DEFINE</var> command is used to specify the characteristics of a Janus port. It defines the usage of the named port as one of the following:

<ul>
<li>Access by IFDIAL clients</li>

<li>Open Server or Open Client connections</li>

<li>Specialty Data Store access</li>

<li>Web access</li>

<li>FTP server connections</li>

<li>Telnet server connections</li>

<li>Generic Sockets usage — with the <var class="product">Model 204</var> online either requesting (<var>[[JANUS DEFINE#type|CLSOCK]]</var>) or accepting (<var>[[JANUS DEFINE#type|SRVSOCK]]</var>) the connection</li>

<li>Generic [http://en.wikipedia.org/wiki/User_Datagram_Protocol UDP] Sockets usage — with the <var class="product">Model 204</var> online either initiating (<var>[[JANUS DEFINE#type|CLSOCKU]]</var>) or accepting (<var>[[JANUS DEFINE#type|SRVSOCKU]]</var>) the exchange of messages.</li>

<li>Connection between the <var class="product">[[Debugger|Janus Debugger]]</var> or <var class="product">[[Debugger|TN3270 Debugger]]</var> workstation GUI and programs being debugged in <var class="product">Model 204</var></li>
</ul>

For any except a <var>CLSOCK</var> or <var>[[#type|DEBUGGERCLIENT]]</var> port, this subcommand associates a service with a TCP/IP port number.

Among the characteristics specified by <var>JANUS DEFINE</var> is whether the port will use Secure Sockets Layer (SSL) for encrypted communications.

See [[Defining server ports]] for connectivity background information and information about when you need to issue the <var>[[JANUS DEFINEREMOTE]]</var> command.

The <var>JANUS DEFINE</var> command syntax is described below.

==Syntax==
JANUS DEFINE portname portnum type maxcon other_parms ...


Where each of the first four parameters is positional and required:

<table>
<tr><th>portname</th>
<td>A 1- to 30-character name by which the port is identified. It is used on other <var>JANUS</var> subcommands, such as <var>[[JANUS START]]</var> and <var>[[JANUS DISPLAY]]</var>. It is used on the <var>$Sock_Conn</var> function or the Socket object <var>[[New (Socket constructor)|New]]</var> constructor to name the <var>CLSOCK</var> port defining a connection.</td></tr>

<tr><th>portnum</th>
<td>The TCP/IP port number at which the service is available. <var class="term">portnum</var> is the server port number, and it must be between 1 and 65535, inclusive. This number is used by client applications on the network when they require access to the <var class="product">Model 204</var> server. The server port number must be unique on the host. Several "well-known" port numbers for various TCP/IP services (for example, 53 for nameserver) should be avoided, unless you are implementing that service using <var class="product">[[Janus Sockets]]</var>.

For <var>CLSOCK</var> and <var>DEBUGGERCLIENT</var> ports, an asterisk (*) is used as the port number, since they are used to create, rather than accept, connections, and these port numbers are not determined until the time of the connection. For <var>WEBSERV</var> ports, 80 is customary for non-secure HTTP and 443 for secure HTTP (SSL); you can, however, use other numbers for <var>WEBSERV</var> ports if required.

For <var>FTPSERVER</var> ports, 21 is customary; you can, however, use other numbers for <var>FTPSERVER</var> ports if required.</td></tr>

<tr><th>type</th>
<td><div id="type"></div>Port type. Valid types are:

<table>
<tr><th><var>2PC</var></th>
<td>A <var class="product">[[Janus Two-Phase Commit]]</var> port.</td></tr>

<tr><th><var>CLSOCK</var></th>
<td>A <var class="product">Janus Sockets</var> client socket port. If non-system administrator users are to use a <var>CLSOCK</var> port, rules must be provided to allow them to initiate outgoing connections on the port.</td></tr>

<tr><th><var>CLSOCKU</var></th>
<td>A <var class="product">Janus Sockets</var> UDP client port. If non-system administrator users are to use a <var>CLSOCKU</var> port, rules must be provided to allow them to initiate outgoing connections on the port. A <var>CLSOCKU</var>
port can also be used to implement a UDP server on a single <var class="product">Model 204</var> thread. Only available in <var class="product">Sirius Mods</var> Version 8.0 and later.</td></tr>

<tr><th><var>DEBUGGERCLIENT</var></th>
<td>A <var class="product">Sirius Debugger</var> client socket port.</td></tr>

<tr><th><var>DEBUGGERSERVER</var></th>
<td>A <var class="product">Janus Debugger</var> or <var class="product">TN3270 Debugger</var> server socket port.</td></tr>

<tr><th><var>FTPSERVER</var></th>
<td>A <var class="product">[[Janus FTP Server]]</var> application.</td></tr>

<tr><th><var>IFDIAL</var></th>
<td><var class="product">[[Janus IFDIAL Library]]</var> applications.</td></tr>

<tr id="IMAGINET"><th><var>IMAGINET</var></th>
<td>An <var class="product">[[Imagine Transparency]]</var> port. This port type is only available in <var class="product">Model 204</var> Version 8.0 and later. There can only be one started IMAGINET port in an Online.</td></tr>

<tr><th><var>OAS</var></th>
<td>Synonym for type <var>SDS</var>.</td></tr>

<tr><th><var>OMNI</var></th>
<td>Synonym for type <var>SDS</var>.</td></tr>

<tr><th><var>OPENSERV</var></th>
<td><var class="product">[[Media:josrvr.pdf|Janus Open Server]]</var> applications; <var class="product">[[Media:JoclrNew.pdf|Janus Open Client]]</var> connections are outward-bound connections on an <var>OPENSERV</var> port.</td></tr>

<tr><th><var>SRVSOCK</var></th>
<td>A <var class="product">Janus Sockets</var> server socket port.</td></tr>
<tr><th><var>SRVSOCKU</var></th>

<td>A <var class="product">Janus Sockets</var> UDP server port. Only available in <var class="product">Sirius Mods</var> Version 8.0 and later.</td></tr>

<tr><th><var>SDS</var></th>
<td>A <var class="product">[[Media:jsdsr.pdf|Janus Specialty Data Store]]</var> port.</td></tr>

<tr><th><var>TNSERV</var></th>
<td>A <var class="product">[[Janus Telnet Server]]</var> port.</td></tr>

<tr><th><var>WEBSERV</var></th>
<td>A World Wide Web Server port.
</td></tr>
</table>

For <var class="product">Janus Open Client</var> usage, you must define one or more ports of type <var>SDS</var> or <var>OPENSERV</var>, and you may need to use the <var>MASTER</var> parameter on a port definition. For <var>JANUS</var> server ports, specify <var>SRVSOCK</var>; for <var>JANUS</var> client ports, specify <var>CLSOCK</var>; for <var>JANUS FTP</var> server ports, specify <var>FTPSERVER</var>; for <var>JANUS</var> telnet server ports, specify <var>TNSERV</var>. <var>TNSERV</var> ports require that the system <var>TNDEV</var> parameter be set to indicate the <var>IODEV</var> that daemon threads switch to while in full-screen mode for a telnet connection.
</td></tr>

<tr><th>maxcon</th>
<td>Maximum number of simultaneous active connections to be allowed on the port. This number must be less than or equal to the number of TCP/IP connections for which the site is licensed. If you are defining multiple ports for your site, however, the sum of the <var class="term">maxcon</var> connections you define is allowed to be greater than the number for which the site is licensed. <var class="product">[[Janus Web Server]]</var> will automatically prevent any connection that would exceed the site license limit.

For <var class="product">Janus Open Client</var>, note that a server-to-server connection requires an extra connection for the '''site handler.''' Thus, a single connection to a remote server would use two connections, while 10 connections to a remote server would use 11. 

You can use the <var>[[JANUS TSTATUS]]</var> command to view the thread usage and connection limits for your port, and you can use the <var>[[JANUS LIMITS]]</var> command to view similar information for your Online.</td></tr>

<tr><th>other_parms</th>
<td>A set of blank-delimited parameters that describe the characteristics of and processing to be performed on the port. These parameters are keywords, sometimes followed by values, and they are described individually in the subsections that follow. They are all optional, except:
<ul>
<li>For <var>OPENSERV</var> ports, <var>CMD</var> is required. </li>

<li>For <var>CLSOCK</var> or <var>DEBUGGERCLIENT</var> ports, <var>REMOTE</var> is required. </li>

<li>For <var>SRVSOCK</var> or <var>SRVSOCKU</var> ports, <var>CMD</var> is required. </li>

<li>For <var>FTPSERVER</var> ports, <var>[[OPEN (JANUS DEFINE parameter)|OPEN]]</var>, <var>[[CMD (JANUS DEFINE parameter)|CMD]]</var>, <var>[[NEWSESOPEN (JANUS DEFINE parameter)|NEWSESOPEN]]</var>, and <var>[[NEWSESCMD (JANUS DEFINE parameter)|NEWSESCMD]]</var> are not allowed. </li>
</ul>
</td></tr>
</table>

==Examples==

The parameters you might use on a port definition vary by port type (that is, communication protocol), the security requirements of your shop and application, performance considerations and the applications that will run inside the <var class="product">Model 204</var> Online as a client or a service on this port.

There is no such thing as a "typical" port — each one is customized to the service or services running over the port.

JANUS DEFINE JANWEB 80 WEBSERV 50 WEBUSER WEBUSER TRACE 0 UPCASE -
OBSIZE 10240 IBSIZE 10240 RBSIZE 10240 TIMEOUT 600 -
OPEN FILE JANWEB MAXTEMP 14000 BINDADDR 198.242.244.47 -
LOG REQ WEBLOGJW LOGCLOSET 57 NOAUDTERM COMPRESS 2 KEEPALIVE 30


In the above example, a <var class="product">Janus Web Server</var> port is defined, named <var>JANWEB</var>. It runs at port 80 (the default web port) and allows 50 simultaneous connections. Buffer sizes are increases over the default settings and a variety of logging, compressions and other settings are specified.

JANUS DEFINE SOAP * CLSOCK 5 TIMEOUT 240 REMOTE * * MASTER


In the above example, a client socket "master" port called <code>SOAP</code> is defined, permitting 5 simultaneous outgoing connections to any ''remote'' hosts.

<div id="parmlist"></div>

==JANUS DEFINE parameters==

<table>
<tr><td>[[ALLOCC (JANUS DEFINE parameter)|ALLOCC]]</td><td>Indicates that input, output and request buffers are to be allocated when a connection is established and are to be freed when the connection is closed.</td></tr>

<tr><td>[[ANONYMOUS (JANUS DEFINE parameter)|ANONYMOUS]]</td><td>Indicates that anonymous access is permitted to the FTP server being defined.</td></tr>

<tr><td>[[ANONUSER (JANUS DEFINE parameter)|ANONUSER]]</td><td>Lets you change the name of the anonymous user, <var>ANONUSER</var> may be specified only if <var>ANONYMOUS</var> is also specified.</td></tr>

<tr><td>[[AUDTERM (JANUS DEFINE parameter)|AUDTERM]]</td><td>Controls whether the server thread sends "non-compiler terminal output" to the audit trail.</td></tr>

<tr><td>[[AUTODONE (JANUS DEFINE parameter)|AUTODONE]]</td><td>Requests <var class="product">[[Janus Web Server]]</var> to treat a return to command mode after all port and ON rules <var>CMD</var>s have been processed as an implicit <var>[[$Web_Done]]</var>.</td></tr>

<tr><td>[[AUTOLOAD (JANUS DEFINE parameter)|AUTOLOAD]]</td><td>Indicates that the incore copy of Janus tables are to be reloaded at the first request subsequent to a table redefinition.</td></tr>

<tr><td>[[AUTOON (JANUS DEFINE parameter)|AUTOON]]</td><td>Requests <var class="product"> Janus Web Server</var> to issue an implicit <var>[[$Web_On]]</var> before executing the commands specified in a <var class="product">JANUS WEB ON</var> rule.</td></tr>

<tr><td>[[AUTOSYS (JANUS DEFINE parameter)|AUTOSYS]]</td><td>Sets the Model 204 <var>AUTOSYS</var> parameter to the indicated (<var class="term">subsys</var>) value when a connection is received on a <var>[[JANUS DEFINE#type|TNSERV]]</var> port.</td></tr>

<tr><td>[[BINARY (JANUS DEFINE parameter)|BINARY]]</td><td>Requests <var class="product">[[Janus Sockets]]</var> to send and receive strings with [[List of Janus Sockets $functions|$Sock_xxx]] functions or Socket methods using no translation.</td></tr>

<tr><td>[[BINDADDR (JANUS DEFINE parameter)|BINDADDR]]</td><td>Specifies the IP address to which the port will be bound, if the host (machine) on which <var class="product">Model 204</var> is running supports multiple IP addresses.</td></tr>

<tr><td>[[BSIZE (JANUS DEFINE parameter)|BSIZE]]</td><td>Specifies the size of the TCP/IP input and output buffers.</td></tr>

<tr><td>[[CHAR (JANUS DEFINE parameter)|CHAR]]</td><td>Requests <var class="product">[[Janus Sockets]]</var> to translate strings (sent and received with <var class="product">Janus Sockets</var> functions or methods) between the internal representation within <var class="product">Model 204</var> (EBCDIC) and the character representation used by the remote end of the
connection.</td></tr>

<tr><td>[[CHARSET (JANUS DEFINE parameter)|CHARSET]]</td><td>Indicates, to the remote host, the character set being used by Janus.</td></tr>

<tr><td>[[CLIENTSOCKET (JANUS DEFINE parameter)|CLIENTSOCKET]]</td><td>Names the client socket port to use to open connections back to the FTP client, if the client requests active file transfers.</td></tr>

<tr><td>[[CLOSEIMMED (JANUS DEFINE parameter)|CLOSEIMMED]]</td><td>Indicates that if a lost connection is noticed by the Janus PST, the PST should <var>BUMP</var> the <var class="product">Model 204</var> thread associated with the connection immediately.</td></tr>

<tr><td>[[CLOSEREAD (JANUS DEFINE parameter)|CLOSEREAD]]</td><td>Indicates that web threads should "put up" a TCP/IP read after receiving the entire request but before processing it.</td></tr>

<tr><td>[[CMD (JANUS DEFINE parameter)|CMD]]</td><td>Specifies the <var class="product">Model 204</var> commands to be executed after the files and groups specified in the <var>OPEN</var> parameter are opened.</td></tr>

<tr><td>[[COMPRESS (JANUS DEFINE parameter)|COMPRESS]]</td><td>Indicates the type of compression to be performed on outgoing <var class="product">Janus Web Server</var> data.</td></tr>

<tr><td>[[CR (JANUS DEFINE parameter)|CR]]</td><td>Indicates that lines of text data sent to a browser should be separated by the ASCII carriage return character (X'0D').</td></tr>
<tr><td>[[CRLF (JANUS DEFINE parameter)|CRLF]]</td><td>Indicates that lines of text data sent to a browser should be separated by the ASCII carriage return and line feed characters (X'0D0A').</td></tr>

<tr><td>[[CSSINSP (JANUS DEFINE parameter)|CSSINSP]]</td><td>Indicates whether or not <var class="product">[[Janus Web Legacy Support]]</var> is to insert a space to represent the attribute byte on a 3270 screen.</td></tr>

<tr><td>[[CSSTITLEDIV and CSSTITLESPAN (JANUS DEFINE parameters)|CSSTITLEDIV and CSSTITLESPAN]]</td><td>Indicates whether <var class="product">Janus Web Legacy</var> support is to use a <code><div></code> (<var>CSSTITLEDIV</var>) or <code></code> (<var>CSSTITLESPAN</var>) tag for the title line of a screen.</td></tr>

<tr><td>[[DBCS and NODBCS (JANUS DEFINE parameters)|DBCS and NODBCS]]</td><td>Indicates whether or not the <var class="product">Model 204</var> <var>DBCS</var> parameter is to be automatically set to 1 on requests to a <var>WEBSERV</var> port.</td></tr>

<tr><td>[[DEBPORTCMD and NODEBPORTCMD (JANUS DEFINE parameters)|DEBPORTCMD and NODEBPORTCMD]]</td><td>Indicates whether the commands specified in the <var>CMD</var> clause of the <var>JANUS DEFINE</var> command are to be run on threads debugging requests to the port with the <var>[[JANUSDEBUG]]</var> command.</td></tr>

<tr><td>[[DEBPORTOPEN and NODEBPORTOPEN (JANUS DEFINE parameters)|DEBPORTOPEN and NODEBPORTOPEN]]</td><td>Indicates whether the files and groups specified in the <var>OPEN</var> clause of the <var>JANUS DEFINE</var> command are to be opened on threads debugging requests.</td></tr>

<tr><td>[[EXEC2RPC (JANUS DEFINE parameter)|EXEC2RPC]]</td><td>Indicates that language requests should be converted to RPCs.</td></tr>

<tr><td>[[FINCLOSE and NOFINCLOSE (JANUS DEFINE parameters)|FINCLOSE and NOFINCLOSE]]</td><td>Affect how <var class="product">Janus Sockets</var> applications respond to a closed connection.</td></tr>

<tr><td>[[FDWOL (JANUS DEFINE parameter)|FDWOL]]</td><td>Specifies that all <var>FIND</var>s done by <var class="product">Janus Specialty Data Store</var> are to be done as <var>Find Without Locks</var>.</td></tr>

<tr><td>[[FORMPOSTWAIT (JANUS DEFINE parameter)|FORMPOSTWAIT]]</td><td>The default number of seconds to wait for the POST'ing of a form while using <var>[[$Web_Form_Done]]</var>.</td></tr>

<tr><td>[[FORMREDIRWAIT (JANUS DEFINE parameter)|FORMREDIRWAIT]]</td><td>The default number of seconds to wait for the client on a <var>WEBSERV</var> port (presumably a browser) to do the GET associated with a redirect generated by a <var>$Web_Form_Done</var> call.</td></tr>

<tr><td>[[HIGHPRIORITY (JANUS DEFINE parameter)|HIGHPRIORITY]]</td><td>Adjusts the <var class="product">Model 204</var> scheduling priority of <var class="product">Janus Web Server</var> threads by starting them at the upper end of their priority range rather than at their default priority.</td></tr>

<tr><td>[[HTTPVERSION (JANUS DEFINE parameter)|HTTPVERSION]]</td>
<td>Sets the HTTP version returned to the browser by <var class="product">Janus Web Server</var>.</td></tr>

<tr><td>[[IBSIZE (JANUS DEFINE parameter)|IBSIZE]]</td><td>Specifies the size of the TCP/IP input buffer.</td></tr>

<tr><td>[[INPUTTIMEOUT (JANUS DEFINE parameter)|INPUTTIMEOUT]]</td><td>Tells <var class="product">Janus Web Server</var> to use a different timeout value for input (receiving the web request) than for output.</td></tr>

<tr><td>[[JANCAT (JANUS DEFINE parameter)|JANCAT]]</td>
<td>Specifies the name of the file that contains the <var class="product">Model 204</var> to SQL mappings.</td></tr>

<tr><td>[[KEEPALIVE (JANUS DEFINE parameter)|KEEPALIVE]]</td>
<td>Indicates the number of seconds a TCP/IP connection is to be held open after an HTTP request on that connection.</td></tr>

<tr><td>[[LANGUAGE (JANUS DEFINE parameter)|LANGUAGE]]</td>
<td>Indicates, to the remote host, the language being used by Janus.</td></tr>

<tr><td>[[LEGBL, LEGREV, LEGUS, NOLEGBL, NOLEGREV, and NOLEGUS (JANUS DEFINE parameters)|LEGBL, LEGREV, LEGUS, NOLEGBL, NOLEGREV, and NOLEGUS]]</td>
<td>Sets ''blink'', ''underscore'' and ''reverse'' characteristics for <var class="product">[[Janus Web Legacy Support]]</var> screens.</td></tr>

<tr><td>[[LEGCSS and NOLEGCSS (JANUS DEFINE parameters)|LEGCSS and NOLEGCSS]]</td>
<td>Indicates whether or not <var class="product">Janus Web Legacy Support</var> is to use Cascading Style Sheets.</td></tr>

<tr><td>[[LEGJS and NOLEGJS (JANUS DEFINE parameters)|LEGJS and NOLEGJS]]</td>
<td>Indicates whether or not <var class="product">Janus Web Legacy Support</var> is to use JavaScript.</td></tr>

<tr><td>[[LF (JANUS DEFINE parameter)|LF]]</td><td>Indicates that lines of text data sent to a browser should be separated by the ASCII line feed character (X'0A').</td></tr>

<tr><td>[[LINEND (JANUS DEFINE parameter)|LINEND]]</td><td>Specifies the hex value of a string to be sent by <var class="product">Janus Sockets</var> at the end of each "line;" that is, appended to the string sent by the <var>[[$Sock_SendLn]]</var> function or <var>Socket</var> <var>[[SendWithLineEnd (Socket function)|SendWithLineEnd]]</var> function or after each output line
captured on the socket.</td></tr>

<tr><td>[[LOG (JANUS DEFINE parameter)|LOG]]</td>
<td>Specifies that all <var class="product">Janus Web Server</var> requests for the port are to be logged to a sequential data set whose DDNAME is specified (as indicated in this parameter's syntax).
The <var>LOG</var> data set records conform to the industry standard for web logging.
</td></tr>

<tr><td>[[LOGAPPEND (JANUS DEFINE parameter)|LOGAPPEND]]</td>
<td>Indicates that the <var class="product">Janus Web Server</var> log data set for the port is to be opened in APPEND mode.</td></tr>

<tr><td>[[LOGCLOSET (JANUS DEFINE parameter)|LOGCLOSET]]</td>
<td>Indicates how often the <var class="product">Janus Web Server</var> log data set is to be "closed", that is how often the DSCB is to be updated for the log dataset.</td></tr>

<tr><td>[[LOGGMT (JANUS DEFINE parameter)|LOGGMT]]</td>
<td>Indicates that the time stamps in the <var class="product">Janus Web Server</var> log data set for the port are to be represented as GMT instead of local time.</td></tr>

<tr><td>[[LOGMSGI (JANUS DEFINE parameter)|LOGMSGI]]</td><td>Prevents <var class="product">Janus Web Server</var> from saving <var class="product">Model 204</var> messages issued during logon for a web user.</td></tr>

<tr><td>[[MASTER (JANUS DEFINE parameter)|MASTER]]</td>
<td>Specifies that this is the default port for ''outgoing'' client communication.</td></tr>

<tr><td>[[MAXCURS (JANUS DEFINE parameter)|MAXCURS]]</td>
<td>Specifies the maximum number of cursors that can be opened for a single <var class="product">Janus Specialty Data Store</var> connection.</td></tr>

<tr><td>[[MAXIPSES (JANUS DEFINE parameter)|MAXIPSES]]</td><td>Specifies the maximum number of <var class="product">Janus Web Legacy Support</var> sessions maintained per IP address.</td></tr>

<tr><td>[[MAXREC (JANUS DEFINE parameter)|MAXREC]]</td>
<td>Specifies the maximum record length for input records on a Janus <var>IFDIAL</var> port.</td></tr>

<tr><td>[[MAXSAVE (JANUS DEFINE parameter)|MAXSAVE]]</td>
<td>Specifies the maximum number of compiled SQL requests to save in CCATEMP.</td></tr>

<tr><td>[[MAXTEMP (JANUS DEFINE parameter)|MAXTEMP]]</td>
<td>Specifies the maximum number of CCATEMP pages allowed to be used by a web request for holding input (file upload) and output (dynamically generated HTML) data.</td></tr>

<tr><td>[[MSGOPT (JANUS DEFINE parameter)|MSGOPT]]</td>
<td>Specifies what types of information to report in <code>MSIR.</code> messages regarding Janus Web (only) requests.</td></tr>

<tr><td>[[MSGSEND and NOMSGSEND (JANUS DEFINE parameters)|MSGSEND and NOMSGSEND]]</td>
<td>Indicates whether or not <var class="product">Model 204</var> messages (as opposed to the output from <var>PRINT</var> or <var>HTML</var> statements) are to be sent to the browser.</td></tr>

<tr><td>[[MSG204 (JANUS DEFINE parameter)|MSG204]]</td>
<td>Specifies the Sybase message number to be used to return terminal output to the client.</td></tr>

<tr><td>[[MSG204L (JANUS DEFINE parameter)|MSG204L]]</td>
<td>Specifies the Sybase message number to be used to return terminal output to the client.</td></tr>

<tr><td>[[NEWPASSWORDC (JANUS DEFINE parameter)|NEWPASSWORDC]]</td>
<td>This parameter prevents <var class="product">Janus Web Server</var> from immediately sending an "Unauthorized" response to a browser after a password change.</td></tr>

<tr><td>[[NEWSESCMD (JANUS DEFINE parameter)|NEWSESCMD]]</td>
<td>Specifies the <var class="product">Model 204</var> commands to be executed when a new login session is initiated.</td></tr>

<tr><td>[[NEWSESGUESTOK (JANUS DEFINE parameter)|NEWSESGUESTOK]]</td>
<td>Indicates that "guest" logins are to be allowed for <var>[[$Sir_Login]]</var> calls in programs run as part of <var>NEWSESCMD</var> processing.</td></tr>

<tr><td>[[NEWSESNOCLEARG (JANUS DEFINE parameter)|NEWSESNOCLEARG]]</td>
<td>Indicates that GTBL is not to be cleared at the end of <var>NEWSESCMD</var> command processing.</td></tr>

<tr><td>[[NEWSESOPEN (JANUS DEFINE parameter)|NEWSESOPEN]]</td>
<td>Specifies the names of one or more <var class="product">Model 204</var> files or groups to be opened before any <var>NEWSESCMD</var> commands are executed.</td></tr>

<tr><td>[[NOAUDTERM (JANUS DEFINE parameter)|NOAUDTERM]]</td>
<td>This parameter is used to control whether the server thread sends "non-compiler terminal output" to the audit trail.</td></tr>

<tr><td>[[NOAUTODONE (JANUS DEFINE parameter)|NOAUTODONE]]</td>
<td>Prevents <var class="product">Janus Web Server</var> from treating a return to command mode after all port and <var>ON</var> rules <var>CMD</var>s have been processed as an implicit <var>$Web_Done</var>.</td></tr>

<tr><td>[[NOAUTOON (JANUS DEFINE parameter)|NOAUTOON]]</td>
<td>Prevents <var class="product">Janus Web Server</var> from preceding the execution of the command specified in a <var>JANUS WEB ON</var> rule with an implicit <var>$Web_On</var>.</td></tr>

<tr><td>[[NOSCREENREDIR (JANUS DEFINE parameter)|NOSCREENREDIR]]</td>
<td>Indicates that <var class="product">Janus Web Server</var> legacy support (automatic mapping of 3270 applications to HTML) is not to use the redirect's to map all screens for a legacy session to the same URL.</td></tr>

<tr><td>[[NOTRACEFIELD (JANUS DEFINE parameter)|NOTRACEFIELD]]</td>
<td>Indicates the form field or fields whose values are not to be traced when the X'04' bit (causes tracing of form field values for web requests) of <var>JANUS TRACE</var> is in effect.</td></tr>

<tr><td>[[NOUPCASE (JANUS DEFINE parameter)|NOUPCASE]]</td>
<td>Indicates that no client data is to be converted to uppercase.</td></tr>

<tr><td>[[OBSIZE (JANUS DEFINE parameter)|OBSIZE]]</td>
<td>Specifies the size of the TCP/IP output buffer.</td></tr>

<tr><td>[[OMNIACCT (JANUS DEFINE parameter)|OMNIACCT]]</td>
<td>Specifies the <var class="product">Model 204</var> <var>ACCOUNT</var> for the <var class="product">Janus Specialty Data Store</var> catalog [[Sdaemons|sdaemon]] for the port.</td></tr>

<tr><td>[[OMNIUSER (JANUS DEFINE parameter)|OMNIUSER]]</td>
<td>Specifies the <var class="product">Model 204</var> user ID for the <var class="product">Janus Specialty Data Store</var> catalog sdaemon for the port.</td></tr>

<tr><td>[[OPEN (JANUS DEFINE parameter)|OPEN]]</td>
<td>Specifies the name of one or more <var class="product">Model 204</var> files or groups to be opened when a server session is initiated.</td></tr>

<tr><td>[[PASVPORT (JANUS DEFINE parameter)|PASVPORT]]</td>
<td>Identifies the first <var>FTP</var> server port number to use for "passive" file transfers.</td></tr>

<tr><td>[[PRELOGINUSER (JANUS DEFINE parameter)|PRELOGINUSER]]</td>
<td>Indicates the userid under which pre-login processing runs.</td></tr>

<tr><td>[[PRSTOK (JANUS DEFINE parameter)|PRSTOK]]</td>
<td>Specifies the hex values of strings that are used to separate input strings using the <var>[[$Sock_RecvPrs]]</var> function or <var>Socket</var> <var>[[ReceiveAndParse (Socket function)|ReceiveAndParse]]</var> function. </td></tr>

<tr><td>[[PUBLOG (JANUS DEFINE parameter)|PUBLOG]]</td>
<td>Indicates that a "real" login should be done for the <var>SOCKUSER</var> userid for <var>SRVSOCK</var> logons.</td></tr>

<tr><td>[[RAWHEADER (JANUS DEFINE parameter)|RAWHEADER]]</td>
<td>Tells <var class="product">Janus Web Server</var> to save the raw web request header stream.</td></tr>

<tr><td>[[RAWINPUT (JANUS DEFINE parameter)|RAWINPUT]]</td>
<td>Tells <var class="product">Janus Web Server</var> to save the raw input stream for an HTTP POST, regardless of the mime type set by the client in the <code>content-type</code> header.</td></tr>

<tr><td>[[RAWINPUTONLY (JANUS DEFINE parameter)|RAWINPUTONLY]]</td>
<td>indicates that, regardless of the POST data content-type set by the client, <var class="product">Janus Web Server</var> should: 1) Save the raw input stream of an HTTP POST and 2) Refrain from parsing the input content into form fields.</td></tr>

<tr><td>[[RBSIZE (JANUS DEFINE parameter)|RBSIZE]]</td>
<td>Specifies the Janus RPC or Request buffer size.</td></tr>

<tr><td>[[REMOTE (JANUS DEFINE parameter)|REMOTE]]</td>
<td>Identifies the remote server and the remote port number to be used with a set of <var class="product">Janus Sockets</var> <var>CLSOCK</var> connections.</td></tr>

<tr><td>[[RPCONLY (JANUS DEFINE parameter)|RPCONLY]]</td>
<td>Indicates that only RPC requests are allowed on the port.</td></tr>

<tr><td>[[SCREEN and NOSCREEN (JANUS DEFINE parameters)|SCREEN and NOSCREEN]]</td>
<td>Indicates whether or not <var class="product">Janus Web Legacy</var> screens will be allowed to appear on requests to the port.</td></tr>

<tr><td>[[SCREENTHROW and NOSCREENTHROW (JANUS DEFINE parameters)|SCREENTHROW and NOSCREENTHROW]]</td>
<td>Indicates whether or not <var class="product">Janus Web Legacy</var> client errors will cause an exception to be thrown.</td></tr>

<tr><td>[[SCREENURL (JANUS DEFINE parameter)|SCREENURL]]</td>
<td>Indicates that <var class="product">Janus Web Server</var> legacy support (automatic mapping of 3270
applications to HTML) is to switch web applications that present a 3270 screen to a special internally generated URL.</td></tr>

<tr><td>[[SDSACCT (JANUS DEFINE parameter)|SDSACCT]]</td>
<td>Specifies the <var class="product">Model 204</var> <var>ACCOUNT</var> for the <var class="product">Janus Specialty Data Store</var> catalog sdaemon for the port.</td></tr>

<tr><td>[[SDSUSER (JANUS DEFINE parameter)|SDSUSER]]</td>
<td>specifies the <var class="product">Model 204</var> <var>USER</var> for the <var class="product">Janus Specialty Data Store</var> catalog sdaemon for the port.</td></tr>

<tr><td>[[SESCOOKIE (JANUS DEFINE parameter)|SESCOOKIE]]</td>
<td>Indicates the name of a cookie that will be used to maintain logical sessions that will be used to perform trusted logins.</td></tr>

<tr><td>[[SESCOOKIENOSEC (JANUS DEFINE parameter)|SESCOOKIENOSEC]]</td>
<td>Indicates that the cookie specified by <var>SESCOOKIE</var> will '''not''' be sent to the browser as a "secure" cookie.</td></tr>

<tr><td>[[SESFASTLOGIN (JANUS DEFINE parameter)|SESFASTLOGIN]]</td>
<td>Reduces the login security overhead for <var class="product">Janus Web Server</var> threads by causing a login performed for a continued session to be a "fast" login.</td></tr>

<tr><td>[[SESTIMEOUT (JANUS DEFINE parameter)|SESTIMEOUT]]</td>
<td>Indicates the number of minutes of inactivity that will cause a logical login session being held either via <var>SESCOOKIE</var> or <var>SSLSES</var> to be terminated.</td></tr>

<tr><td>[[SLOWCLOSE (JANUS DEFINE parameter)|SLOWCLOSE]]</td>
<td>Specifies a bitmask that indicates the conditions under which <var class="product">Janus Web Server</var> is to perform a "slow" close of a connection with a browser.</td></tr>

<tr><td>[[SOCKACCT (JANUS DEFINE parameter)|SOCKACCT]]</td>
<td>Specifies the default <var class="product">Model 204</var> account ID used for <var>SRVSOCK</var> logons.</td></tr>

<tr><td>[[SOCKPMAX (JANUS DEFINE parameter)|SOCKPMAX]]</td>
<td>Specifies the maximum number of sockets a user may have connected at any time using the particular <var class="product">Janus Sockets</var> client port.</td></tr>

<tr><td>[[SOCKUSER (JANUS DEFINE parameter)|SOCKUSER]]</td><td>Specifies the default <var class="product">Model 204</var> user ID used for <var>SRVSOCK</var> logons.</td></tr>

<tr><td>[[SQUAREB (JANUS DEFINE parameter)|SQUAREB]]</td><td>Overrides the default EBCDIC characters for square brackets in the <var class="product">Janus Web Server</var> log file.</td></tr>

<tr><td>[[SSL (JANUS DEFINE parameter)|SSL]]</td><td>Indicates that communications on this port should be encrypted using SSL (Secure Sockets Layer) or TLS (Transport Layer Security) support.</td></tr>

<tr><td>[[SSLBSIZE (JANUS DEFINE parameter)|SSLBSIZE]]</td><td>Specifies the size of the input and output buffers used for reading encrypted data for an <var>SSL</var> port.</td></tr>

<tr><td>[[SSLCACHE (JANUS DEFINE parameter)|SSLCACHE]]</td><td>Specifies the number of entries in virtual storage to be allocated for caching information related to this port's SSL sessions.</td></tr>

<tr><td>[[SSLCIPH (JANUS DEFINE parameter)|SSLCIPH]]</td><td>Limit the stream ciphers (encryption algorithms) that this port offers for SSL connections.</td></tr>

<tr><td>[[SSLCLCERT and SSLCLCERTR (JANUS DEFINE parameters)|SSLCLCERT and SSLCLCERTR]]</td><td>Specify that an <var>SSL</var> server port will request an SSL certificate from the client.</td></tr>

<tr><td>[[SSLIBSIZE (JANUS DEFINE parameter)|SSLIBSIZE]]</td><td>Specifies the size of the SSL input buffer to be used on <var>SSL</var> ports.</td></tr>

<tr><td>[[SSLMAXAGE (JANUS DEFINE parameter)|SSLMAXAGE]]</td><td>Specifies the maximum number of minutes that an SSL session is to be maintained.</td></tr>

<tr><td>[[SSLMAXCERTL (JANUS DEFINE parameter)|SSLMAXCERTL]]</td><td>Indicates the number of bytes of virtual storage to be allocated to hold incoming certificates presented for authentication.</td></tr>

<tr><td>[[SSLOBSIZE (JANUS DEFINE parameter)|SSLOBSIZE]]</td><td>Specifies the size of the SSL output buffer to be used on <var>SSL</var> ports.</td></tr>

<tr><td>[[SSLOPT (JANUS DEFINE parameter)|SSLOPT]]</td><td>Specifies that the use of SSL-like encryption is optional for applications using the port.</td></tr>

<tr><td>[[SSLPROT (JANUS DEFINE parameter)|SSLPROT]]</td><td>Specify the degree of SSL-like encryption available at this port.</td></tr>

<tr><td>[[SSLSES (JANUS DEFINE parameter)|SSLSES]]</td><td>Reduces the overhead of <var>NEWSESCMD</var> processing by limiting it to logical session establishment time.</td></tr>

<tr><td>[[SSLTRUST (JANUS DEFINE parameter)|SSLTRUST]]</td><td>Indicates that the certificate presented by the other side of a TLS/SSL connection is to be trusted, even if it is not signed by a known certifying authority. This parameter is only available in Model 204 7.7 and later.</td></tr>

<tr><td>[[SSLUNENC (JANUS DEFINE parameter)|SSLUNENC]]</td><td>Indicates that an unencrypted private key is being used in the certificate specified by the <var>SSL</var> parameter on this Janus server port definition.</td></tr>

<tr><td>[[STIMEOUT (JANUS DEFINE parameter)|STIMEOUT]]</td><td>Sets the number of seconds of inactivity after which a <var class="product">Janus Web Legacy</var> session is terminated.</td></tr>

<tr><td>[[TCPLOG (JANUS DEFINE parameter)|TCPLOG]]</td><td>Tells <var class="product">Janus Web Server</var> to log in a sequential dataset all inbound and outbound TCP data transmitted for this port.</td></tr>

<tr><td>[[TCPKEEPALIVE (JANUS DEFINE parameter)|TCPKEEPALIVE]]</td><td>Specifies that connections on the port should use TCP keepalives.</td></tr>

<tr><td>[[TCPKEEPALIVETIME (JANUS DEFINE parameter)|TCPKEEPALIVETIME]]</td><td>Specifies the time interval, in seconds, that TCP keepalive probes are to be sent.</td></tr>

<tr><td>[[TIMEOUT (JANUS DEFINE parameter)|TIMEOUT]]</td><td>Specifies the number of seconds of inactivity after which clients connected to this port will be disconnected.</td></tr>

<tr><td>[[TIMEZONE (JANUS DEFINE parameter)|TIMEZONE]]</td><td>A string indicating the [https://www.iana.org/time-zones IANA time zone] under which the Online is running. This parameter is only valid for <var>IMAGINET</var> ports.</td></tr>

<tr><td>[[TRACE (JANUS DEFINE parameter)|TRACE]]</td><td>Specifies the initial <var>TRACE</var> setting for the port.</td></tr>

<tr><td>[[UPCASE (JANUS DEFINE parameter)|UPCASE]]</td><td>Indicates that all client "names" are to be converted to uppercase.</td></tr>

<tr><td>[[VARIPADDR (JANUS DEFINE parameter)|VARIPADDR]]</td><td>Indicates that a single browser might access <var class="product">Janus Web Server</var> using different IP addresses.</td></tr>

<tr><td>[[WEBACCT (JANUS DEFINE parameter)|WEBACCT]]</td><td>Specifies the default <var class="product">Model 204</var> account ID used for web logons for URLs where no userid is required.</td></tr>

<tr><td>[[WEBCOOKID (JANUS DEFINE parameter)|WEBCOOKID]]</td><td>Indicates that an identifying "cookie" should be sent to a browser to distinguish multiple browsers coming through the same proxy server or running on the same machine.</td></tr>

<tr><td>[[WEBLH (JANUS DEFINE parameter)|WEBLH]]</td><td>Synonym for <var>WEBLOGHOLD</var>.</td></tr>

<tr><td>[[WEBLM (JANUS DEFINE parameter)|WEBLM]]</td><td>Synonym for <var>WEBLOGMAX</var>.</td></tr>

<tr><td>[[WEBLOGCOOKIE (JANUS DEFINE parameter)|WEBLOGCOOKIE]]</td><td>Indicates that, for public URLs, <var class="product">Janus Web Server</var> should log the user in with the userid specified by cookie-name. Normally, all public URL logins use the default public userid (usually <var>WEBUSER</var>).</td></tr>

<tr><td>[[WEBLOGHOLD (JANUS DEFINE parameter)|WEBLOGHOLD]]</td><td>Indicates the number of seconds that a "real" login should be saved for re-use on a web connection.</td></tr>

<tr><td>[[WEBLOGMAX (JANUS DEFINE parameter)|WEBLOGMAX]]</td><td>Indicates the maximum number of cached login sessions to be held for a single user.</td></tr>

<tr><td>[[WEBPL (JANUS DEFINE parameter)|WEBPL]]</td><td>Synonym for <var>WEBPUBLOG</var>.</td></tr>

<tr><td>[[WEBPUBLOG (JANUS DEFINE parameter)|WEBPUBLOG]]</td><td>Indicates that a "real" login should be done for the <var>WEBUSER</var> <var class="term">userid</var> for public URLs.</td></tr>

<tr><td>[[WEBREALM (JANUS DEFINE parameter)|WEBREALM]]</td><td>Indicates the security "realm" of userids and passwords.</td></tr>

<tr><td>[[WEBSDMAX (JANUS DEFINE parameter)|WEBSDMAX]]</td><td>Indicates the maximum number of sdaemons to be used for cached web logins.</td></tr>

<tr><td>[[WEBSM (JANUS DEFINE parameter)|WEBSM]]</td><td>Synonym for <var>WEBSDMAX</var>.</td></tr>
<tr><td>[[WEBSOCKET and NOWEBSOCKET (JANUS DEFINE parameters)|WEBSOCKET and NOWEBSOCKET ]]</td><td>Indicates whether or not the port will negotiate with a client to upgrade to the Web Socket protocol. </td></tr>

<tr><td>[[WEBUSER (JANUS DEFINE parameter)|WEBUSER]]</td><td>Specifies the default <var class="product">Model 204</var> user ID used for web logons for URLs where no userid is required.</td></tr>

<tr><td>[[WSFQUERY (JANUS DEFINE parameter)|WSFQUERY]]</td><td>Indicates that Janus is to issue a "Write Structured Field Query" request to any Telnet client that connects to it.</td></tr>

<tr><td>[[XMLSCREEN and NOXMLSCREEN (JANUS DEFINE parameters)|XMLSCREEN and NOXMLSCREEN]]</td><td>Sets XML screen mode (<var class="product">[[Janus Web Legacy XML Support]]</var>) characteristics for <var class="product">[[Janus Web Legacy Support]]</var> screens.</td></tr>

<tr><td>[[XMLSCREENFIELD and NOXMLSCREENFIELD (JANUS DEFINE parameters)|XMLSCREENFIELD and NOXMLSCREENFIELD]]</td><td>Indicates whether or not a screenField attribute is to be added to <var class="product">Janus Web Legacy Support</var> pages.</td></tr>

<tr><td>[[XMLSCREENREPUC (JANUS DEFINE parameter)|XMLSCREENREPUC]]</td><td>Specifies a Unicode character with which to replace an XMLSCREEN input character that cannot be translated to EBCDIC.</td></tr>

<tr><td>[[XMLNULLSCANCEL and XMLNULLSSEND (JANUS DEFINE parameters)|XMLNULLSCANCEL and XMLNULLSSEND]]</td><td>Sets XML screen mode (<var class="product">[[Janus Web Legacy XML Support]]</var>) response to nulls for <var class="product">[[Janus Web Legacy Support]]</var> screens.</td></tr>

<tr><td>[[XMLNULLSSTRIP and XMLNULLSBLANK (JANUS DEFINE parameters)|XMLNULLSSTRIP and XMLNULLSBLANK]]</td><td>Sets an XML screen mode (<var class="product">Janus Web Legacy XML Support</var>) null-replacement option for <var class="product">Janus Web Legacy Support</var> screens.</td></tr>

<tr><td>[[XTAB (JANUS DEFINE parameter)|XTAB]]</td><td>Specifies a translation table that has not yet been loaded with the <var>JANUS LOADXT</var> command, but the table must be loaded before the port can be started.</td></tr>
</table>

==See also==
<ul>
<li>[[List of Janus commands]]
<li>[[JANUS DEFINE#parmlist|List of JANUS DEFINE parameters]]
<li>[[Janus port processing and examples]]
</ul>

[[Category:JANUS DEFINE parameters|JANUS DEFINE]]
[[Category:Janus commands]]
[[Category:Janus Web Server]]

TCPKEEPALIVETIME (JANUS DEFINE parameter)

2025-06-23T02:06:19Z

Alex: Created page with "Set TCP Keepalive time interval <var>TCPKEEPALIVE</var> is a parameter on <var>JANUS DEFINE</var>, which defines and sets characteristics of a Janus port. This parameter specifies the time interval in seconds between TCP keepalive packets sent on active connections to test if they are, in fact, still connected. <var>TCPKEEPALIVETIME</var> has no effect unless the TCPKEEPALIVE parameter is..."

Set TCP Keepalive time interval

<var>TCPKEEPALIVE</var> is a parameter on <var>[[JANUS DEFINE]]</var>, which defines and sets characteristics of a Janus port.

This parameter specifies the time interval in seconds between TCP keepalive packets sent on active connections to test if they are, in fact, still connected.

<var>TCPKEEPALIVETIME</var> has no effect unless the [[TCPKEEPALIVE (JANUS DEFINE parameter)|TCPKEEPALIVE]] parameter is also set to enable TCP keepalives.

Since the TCP/IP stack does the keepalives, the overhead in <var class="product">Model 204</var> for setting this parameter is virtually zero.

If not set, or set to 0, and <var>TCPKEEPALIVE</var> the TCP stack's default keepalive intervale is used. This interval is usually 7200 (2 hours), a value so high that it renders TCP keepalives virtually useless.

This parameter is only available in <var class="product">Model 204</var> Version 8.0 and later.

<var>TCPKEEPALIVETIME</var> is valid for all port types.

==See also==
<ul>
<li>[[List of Janus commands]]
<li>[[JANUS DEFINE#parmlist|List of JANUS DEFINE parameters]]
</ul>

[[Category:JANUS DEFINE parameters|TCPKEEPALIVETIME]]

IMAGINE command

2025-06-04T23:37:55Z

Alex:

{{DISPLAYTITLE:IMAGINE command}}
Move Model 204 data to Imagine

This command provides the facilities to extract <var>Model 204</var> data and load it into <var>Imagine</var>.

==Summary==
<dl>
<dt>Privileges</dt>
<dd>File manager</dd>
<dt>Function</dt>
<dd>provides the facilities to extract <var>Model 204</var> data and load it into <var>Imagine</var>.</dd>
</dl>

==Syntax for IMAGINE==
IMAGINE SYNC | EXTRACT [NOCOMMIT] [TICK t] [MAXPENDING m] [MAXERR e]


Where:
<ul>
<li><var class="term">SYNC</var> indicates that data is to be extracted and the <var>Model 204</var> file and <var>Imagine</var> are to be kept in sync after the command.</li>
<li><var class="term">EXTRACT</var> indicates that data is to be extracted but the <var>Model 204</var> file and <var>Imagine</var> are not to be kept in sync after the command.</li>
<li><var class="term">NOCOMMIT</var> indicates that the data is to be sent to Imagine and processed, but not committed. This provides a way of validating that a file can be loaded into <var>Imagine</var> without actually doing so. This option makes no sense for a SYNC extract so is only allowed with <code>IMAGINE EXTRACT</code>.</li>
<li><var class="term">TICK</var> indicates the number of records between progress messages (M204.3073) to the journal. This parameter also sets the frequency of progress messages on <var>Imagine</var>. <var>TICK</var> defaults to 100000.</li>
<li><var class="term">MAXPENDING</var> indicates the maximum number of uncommitted record sends to be allowed in the extract. Setting this to a low value could result in reduced transfer rates because of network latency. <var>MAXPENDING</var> defaults to 4095.</li>
<li><var class="term">MAXERR</var> indicates the maximum number of record data errors allowed before the extract is aborted. One might wish to set this to a high value for an extract intended to scan a file for data integrity errors. Because records are sent asynchronously in batches, it's quite possible for the actual number of errors to exceed the <var>MAXERROR</var> value. <var>MAXERROR</var> defaults to 50.</li>
</ul>

There is also a format of the IMAGINE command:
IMAGINE ENDSYNC


That indicates a SYNC or EXTRACT for the file should be terminated.

===Syntax notes===

The IMAGINE command operates on the context file which is either the current file or one
explicitly specified before the command as in:

IN FILE FOOBAR EXTRACT NOCOMMIT


==Example==

To put file FOO into sync mode, one can do:

OPEN FILE FOO
IMAGINE SYNC TICK 200000
The <var>TICK</var> keyword indicates that a M204.3073 message should be issued every 200,000
records. If one wishes to see these messages on the operator console, one can do:
MSGCTL M204.3073 OPR


Note that the actual extraction of records is done on a daemon thread created by the
IMAGINE command so the thread that issued the IMAGINE command would return fairly
quickly. Also note that this means that there is no terminal for M204.3073 (or other)
messages issued during the extract to appear, so one needs to look in the journal
for errors, should they occur.

==Usage notes==

To obtain a consistent view of the file on <var>Imagine</var>, the IMAGINE command
first quiesces the file; that is, ensures that no updating transactions that had
updated the file are active. This will usually take less than a second, but a long
running transaction that had updated the file could make this take quite a while.
As such, it is recommended that the IMAGINE command be issued at a relatively quiet
time in terms of file updates.


Once the extraction process has begun, whether <var>SYNC</var>, <var>EXTRACT</var>,
or <var>NOCOMMIT</var>, any other thread that wishes to update a record in the file
being extracted, cannot update the record until it has been copied to <var>Imagine</var> and
committed. If it has already been done at the time of the commit, no wait is required.
However, if the record has not been copied to and committed to <var>Imagine</var> the
thread would send a request to the extracting daemon to immediately send the record to
<var>Imagine</var> (if not already sent) and then to wake the updating thread when that
record is committed on <var>Imagine</var>. This can cause a slight delay in update
processing so, again, the recommendation is for extracts to be done at relatively quiet
times for a file.


If a file is in SYNC mode, once a record has been sent to <var>Imagine</var>, any updates
to the file are sent to <var>Imagine</var> (via a broker connection) and those updates
must be committed for the transaction to succeed. That is, if some error occurs on
<var>Imagine</var> for a SYNC update, the request would be cancelled and the transaction
backed out. Note that this processing occurs even after the file has been fully extracted,
and the extracting daemon is no longer active. This ensures that the SYNC'ed file will
remain consistent between <var>Model 204</var> and <var>Imagine</var> making it feasible
to switch the file to transparency mode with a minimal outage.


For a plain EXTRACT (as opposed to SYNC), updates to records in the file after they have
committed in <var>Imagine</var> are not sent to <var>Imagine</var>, so the file can
get out of synch between <var>Model 204</var> and <var>Imagine</var>. However, by not
allowing any records to be updated in the file during the EXTRACT process until they
have been committed on <var>Imagine</var>, the file on <var>Imagine</var> will be ensured
to be a consistent view of the file as of the point in the <code>IMAGINE EXTRACT</code>
command where updates to the file had been quiesced.


==See also==
<ul>
<li>[[Imagine Transparency]]</li>
</ul>

[[Category: File manager commands]]
[[Category:Commands]]

IMAGINE command

2025-05-02T14:07:27Z

Alex: /* Syntax for IMAGINE */

{{DISPLAYTITLE:IMAGINE command}}
Move Model 204 data to Imagine

This command provides the facilities to extract <var>Model 204</var> data and load it into <var>Imagine</var>.

==Summary==
<dl>
<dt>Privileges</dt>
<dd>File manager</dd>
<dt>Function</dt>
<dd>provides the facilities to extract <var>Model 204</var> data and load it into <var>Imagine</var>.</dd>
</dl>

==Syntax for IMAGINE==
IMAGINE SYNC | EXTRACT [NOCOMMIT] [TICK t] [MAXPENDING m]


Where:
<ul>
<li><var class="term">SYNC</var> indicates that data is to be extracted and the <var>Model 204</var> file and <var>Imagine</var> are to be kept in sync after the command.</li>
<li><var class="term">EXTRACT</var> indicates that data is to be extracted but the <var>Model 204</var> file and <var>Imagine</var> are not to be kept in sync after the command.</li>
<li><var class="term">NOCOMMIT</var> indicates that the data is to be sent to Imagine and processed, but not committed. This provides a way of validating that a file can be loaded into <var>Imagine</var> without actually doing so. This option makes no sense for a SYNC extract so is only allowed with <code>IMAGINE EXTRACT</code>.</li>
<li><var class="term">TICK</var> indicates the number of records between progress messages (M204.3073) to the journal. This parameter also sets the frequency of progress messages on <var>Imagine</var>. <var>TICK</var> defaults to 100000.</li>
<li><var class="term">MAXPENDING</var> indicates the maximum number of uncommitted record sends to be allowed in the extract. Setting this to a low value could result in reduced transfer rates because of network latency. <var>MAXPENDING</var> defaults to 4095.</li>
</ul>

There is also a format of the IMAGINE command:
IMAGINE ENDSYNC


That indicates a SYNC or EXTRACT for the file should be terminated.

===Syntax notes===

The IMAGINE command operates on the context file which is either the current file or one
explicitly specified before the command as in:

IN FILE FOOBAR EXTRACT NOCOMMIT


==Example==

To put file FOO into sync mode, one can do:

OPEN FILE FOO
IMAGINE SYNC TICK 200000
The <var>TICK</var> keyword indicates that a M204.3073 message should be issued every 200,000
records. If one wishes to see these messages on the operator console, one can do:
MSGCTL M204.3073 OPR


Note that the actual extraction of records is done on a daemon thread created by the
IMAGINE command so the thread that issued the IMAGINE command would return fairly
quickly. Also note that this means that there is no terminal for M204.3073 (or other)
messages issued during the extract to appear, so one needs to look in the journal
for errors, should they occur.

==Usage notes==

To obtain a consistent view of the file on <var>Imagine</var>, the IMAGINE command
first quiesces the file; that is, ensures that no updating transactions that had
updated the file are active. This will usually take less than a second, but a long
running transaction that had updated the file could make this take quite a while.
As such, it is recommended that the IMAGINE command be issued at a relatively quiet
time in terms of file updates.


Once the extraction process has begun, whether <var>SYNC</var>, <var>EXTRACT</var>,
or <var>NOCOMMIT</var>, any other thread that wishes to update a record in the file
being extracted, cannot update the record until it has been copied to <var>Imagine</var> and
committed. If it has already been done at the time of the commit, no wait is required.
However, if the record has not been copied to and committed to <var>Imagine</var> the
thread would send a request to the extracting daemon to immediately send the record to
<var>Imagine</var> (if not already sent) and then to wake the updating thread when that
record is committed on <var>Imagine</var>. This can cause a slight delay in update
processing so, again, the recommendation is for extracts to be done at relatively quiet
times for a file.


If a file is in SYNC mode, once a record has been sent to <var>Imagine</var>, any updates
to the file are sent to <var>Imagine</var> (via a broker connection) and those updates
must be committed for the transaction to succeed. That is, if some error occurs on
<var>Imagine</var> for a SYNC update, the request would be cancelled and the transaction
backed out. Note that this processing occurs even after the file has been fully extracted,
and the extracting daemon is no longer active. This ensures that the SYNC'ed file will
remain consistent between <var>Model 204</var> and <var>Imagine</var> making it feasible
to switch the file to transparency mode with a minimal outage.


For a plain EXTRACT (as opposed to SYNC), updates to records in the file after they have
committed in <var>Imagine</var> are not sent to <var>Imagine</var>, so the file can
get out of synch between <var>Model 204</var> and <var>Imagine</var>. However, by not
allowing any records to be updated in the file during the EXTRACT process until they
have been committed on <var>Imagine</var>, the file on <var>Imagine</var> will be ensured
to be a consistent view of the file as of the point in the <code>IMAGINE EXTRACT</code>
command where updates to the file had been quiesced.


==See also==
<ul>
<li>[[Imagine Transparency]]</li>
</ul>

[[Category: File manager commands]]
[[Category:Commands]]

IMAGINE command

2025-05-02T11:30:21Z

Alex:

{{DISPLAYTITLE:IMAGINE command}}
Move Model 204 data to Imagine

This command provides the facilities to extract <var>Model 204</var> data and load it into <var>Imagine</var>.

==Summary==
<dl>
<dt>Privileges</dt>
<dd>File manager</dd>
<dt>Function</dt>
<dd>provides the facilities to extract <var>Model 204</var> data and load it into <var>Imagine</var>.</dd>
</dl>

==Syntax for IMAGINE==
IMAGINE SYNC | EXTRACT [NOCOMMIT] [TICK t] [MAXPENDING m]


Where:
<ul>
<li><var class="term">SYNC</var> indicates that data is to be extracted and the <var>Model 204</var> file and <var>Imagine</var> are to be kept in sync after the command.</li>
<li><var class="term">EXTRACT</var> indicates that data is to be extracted but the <var>Model 204</var> file and <var>Imagine</var> are not to be kept in sync after the command.</li>
<li><var class="term">NOCOMMIT</var> indicates that the data is to be sent to Imagine and processed, but not committed. This provides a way of validating that a file can be loaded into <var>Imagine</var> without actually doing so.</li>
<li><var class="term">TICK</var> indicates the number of records between progress messages (M204.3073) to the journal. This parameter also sets the frequency of progress messages on <var>Imagine</var>. <var>TICK</var> defaults to 100000.</li>
<li><var class="term">MAXPENDING</var> indicates the maximum number of uncommitted record sends to be allowed in the extract. Setting this to a low value could result in reduced transfer rates because of network latency. <var>MAXPENDING</var> defaults to 4095.</li>
</ul>

There is also a format of the IMAGINE command:
IMAGINE ENDSYNC


That indicates a SYNC or EXTRACT for the file should be terminated.

===Syntax notes===

The IMAGINE command operates on the context file which is either the current file or one
explicitly specified before the command as in:

IN FILE FOOBAR EXTRACT NOCOMMIT


==Example==

To put file FOO into sync mode, one can do:

OPEN FILE FOO
IMAGINE SYNC TICK 200000
The <var>TICK</var> keyword indicates that a M204.3073 message should be issued every 200,000
records. If one wishes to see these messages on the operator console, one can do:
MSGCTL M204.3073 OPR


Note that the actual extraction of records is done on a daemon thread created by the
IMAGINE command so the thread that issued the IMAGINE command would return fairly
quickly. Also note that this means that there is no terminal for M204.3073 (or other)
messages issued during the extract to appear, so one needs to look in the journal
for errors, should they occur.

==Usage notes==

To obtain a consistent view of the file on <var>Imagine</var>, the IMAGINE command
first quiesces the file; that is, ensures that no updating transactions that had
updated the file are active. This will usually take less than a second, but a long
running transaction that had updated the file could make this take quite a while.
As such, it is recommended that the IMAGINE command be issued at a relatively quiet
time in terms of file updates.


Once the extraction process has begun, whether <var>SYNC</var>, <var>EXTRACT</var>,
or <var>NOCOMMIT</var>, any other thread that wishes to update a record in the file
being extracted, cannot update the record until it has been copied to <var>Imagine</var> and
committed. If it has already been done at the time of the commit, no wait is required.
However, if the record has not been copied to and committed to <var>Imagine</var> the
thread would send a request to the extracting daemon to immediately send the record to
<var>Imagine</var> (if not already sent) and then to wake the updating thread when that
record is committed on <var>Imagine</var>. This can cause a slight delay in update
processing so, again, the recommendation is for extracts to be done at relatively quiet
times for a file.


If a file is in SYNC mode, once a record has been sent to <var>Imagine</var>, any updates
to the file are sent to <var>Imagine</var> (via a broker connection) and those updates
must be committed for the transaction to succeed. That is, if some error occurs on
<var>Imagine</var> for a SYNC update, the request would be cancelled and the transaction
backed out. Note that this processing occurs even after the file has been fully extracted,
and the extracting daemon is no longer active. This ensures that the SYNC'ed file will
remain consistent between <var>Model 204</var> and <var>Imagine</var> making it feasible
to switch the file to transparency mode with a minimal outage.


For a plain EXTRACT (as opposed to SYNC), updates to records in the file after they have
committed in <var>Imagine</var> are not sent to <var>Imagine</var>, so the file can
get out of synch between <var>Model 204</var> and <var>Imagine</var>. However, by not
allowing any records to be updated in the file during the EXTRACT process until they
have been committed on <var>Imagine</var>, the file on <var>Imagine</var> will be ensured
to be a consistent view of the file as of the point in the <code>IMAGINE EXTRACT</code>
command where updates to the file had been quiesced.


==See also==
<ul>
<li>[[Imagine Transparency]]</li>
</ul>

[[Category: File manager commands]]
[[Category:Commands]]

IMAGINE command

2025-05-02T10:47:13Z

Alex: /* Syntax for IMAGINE */

IMAGINE command

2025-05-02T10:47:01Z

Alex: /* Syntax for IMAGINE */

IMAGINE command

2025-05-02T03:34:08Z

Alex: Created page with "{{DISPLAYTITLE:IMAGINE command}} Move Model 204 data to Imagine This command provides the facilities to extract <var>Model 204</var> data and load it into <var>Imagine</var>. ==Summary== <dl> <dt>Privileges</dt> <dd>File manager</dd> <dt>Function</dt> <dd>provides the facilities to extract <var>Model 204</var> data and load it into <var>Imagine</var>.</dd> </dl> ==Syntax for IMAGINE== IMAGINE SYNC | EXTRACT [NOCOMMIT..."

$CurrecId

2025-03-28T21:45:50Z

Alex: /* Usage notes */

The <var>$CurrecId</var> function returns the <var class="product">Imagine Transparency</var> recordId for current (innermost) record <var>For</var> loop. If the current record is in a file that is not an <var class="product">Imagine Transparency</var> file, an empty string is returned.


<var>$CurrecId</var> takes no arguments.


==Usage notes==

The recordId for <var class="product">Imagine</var> associated records is an 8-byte binary string value. This can be used to create another <var>Record</var> object with the [[NewFromRecordId (Record function)|NewFromRecordId]] function though there is really no good reason to create another <var>Record</var> object this way, or it could be passed to the <var class="product">Imagine</var> broker, probably after converting it to hex. Note, however, that while recordIds uniquely identify any record in <var class="product">Imagine</var>, <var class="product">Imagine</var> still needs to know the <var class="product">Imagine</var> file that holds the record to locate it. This can be obtained using the [[$CurImagineFile|CurImagineFile function]].


The [[CurrentRecordId (Record function)|CurrentRecordId]] method provides identical functionality using O-O syntax.

$CurImagineFile

2025-03-28T21:43:01Z

Alex: Created page with " The <var>$CurrecImagineFile</var> function returns the conatining <var class="product">Imagine</var> filename for the current (innermost) record <var>For</var> loop. If the current record is in a file that is not an <var class="product">Imagine Transparency</var> file, an empty string is returned. <var>$CurImagineFile</var> takes no arguments. ==Usage notes== The <var class="product">Imagine</var> filename can be used with a recordId obtained via..."

The <var>$CurrecImagineFile</var> function returns the conatining <var class="product">Imagine</var> filename for the current (innermost) record <var>For</var> loop. If the current record is in a file that is not an <var class="product">Imagine Transparency</var> file, an empty string is returned.


<var>$CurImagineFile</var> takes no arguments.


==Usage notes==

The <var class="product">Imagine</var> filename can be used with a recordId obtained via the [[$CurrecId|$CurrecId function]] to allow an <var class="product">Imagine</var> application to easily locate a record.


The [[CurrentImagineFile (Record function)|CurrentImagine]] method provides identical functionality using O-O syntax.

CurrentRecordId (Record function)

2025-03-28T21:35:48Z

Alex:

{{Template:Record:CurrentRecordId subtitle}}

Get the <var class="product">Imagine Transparency</var> recordId for current (innermost) record <var>For</var> loop.
==Syntax==
{{Template:Record:CurrentRecordId syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%string</th><td>The recordId of the <var>For</var> loop record on <var class="product">Imagine</var> if the record is in a file that is an <var class="product">Imagine Transparency</var> file, or an empty string, otherwise.</td></tr>
<tr><th nowrap="true"><var>%(Record In </var>filOrGrp name<var>)</var></th>
<td>The class name in parentheses denotes a shared method. <var>CurrentRecordId</var> can also be invoked via a <var>Record</var> object variable, which may be <var>Null</var>.</td></tr>
</table>
==Usage notes==

The recordId for <var class="product">Imagine</var> associated records is an 8-byte binary string value. This can be used to create another <var>Record</var> object with the [[NewFromRecordId (Record function)|NewFromRecordId]] function though there is really no good reason to create another <var>Record</var> object this way, or it could be passed to the <var class="product">Imagine</var> broker, probably after converting it to hex. Note, however, that while recordIds uniquely identify any record in <var class="product">Imagine</var>, <var class="product">Imagine</var> still needs to know the <var class="product">Imagine</var> file that holds the record to locate it. This can be obtained using the [[CurrentImagineFile (Record function)|CurrentImagineFile]] method.


==Examples==
==See also==
{{Template:Record:CurrentRecordId footer}}

CurrentImagineFile (Record function)

2025-03-28T21:34:25Z

Alex:

{{Template:Record:CurrentImagineFile subtitle}}

Get the name of the containing <var class="product">Imagine</var> file for current (innermost) record <var>For</var> loop.
==Syntax==
{{Template:Record:CurrentImagineFile syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%string</th><td>The name of the containing <var class="product">Imagine</var> file for the current <var>For</var> loop record, if the record is in an <var class="product">Imagine Transparency</var> file, or an empty string, otherwise.</td></tr>
<tr><th nowrap="true"><var>%(Record In </var>filOrGrp name<var>)</var></th>
<td>The class name in parentheses denotes a shared method. <var>CurrentImagineFile</var> can also be invoked via a <var>Record</var> object variable, which may be <var>Null</var>.</td></tr>
</table>
==Usage notes==
The <var class="product">Imagine</var> filename can be used with a recordId obtained via the [[CurrentRecordId (Record function)|CurrentRecordId method]] to allow an <var class="product">Imagine</var> application to easily locate a record.
==See also==
{{Template:Record:CurrentImagineFile footer}}

RecordId (Record function)

2025-03-28T21:28:45Z

Alex:

{{Template:Record:RecordId subtitle}}

Get the <var class="product">Imagine Transparency</var> recordId for the <var>Record</var> object.
==Syntax==
{{Template:Record:RecordId syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%string</th><td>The recordId of the record on <var class="product">Imagine</var> if the record is in a file that is an <var class="product">Imagine Transparency</var> file, or an empty string, otherwise.</td></tr>
<tr><th>record</th>
<td><var>Record</var> object</td></tr>
</table>

==Usage notes==

The recordId for <var class="product">Imagine</var> associated records is an 8-byte binary string value. This can be used to create another <var>Record</var> object with the [[NewFromRecordId (Record function)|NewFromRecordId]] function though there is really no good reason to create another <var>Record</var> object this way, or it could be passed to the <var class="product">Imagine</var> broker, probably after converting it to hex. Note, however, that while recordIds uniquely identify any record in <var class="product">Imagine</var>, <var class="product">Imagine</var> still needs to know the <var class="product">Imagine</var> file that holds the record to locate it. This can be obtained using the [[ImagineFile (Record function)|ImagineFile]] method.


==Examples==
==See also==
{{Template:Record:RecordId footer}}

ImagineFile (Record function)

2025-03-28T21:27:57Z

Alex:

{{Template:Record:ImagineFile subtitle}}

Get the name of the <var class="product">Imagine</var> file that contains the <var class="product">Imagine Transparency</var> record for the <var>Record</var> object.
==Syntax==
{{Template:Record:ImagineFile syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%string</th><td>The name of the containing <var class="product">Imagine</var> file, if the record is in an <var class="product">Imagine Transparency</var> file, or an empty string, otherwise.</td></tr>
<tr><th>record</th>
<td><var>Record</var> object</td></tr>
</table>
==Usage notes==
The <var class="product">Imagine</var> filename can be used with a recordId obtained via the [[RecordId (Record function)|RecordId method]] to allow an <var class="product">Imagine</var> application to easily locate a record.

==See also==
{{Template:Record:ImagineFile footer}}

BrokerLost class

2025-03-25T16:02:35Z

Alex: /* New constructor */

__NOTOC__
The <var>BrokerLost</var> exception class indicates that the connection with the <var class="product">Imagine Transparency</var> broker for the session was lost, either because of a network issue or an error in the <var class="product">Imagine</var> application.
The <var>[[Call (Imagine function)|Call]]</var> function of the <var>[[Imagine_class|Imagine]]</var> system class is currently the only method that might throw a <var>BrokerLost</var> exception. For more information about catching a thrown exception, see [[Exceptions#Try and Catch|Try and Catch]]. A lost broker connection for <var class="product">Imagine Transparency</var> file operations results in a request cancellation as there's typically no method to throw the exception and, even if an exception were thrown in such a case, the error is so low-level and severe that any attempt to recover from it would be a bad idea.

==The BrokerLost methods==
{{Template:List of BrokerLost methods}}

The methods in the class are described in the subsections that follow. In addition:
<ul>
<li>[[Notation conventions for methods]] has information about the conventions followed. </li>
<li>[[BrokerLost methods syntax]] is a single page that contains the syntax diagrams of all the methods in the class.</li>
</ul>

==New constructor==
{{Template:BrokerLost:New subtitle}}

This <var>Constructor</var> generates an instance of a <var>[[BrokerLost_class|BrokerLost]]</var> exception.

===Syntax===
{{Template:BrokerLost:New syntax}}

====Syntax terms====
<table>
<tr><th>%brokerLost</th>
<td>A reference to an instance of a <var>BrokerLost</var> object.
</td></tr>

<tr><th><var>[%(BrokerLost):]</var></th>
<td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>.</td></tr>

[[Category:System exception classes]]

BrokerLost class

2025-03-25T16:01:37Z

Alex:

__NOTOC__
The <var>BrokerLost</var> exception class indicates that the connection with the <var class="product">Imagine Transparency</var> broker for the session was lost, either because of a network issue or an error in the <var class="product">Imagine</var> application.
The <var>[[Call (Imagine function)|Call]]</var> function of the <var>[[Imagine_class|Imagine]]</var> system class is currently the only method that might throw a <var>BrokerLost</var> exception. For more information about catching a thrown exception, see [[Exceptions#Try and Catch|Try and Catch]]. A lost broker connection for <var class="product">Imagine Transparency</var> file operations results in a request cancellation as there's typically no method to throw the exception and, even if an exception were thrown in such a case, the error is so low-level and severe that any attempt to recover from it would be a bad idea.

==The BrokerLost methods==
{{Template:List of BrokerLost methods}}

The methods in the class are described in the subsections that follow. In addition:
<ul>
<li>[[Notation conventions for methods]] has information about the conventions followed. </li>
<li>[[BrokerLost methods syntax]] is a single page that contains the syntax diagrams of all the methods in the class.</li>
</ul>

==New constructor==
{{Template:DaemonLost:New subtitle}}

This <var>Constructor</var> generates an instance of a <var>[[DaemonLost_class|DaemonLost]]</var> exception. As shown below, the optional argument of the <var>New</var> method is a setting of the <var>[[DaemonOutput_(DaemonLost_property)|DaemonOutput]]</var> property.

===Syntax===
{{Template:BrokerLost:New syntax}}

====Syntax terms====
<table>
<tr><th>%brokerLost</th>
<td>A reference to an instance of a <var>BrokerLost</var> object.
</td></tr>

<tr><th><var>[%(BrokerLost):]</var></th>
<td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>.</td></tr>

[[Category:System exception classes]]

BrokerLost class

2025-03-25T16:00:40Z

Alex:

__NOTOC__
The <var>BrokerLost</var> exception class indicates that the connection with the <var class="product">Imagine Transparency</var> broker for the session was lost, either because of a network issue or an error in the <var class="product">Imagine</var> application.
The <var>[[Call (Imagine function)|Call]]</var> function of the <var>[[Imagine_class|Imagine]]</var> system class is currently the only method that might throw a <var>BrokerLost</var> exception. For more information about catching a thrown exception, see [[Exceptions#Try and Catch|Try and Catch]]. A lost broker connection for <var class="product">Imagine Transparency</var> file operations results in a request cancellation as there's typically no method to throw the exception and, even if an exception were thrown in such a case, the error is so low-level and severe that any attempt to recover from it would be a bad idea.

==The BrokerLost methods==
{{Template:List of BrokerLost methods}}

The methods in the class are described in the subsections that follow. In addition:
<ul>
<li>[[Notation conventions for methods]] has information about the conventions followed. </li>
<li>[[BrokerLost methods syntax]] is a single page that contains the syntax diagrams of all the methods in the class.</li>
</ul>

==New constructor==
{{Template:DaemonLost:New subtitle}}

This <var>Constructor</var> generates an instance of a <var>[[DaemonLost_class|DaemonLost]]</var> exception. As shown below, the optional argument of the <var>New</var> method is a setting of the <var>[[DaemonOutput_(DaemonLost_property)|DaemonOutput]]</var> property.

===Syntax===
{{Template:BrokerLost:New syntax}}

====Syntax terms====
<table>
<tr><th>%brokerLost</th>
<td>A reference to an instance of a <var>BrokerLost</var> object.
</td></tr>

<tr><th><var>[%(BrokerLost):]</var></th>
<td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>.</td></tr>

Category:BrokerLost methods

2025-03-25T15:57:59Z

Alex: Created page with "This page displays links to the available BrokerLost class methods. See Notation conventions for methods for information about the conventions followed in the method descriptions. ==PDF of category pages== {{Template:PDF of category pages}}"

This page displays links to the available [[BrokerLost class]] methods.

See [[Notation conventions for methods]] for information about the conventions followed in the method descriptions.

==PDF of category pages==
{{Template:PDF of category pages}}

New (BrokerLost constructor)

2025-03-25T15:57:14Z

Alex: Redirected page to BrokerLost class#New constructor

#REDIRECT [[BrokerLost class#New constructor|New constructor]]

[[Category:BrokerLost methods|New constructor]]

BrokerLost class

2025-03-25T15:53:43Z

Alex: Created page with " __NOTOC__ The <var>BrokerLost</var> exception class indicates that the connection with the <var class="product">Imagine Transparency</var> broker for the session was lost, either because of a network issue or an error in the <var class="product">Imagine</var> application. The <var>Call</var> function of the <var>Imagine</var> system class is currently the only method that might throw a <var>BrokerLo..."

Category:Imagine methods

2025-03-25T15:44:01Z

Alex: Created page with "This page displays links to the available Imagine class methods. See Notation conventions for methods for information about the conventions followed in the method descriptions. ==PDF of category pages== {{Template:PDF of category pages}}"

This page displays links to the available [[Imagine class]] methods.

See [[Notation conventions for methods]] for information about the conventions followed in the method descriptions.

==PDF of category pages==
{{Template:PDF of category pages}}

Call (Imagine function)

2025-03-25T15:41:42Z

Alex: /* Syntax terms */

{{Template:Imagine:Call subtitle}}

This method calls code running in the <var class="product">Imagine Transparency</var> broker for the current transaction.

==Syntax==
{{Template:Imagine:Call syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%string</th><td>The value returned by the called <var class="product">Imagine</var> function. This could be anything though JSON would be the most convenient format for passing data from <var class="product">Imagine</var> to <var class="product">Model 204</var>.</td></tr>
<tr><th nowrap="true"><var>%(Imagine)</var></th>
<td>The class name in parentheses denotes a shared method. <var>Call</var> can also be invoked via a <var>Imagine</var> object variable, which may be <var>Null</var>.</td></tr>
<tr><th>name</th>
<td>A string that contains the name of the function to be called in the <var class="product">Imagine</var> broker. The semantics of this value is under the control of the <var class="product">Imagine</var> broker.</td></tr>
<tr><th><var>payload</var></th>
<td>A string that contains data passed to the <var class="product">Imagine</var> function. This could be anything though JSON would be the most convenient format for passing data to the <var class="product">Imagine</var> function. Thwe default value for this is an empty string.</td></tr>
<tr><th><var>globals</var></th>
<td>A <var>Boolean</var> value that indicates whether global strings (<code>$setg</code>/<code>$getg</code>) should be sent to <var class="product">Imagine</var>. The default value of this argument is <var>false</var>.</td></tr>
<tr><th><var>globalImages</var></th>
<td>A <var>Boolean</var> value that indicates whether global images should be sent to <var class="product">Imagine</var>. The default value of this argument is <var>false</var>.</td></tr>
<tr><th><var>recordMap</var></th>
<td>A <var>Boolean</var> value that indicates whether a map of (thread-specific) <var class="product">Model 204</var> record numbers to <var class="product">Imagine</var> file and recordId should be sent to <var class="product">Imagine</var>. This can be useful if one is passing <var class="product">Model 204</var> record numbers to the <var class="product">Imagine</var> application. The default value of this argument is <var>false</var>.</td></tr>
</table>

==Usage notes==
In <var class="product">Imagine</var>, a transaction includes both retrieval requests and updating requests.

Because <var class="product">Imagine Transparency</var> files and transactions are automatically kept in synch with the corresponding files in <var class="product">Model 204</var> any updates in the <var class="product">Model 204</var> transaction are visible in the <var class="product">Imagine</var> transaction and vice versa==Examples==
==See also==
{{Template:Imagine:Call footer}}

Call (Imagine function)

2025-03-25T14:54:15Z

Alex:

{{Template:Imagine:Call subtitle}}

This method calls code running in the <var class="product">Imagine Transparency</var> broker for the current transaction.

==Syntax==
{{Template:Imagine:Call syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%string</th><td>The value returned by the called <var class="product">Imagine</var> function. This could be anything though JSON would be the most convenient format for passing data from <var class="product">Imagine</var> to <var class="product">Model 204</var>.</td></tr>
<tr><th nowrap="true"><var>%(Imagine)</var></th>
<td>The class name in parentheses denotes a shared method. <var>Call</var> can also be invoked via a <var>Imagine</var> object variable, which may be <var>Null</var>.</td></tr>
<tr><th>name</th>
<td>A string that contains the name of the function to be called in the <var class="product">Imagine</var> broker. The semantics of this value is under the control of the <var class="product">Imagine</var> broker.</td></tr>
<tr><th><var>payload</var></th>
<td>A string that contains data passed to the <var class="product">Imagine</var> function. This could be anything though JSON would be the most convenient format for passing data to the <var class="product">Imagine</var> function. Thwe default value for this is an empty string.</td></tr>
<tr><th><var>globals</var></th>
<td>A <var>Boolean</var> value that indicates whether global strings (<code>$setg</code>/<code>$getg</code>) should be sent to <var class="product">Imagine</var>. The default value of this argument is <var>false</var>.</td></tr>
<tr><th><var>globalImages</var></th>
<td>A <var>Boolean</var> value that indicates whether global images should be sent to <var class="product">Imagine</var>. The default value of this argument is <var>false</var>.</td></tr>
<tr><th><var>recordMap</var></th>
<td><var>Boolean</var> value The default value of this argument is [[??]].</td></tr>
</table>
==Usage notes==
In <var class="product">Imagine</var>, a transaction includes both retrieval requests and updating requests.

Because <var class="product">Imagine Transparency</var> files and transactions are automatically kept in synch with the corresponding files in <var class="product">Model 204</var> any updates in the <var class="product">Model 204</var> transaction are visible in the <var class="product">Imagine</var> transaction and vice versa==Examples==
==See also==
{{Template:Imagine:Call footer}}

Imagine class

2025-03-25T11:07:43Z

Alex: Created page with " The <var>Imagine</var> class can be used to interact with the <var class="product">Imagine Transparency</var> broker for the current transaction. Note that in <var class="product">Imagine</var>, a transaction includes both retrieval requests and updating requests. <var class="product">Imagine</var> is a non-relational, [https://en.wikipedia.org/wiki/ACID ACID] database and application server that is capable of mapping <var class="product">Model 204</var> data relativ..."

The <var>Imagine</var> class can be used to interact with the <var class="product">Imagine Transparency</var> broker for the current transaction. Note that in <var class="product">Imagine</var>, a transaction includes both retrieval requests and updating requests. <var class="product">Imagine</var> is a non-relational, [https://en.wikipedia.org/wiki/ACID ACID] database and application server that is capable of mapping <var class="product">Model 204</var> data relatively easily.


Currently, there is no <var>Imagine</var> object per se – the <var>Imagine</var> class is just a collection of shared methods. Because <var class="product">Imagine Transparency</var> files and transactions are automatically kept in synch with the corresponding files in <var class="product">Model 204</var> any updates in the <var class="product">Model 204</var> transaction are visible in the <var class="product">Imagine</var> transaction and vice versa

==List of Imagine methods==
The [[List of Imagine methods|"List of Imagine methods"]] shows all the class methods.

[[Category:System classes]]

Template:List of classes and methods

2025-03-25T02:49:25Z

Alex:

==System classes==
<table>
<tr><td style="border-right:0">CharacterMap class:</td><td style="border-left:0">[[CharacterMap class|Synopsis]] | [[List of CharacterMap methods|Methods]]</td></tr>

<tr><td style="border-right:0">CharacterToUnicodeMap class:</td><td style="border-left:0">[[CharacterToUnicodeMap class|Synopsis]] | [[List of CharacterToUnicodeMap methods|Methods]]</td></tr>

<tr><td style="border-right:0">[[Collections|Collection]] classes <ul class="nobul"><li>Arraylist class:<li>FloatNamedArraylist class:<li>NamedArraylist class:<li>UnicodeNamedArraylist class:</ul> </td>

<td style="border-left:0"> <ul class="nobulnoindent"><li>[[Arraylist class|Synopsis]] | [[List of Arraylist methods|Methods]]<li>[[FloatNamedArraylist class|Synopsis]] | [[List of FloatNamedArraylist methods|Methods]]<li>[[NamedArraylist class|Synopsis]] | [[List of NamedArraylist methods|Methods]]<li>[[UnicodeNamedArraylist class|Synopsis]] | [[List of UnicodeNamedArraylist methods|Methods]]</ul></td></tr>

<tr><td style="border-right:0">Daemon class:</td><td style="border-left:0">[[Daemon class|Synopsis]] | [[List of Daemon methods|Methods]]</td></tr>

<tr><td style="border-right:0">Dataset class:</td><td style="border-left:0">[[Dataset class|Synopsis]] | [[List of Dataset methods|Methods]]</td></tr>

<tr><td style="border-right:0">Email class:</td><td style="border-left:0">[[Email class|Synopsis]] | [[List of Email methods|Methods]]</td></tr>

<tr><td style="border-right:0">FastUnloadTask class:</td><td style="border-left:0">[[FastUnloadTask class|Synopsis]] | [[List of FastUnloadTask methods|Methods]]</td></tr>

<tr><td style="border-right:0">[[File classes]] <ul class="nobul"><li>Recordset class:<li>Record class:<li>SortedRecordset class:<li>RecordsetCursor class:</ul></td>
<td style="border-left:0"> <ul class="nobulnoindent"><li>[[Recordset class|Synopsis]] | [[List of Recordset methods|Methods]]<li>[[Record class|Synopsis]] | [[List of Record methods|Methods]]<li>[[SortedRecordset class|Synopsis]] | [[List of SortedRecordset methods|Methods]]<li>[[RecordsetCursor class|Synopsis]] | [[List of RecordsetCursor methods|Methods]]</ul></td></tr>

<tr><td style="border-right:0">[[HTTP Helper|HTTP Helper]] classes: <ul class="nobul"><li>HttpRequest class:<li>HttpResponse class:</ul></td>
<td style="border-left:0">[[List of HTTP Helper methods|HTTP Helper methods]]<ul class="nobulnoindent"><li>[[HttpRequest class|Synopsis]] | [[List of HttpRequest methods|Methods]]<li>[[HttpResponse class|Synopsis]] | [[List of HttpResponse methods|Methods]]</ul></td></tr>

<tr><td style="border-right:0">Imagine class:</td><td style="border-left:0">[[Imagine class|Synopsis]] | [[List of Imagine methods|Methods]]</td></tr>

<tr><td style="border-right:0">[[Intrinsic classes|Intrinsic]] classes: <ul class="nobul"><li>Float class:<li>String class:<li>Unicode class:</ul></td>
<td style="border-left:0"> <ul class="nobulnoindent"><li>[[List of Float methods|Methods]]<li>[[List of String methods|Methods]]<li>[[List of Unicode methods|Methods]]</ul></td></tr>

<tr><td style="border-right:0">Journal class:</td><td style="border-left:0">[[Journal class|Synopsis]] | [[List of Journal methods|Methods]]</td></tr>

<tr><td style="border-right:0">Json class:</td><td style="border-left:0">[[Json class|Synopsis]] | [[List of Json methods|Methods]]</td></tr>

<tr><td style="border-right:0">LDAP class:</td><td style="border-left:0">[[LDAP class|Synopsis]] | [[List of LDAP methods|Methods]]</td></tr>

<tr><td style="border-right:0">Object class:</td><td style="border-left:0">[[Object class|Synopsis]] | [[List of Object methods|Methods]]</td></tr>

<tr><td style="border-right:0">PersistentObjectInfo class:</td><td style="border-left:0">[[PersistentObjectInfo class|Synopsis]] | [[List of PersistentObjectInfo methods|Methods]]</td></tr>

<tr><td style="border-right:0">ProcedureInfo class:</td><td style="border-left:0">[[ProcedureInfo class|Synopsis]] | [[List of ProcedureInfo methods|Methods]]</td></tr>

<tr><td style="border-right:0">RandomNumberGenerator class:</td><td style="border-left:0">[[RandomNumberGenerator class|Synopsis]] | [[List of RandomNumberGenerator methods|Methods]]</td></tr>

<tr><td style="border-right:0">Regex class:</td><td style="border-left:0">[[Regex class|Synopsis]] | [[List of Regex methods|Methods]]</td></tr>

<tr><td style="border-right:0">Screen and ScreenField classes:</td>
<td style="border-left:0">[[Screen classes|Synopsis]] | [[List of Screen API methods|Methods]]</td></tr>

<tr><td style="border-right:0">SelectionCriterion class:</td><td style="border-left:0">[[SelectionCriterion class|Synopsis]] | [[List of SelectionCriterion methods|Methods]]</td></tr>

<tr><td style="border-right:0">Socket class:</td><td style="border-left:0">[[Socket class|Synopsis]] | [[List of Socket methods|Methods]]</td></tr>

<tr><td style="border-right:0">SortOrder class:</td><td style="border-left:0">[[SortOrder class|Synopsis]] | [[List of SortOrder methods|Methods]]</td></tr>

<tr><td style="border-right:0">Stringlist class:</td><td style="border-left:0">[[Stringlist class|Synopsis]] | [[List of Stringlist methods|Methods]]</td></tr>

<tr><td style="border-right:0">StringTokenizer class:</td><td style="border-left:0">[[StringTokenizer class|Synopsis]] | [[List of StringTokenizer methods|Methods]]</td></tr>

<tr><td style="border-right:0"><ul class="nobulnoindent"><li>System class:<li>Subsystem class:</ul></td>
<td style="border-left:0"><ul class="nobulnoindent"><li>[[System and Subsystem classes|Synopsis]] | [[List of System methods|Methods]]<li>[[System and Subsystem classes|Synopsis]] | [[List of Subsystem methods|Methods]]</ul></td></tr>

<tr><td style="border-right:0">Transaction class:</td><td style="border-left:0">[[Transaction class|Synopsis]] | [[List of Transaction methods|Methods]]</td></tr>

<tr><td style="border-right:0">UdpSocket class:</td><td style="border-left:0">[[UdpSocket class|Synopsis]] | [[List of UdpSocket methods|Methods]]</td></tr>

<tr><td style="border-right:0">UserStatistics class:</td><td style="border-left:0">[[UserStatistics class|Synopsis]] | [[List of UserStatistics methods|Methods]]</td></tr>

<tr><td style="border-right:0">Web class:</td><td style="border-left:0">[[Web class|Synopsis]] | [[List of Web methods|Methods]]</td></tr>

<tr><td style="border-right:0">[[XmlDoc API]] classes <ul class="nobul"><li>XmlDoc class:<li>XmlNode class:<li>XmlNodelist class:</ul> </td>
<td style="border-left:0">[[List of XmlDoc API methods|XmlDoc API methods]]<ul class="nobulnoindent"><li>[[XmlDoc API#The XmlDoc class|Synopsis]] | [[List of XmlDoc methods|XmlDoc methods]]<li>[[XmlDoc API#The XmlNode and XmlNodelist classes, and XPath|Synopsis]] | [[List of XmlNode methods|XmlNode methods]]<li>[[XmlDoc API#The XmlNode and XmlNodelist classes, and XPath|Synopsis]] | [[List of XmlNodelist methods|XmlNodelist methods]]</ul></td></tr>

<tr>
<td style="border-right:0">[[XmlParser API]] classes <ul class="nobul"><li>XmlParser class:<li>XmlSelector class:<li>XmlAttributeList class:</ul> </td>
<td style="border-left:0">[[List of XmlParser API methods|XmlParser API methods]]<ul class="nobulnoindent"><li>[[XmlParser class|Synopsis]] | [[List of XmlParser methods|XmlParser methods]]<li>[[XmlSelector class|Synopsis]] | [[List of XmlSelector methods|XmlSelector methods]]<li>[[XmlAttributeList class|Synopsis]] | [[List of XmlAttributeList methods|XmlAttributeList methods]]</ul></td></tr>
</table>

==System enumerations==
<table>
<tr><td colspan="2">[[Enumerations]]
<table class="noBorder"><tr><td style="border-right:0"><ul class="nobulnoindent">
<li>  [[ActionKey enumeration|ActionKey]]</li>
<li>  [[AddToRecordErrorReason enumeration|AddToRecordErrorReason]] </li>
<li>  [[Boolean enumeration|Boolean]]</li>
<li>  [[CoordinatorExceptionReason enumeration|CoordinatorExceptionReason]]</li>
<li>  [[CursorState enumeration|CursorState]]</li>
<li>  [[DaemonState enumeration|DaemonState]]</li>
<li>  [[DatasetState enumeration|DatasetState]]</li>
<li>  [[DigestAlgorithm enumeration|DigestAlgorithm]]</li>
<li>  [[FastUnloadTaskState enumeration|FastUnloadTaskState]]</li>
<li>  [[FieldColor enumeration|FieldColor]]</li>
<li>  [[Highlight enumeration|Highlight]]</li>
<li>  [[JsonType enumeration|JsonType]]</li>
<li>  [[LineEnd enumeration|LineEnd]]</li>
<li>  [[LockStrength enumeration|LockStrength]]</li>
</ul></td>
<td style="border-left:0"><ul class="nobul">
<li>   [[RecordFormat enumeration|RecordFormat]]</li>
<li>   [[RecordLockType enumeration|RecordLockType]]</li>
<li>   [[RegexSplitOutputOptions enumeration|RegexSplitOutputOptions]]</li>
<li>   [[TranslationExceptionReason enumeration|TranslationExceptionReason]]</li>
<li>   [[XmlAdjacentTextSetting enumeration|XmlAdjacentTextSetting]]</li>
<li>   [[XmlInvalidChar enumeration|XmlInvalidChar]]</li>
<li>   [[XmlNamespaceSetting enumeration|XmlNamespaceSetting]]</li>
<li>   [[XmlNodeType enumeration|XmlNodeType]]</li>
<li>   [[XmlParseErrorReason enumeration|XmlParseErrorReason]]</li>
<li>   [[XPathErrorReason enumeration|XPathErrorReason]]</li>
</ul></td></tr></table></td></tr>
</table>

==System exceptions==
{{Template:List of System exceptions}}

==System types==
<table>
<tr><td style="border-right:0"><div id="except"></div>System types<ul class="nobul">
<li>CertificateChecker</li>
<li>ProcedureInfoList</li>
<li>WebScreenCallback</li>
<li>XmlParser API types
<ul class="nobul">
<li>[[XmlParser API types|XmlStartHandler]]</li>
<li>[[XmlParser API types|XmlEndHandler]]</li>
<li>[[XmlParser API types|XmlPIHandler]]</li>
</ul></li>
</ul></td>
<td nowrap style="border-left:0"> <ul class="nobulnoindent">
<li>[[CertificateChecker type|Synopsis]]</li>
<li>[[ProcedureInfoList type|Synopsis]]</li>
<li>[[WebScreenCallback type|Synopsis]]</li>
<li>[[XmlParser API types|Synopsis]] </li>
</ul></td></tr>
</table>

$CurrecId

2025-03-25T02:43:10Z

Alex: Created page with " The <var>$CurrecId</var> function returns the <var class="product">Imagine Transparency</var> recordId for current (innermost) record <var>For</var> loop. If the current record is in a file that is not an <var class="product">Imagine Transparency</var> file, an empty string is returned. <var>$CurrecId</var> takes no arguments. ==Usage notes== The recordId for <var class="product">Imagine</var> associated records is an 8-byte binary string value. T..."

The <var>$CurrecId</var> function returns the <var class="product">Imagine Transparency</var> recordId for current (innermost) record <var>For</var> loop. If the current record is in a file that is not an <var class="product">Imagine Transparency</var> file, an empty string is returned.


<var>$CurrecId</var> takes no arguments.


==Usage notes==

The recordId for <var class="product">Imagine</var> associated records is an 8-byte binary string value. This can be used to create another <var>Record</var> object with the [[NewFromRecordId (Record function)|NewFromRecordId]] function though there is really no good reason to create another <var>Record</var> object this way, or it could be passed to the <var class="product">Imagine</var> broker, probably after converting it to hex. Note, however, that while recordIds uniquely identify any record in <var class="product">Imagine</var>, <var class="product">Imagine</var> still needs to know the <var class="product">Imagine</var> file that holds the record to locate it.


The [[CurrentRecordId (Record function)|CurrentRecordId]] method provides identical functionality using O-O syntax.

SOUL $functions

2025-03-25T02:36:44Z

Alex: /* List of standard $functions */

Some operations are inefficient or impossible to code in a high-level programming language like <var class="product">SOUL</var>. To overcome this difficulty, <var class="product">SOUL</var> provides a variety of $functions. Many of these functions are deprecated in favor of an OO API method. When that is the case, the $function page notes the matching method.

<div id="otherLists"></div>
The mathematical $functions, and those $functions central to a <var class="product">Model 204</var> product (and which require authorization of that product) are listed separately; you can find links to those sets of $functions in the following table:
<div class="showVisit">
<table class="wikitable">
<tr class="head"><th>$Function set</th><th>Description</th></tr>

<tr><td>[[List of mathematical $functions|$xxxmath]]</td><td>Mathematical $functions</td></tr>
<tr><td>[[SirFact $functions|$Fact_xxx]]</td><td>SirFact $functions</td></tr>
<tr><td>[[List of Janus FTP Server $functions|$Ftp_xxx]]</td><td>Janus FTP Server $functions</td></tr>
<tr><td>[[List of Janus Sockets $functions|$Sock_xxx]]</td><td>Janus Sockets $functions</td></tr>
<tr><td>[[List of Janus Web Server $functions|$Web_xxx]]</td><td>Janus Web Server $functions</td></tr>
<tr><td>[[List of Sir2000 User Language Tools $functions|Sir2000]]</td><td>Sir2000 User Language Tools $functions</td></tr>

</table>
</div>

==List of standard $functions==
The following table lists available <var class="product">SOUL</var> $functions, in alphabetical order. The list is not exhaustive (see the [[#otherLists|table of other $function sets]], above).

Note: Some of the $functions listed below are only available with the purchase of a Model 204 add-on product. The individual page containing such a $function's full description has an itemized list of the add-on products that authorize the use of the $function.

See also: 
<ul>
<li>[[#Using_functions|Using functions]], which reviews coding in <var class="product">SOUL</var> with $functions </li>

<li>[[Notation conventions]], which provides a description of the conventions used in syntax on individual $function pages. </li>
</ul>

<div class="showVisit">
<table class="wikitable">
<tr class="head"><th>$Function</th><th>Description</th></tr>



<tr><td>[[$Abbrev]]</td><td>Determine if string is abbreviation within list of words</td></tr>
<tr><td>[[$Account]]</td><td>Account under which the user is logged in.</td></tr>
<tr><td>[[$Acct]]</td><td>User ID under which the user is logged in.</td></tr>
<tr><td>[[$Alpha]]</td><td>Whether a string is composed of only the letters A through Z.</td></tr>
<tr><td>[[$AlphNum]]</td><td>Whether a string is composed of only the letters A through Z and digits 0 through 9.</td></tr>
<tr><td>[[$Arr_Find]]</td><td>Find value within array</td></tr>
<tr><td>[[$Arr_Init]]</td><td>Initialize every element of array to specific value</td></tr>
<tr><td>[[$Arr_Max]]</td><td>Find maximum value in array</td></tr>
<tr><td>[[$Arr_Min]]</td><td>Find minimum value in array</td></tr>
<tr><td>[[$ArrSize]]</td><td>Number of elements in a particular dimension of an array.</td></tr>
<tr><td>[[$Ascii]]</td><td>Input string, converted from EBCDIC to ASCII.</td></tr>
<tr><td>[[$A2E]]</td><td>Translate ASCII to EBCDIC</td></tr>
<tr><td>[[$Base64_Decode]]</td><td>Convert from base 64 to byte string</td></tr>
<tr><td>[[$Base64_Encode]]</td><td>Convert byte string to base 64</td></tr>
<tr><td>[[$BgPurge]]</td><td>Cancel "long" sdaemon request initiated with $CommBg</td></tr>
<tr><td>[[$BgQuery]]</td><td>List of "long" sdaemon requests initiated via $CommBg</td></tr>
<tr><td>[[$Binary]]</td><td>A number converted into fixed-point binary.</td></tr>
<tr><td>[[$Bind_List]]</td><td>Return list of bound semaphores onto a $list</td></tr>
<tr><td>[[$Bind]]</td><td>Fast, easy synchronization of system wide resource</td></tr>
<tr><td>[[$BitAnd]]</td><td>Bitwise AND of two integers</td></tr>
<tr><td>[[$BitOr]]</td><td>Bitwise OR of two integers</td></tr>
<tr><td>[[$BldProc]]</td><td>Enables a request to build a temporary procedure.</td></tr>
<tr><td>[[$Buffer_Position]]</td><td>Current Universal Buffer position.</td></tr>
<tr><td>[[$Buffer_Size]]</td><td>Size of user's Universal Buffer.</td></tr>
<tr><td>[[$Buffer_Used]]</td><td>Amount of data currently in Universal Buffer</td></tr>
<tr><td>[[$Bump]]</td><td>Bump a user</td></tr>
<tr><td>[[$CenqCt]]</td><td>Number of unused entries within the resource enqueuing table.</td></tr>
<tr><td>[[$Center]]</td><td>Center string</td></tr>
<tr><td>[[$CfStatL]]</td><td>List of statistics for users holding critical file resources</td></tr>
<tr><td>[[$ChkMod]]</td><td>Whether the terminal operator entered data in any full-screen input field.</td></tr>
<tr><td>[[$ChkPat]]</td><td>Syntax of a pattern.</td></tr>
<tr><td>[[$ChkpInf]]</td><td>Information about checkpoints</td></tr>
<tr><td>[[$ChkTag]]</td><td>Whether any erroneous full-screen input has been entered by the end user.</td></tr>
<tr><td>[[$Close]]</td><td>Close file or group in User Language request</td></tr>
<tr><td>[[$Cms]]</td><td>Determine if online is running under CMS</td></tr>
<tr><td>[[$Code]]</td><td>Encoding facility.</td></tr>
<tr><td>[[$Command]]</td><td>Execute Model 204 command on sdaemon, results to image</td></tr>
<tr><td>[[$CommBg]]</td><td>Execute Model 204 commands on sdaemon</td></tr>
<tr><td>[[$CommndL]]</td><td>Execute Model 204 command on sdaemon, results to $list</td></tr>
<tr><td>[[$Context]]</td><td>Determine if string is name of open file or group</td></tr>
<tr><td>[[$Curfile]]</td><td>Name of the file from which the current record has been selected.</td></tr>
<tr><td>[[$Currec]]</td><td>Integer equal to the internal number of the current record.</td></tr>
<tr><td>[[$CurrecId]]</td><td>Get the <var class="product">Imagine</var> recordId of the current record.</td></tr>
<tr><td>[[$C2D]]</td><td>Convert binary byte string to integer</td></tr>
<tr><td>[[$C2X]]</td><td>A translation of each byte within a character string to its two-byte hexadecimal representation.</td></tr>
<tr><td>[[$DaemonMasterNumber]]</td><td>Get user number of master thread</td></tr>
<tr><td>[[$DaemonParentNumber]]</td><td>Get user number of parent thread</td></tr>
<tr><td><div id="datex"></div>[[$Date]]</td><td>Current date in yy-mm-dd format.</td></tr>
<tr><td>[[$DateChg]]</td><td>Specified number of days, added to or subtracted from a given date.</td></tr>
<tr><td>[[$DateChk]]</td><td>Whether a given date is valid.</td></tr>
<tr><td>[[$DateCnv]]</td><td>Date converted to a format specified by the user.</td></tr>
<tr><td>[[$DateDif]]</td><td>Difference in days between two dates.</td></tr>
<tr><td>[[$DateJ]]</td><td>Current date in "yy.ddd" format.</td></tr>
<tr><td>[[$DateP]]</td><td>Current date in "dd mon yy" format.</td></tr>
<tr><td>[[$DAY]]</td><td>Day name of the input day-number.</td></tr>
<tr><td>[[$DayI]]</td><td>Number reflecting current day of the week.</td></tr>
<tr><td>[[$Deblank]]</td><td>Substring of a string, with leading and trailing blanks removed.</td></tr>
<tr><td>[[$Decode]]</td><td>Decoding facility.</td></tr>
<tr><td>[[$Deflate]]</td><td>Compress a longstring with Deflate</td></tr>
<tr><td>[[$DelCh]]</td><td>Remove characters from string, compress and strip blanks</td></tr>
<tr><td>[[$Delg_Subsys]]</td><td>Delete subsystem-wide global</td></tr>
<tr><td>[[$Delg_Sys]]</td><td>Delete system-wide global</td></tr>
<tr><td>[[$Delimr]]</td><td>Insert delimiter string into input string at regular positions</td></tr>
<tr><td>[[$Dscr]]</td><td>Decoding facility.</td></tr>
<tr><td>[[$Dsn]]</td><td>Data set name when you specify a file's DD name and the ordinal number.</td></tr>
<tr><td>[[$DsnNum]]</td><td>Total number of data sets defined for a file when you specify the file's DD name.</td></tr>
<tr><td>[[$D2C]]</td><td>Binary byte representation of integer</td></tr>
<tr><td>[[$D2X]]</td><td>Hex representation of integer</td></tr>
<tr><td>[[$Ebcdic]]</td><td>Convert input string from ASCII to EBCDIC</td></tr>
<tr><td>[[$EcbDGet]]</td><td>Get string data associated with an Event Control Block (ECB)</td></tr>
<tr><td>[[$EcbDSet]]</td><td>Set string data associated with an Event Control Block (ECB)</td></tr>
<tr><td>[[$EcbTest]]</td><td>Check an Event Control Block (ECB) to see if it is posted</td></tr>
<tr><td>[[$EcfStat]]</td><td>Returns the detailed completion code from the previous EXTERNAL statement.</td></tr>
<tr><td>[[$Edit]]</td><td>Edited numeric and alphanumeric text</td></tr>
<tr><td>[[$EdScan]]</td><td>Scan list of entities in online</td></tr>
<tr><td>[[$Eformat]]</td><td>Exponent notations from converted numeric values</td></tr>
<tr><td>[[$Encrypt]]</td><td>A one-way encryption of a character string.</td></tr>
<tr><td>[[$Ent_Print]]</td><td>Set automatic character entity substitution</td></tr>
<tr><td>[[$Ent_Tab]]</td><td>retrieve/modify character entity substitution table</td></tr>
<tr><td>[[$Ent]]</td><td>Do character entity substitution</td></tr>
<tr><td>[[$Enter]]</td><td>Efficient terminal dialogue with users of data entry applications.</td></tr>
<tr><td>[[$ErrClr]]</td><td>Clears the error message text returned by the $ErrMsg and $Fsterr functions.</td></tr>
<tr><td>[[$ErrMsg]]</td><td>Prefix and text of the last counting error or request cancellation message received.</td></tr>
<tr><td>[[$ErrSet]]</td><td>Increment or clear number of counting errors, set $ErrMsg</td></tr>
<tr><td>[[$E2A]]</td><td>Translate EBCDIC to ASCII</td></tr>
<tr><td>[[$FakeEnt]]</td><td>Prepare fake ENTER to automatically satisfy next full screen read</td></tr>
<tr><td>[[$FDef]]</td><td>String that describes the attributes of a field in a <var class="product">Model 204</var> file.</td></tr>
<tr><td>[[$Field_Image]]</td><td>Return field values into an image</td></tr>
<tr><td>[[$Field_List]]</td><td>Return field values into a $list</td></tr>
<tr><td>[[$Field_ListI]]</td><td>Return field values into a $list mapped to an image</td></tr>
<tr><td>[[$FieldgroupId]]</td><td>The ID of the current field group. (Available as of Model 204 version 7.5.)</td></tr>
<tr><td>[[$FieldgroupOccurrence]]</td><td>The current occurrence number of the field group. (Available as of Model 204 version 7.5.)</td></tr>
<tr><td>[[$FIniTim]]</td><td>File initialization YYDDDMMHHSSTH</td></tr>
<tr><td>[[$FiStat]]</td><td>Retrieve file's statistics into string</td></tr>
<tr><td>[[$FiStatL]]</td><td>Retrieve set of files' statistics into list</td></tr>
<tr><td>[[$FldLen]]</td><td>Length of a field.</td></tr>
<tr><td>[[$Float]]</td><td>Floating-point to a 4-byte string without conversion (4-byte floating point number to a 4-byte string).</td></tr>
<tr><td>[[$FloatD]]</td><td>Floating-point to a 4-byte string without conversion (8-byte floating point number to an 8-byte string). </td></tr>
<tr><td>[[$FlsAcc]]</td><td>User's access rights to a particular field.</td></tr>
<tr><td>[[$FlsChk]]</td><td>Whether a given set of field level security accesses is valid for a field.</td></tr>
<tr><td>[[$FreeOpt]]</td><td>Free optional file or group from subsystem</td></tr>
<tr><td>[[$Fsterr]]</td><td>Variable-length string containing the prefix and the first counting error message or request cancellation message received by the user since the last time the count was reset to zero.</td></tr>
<tr><td>[[$FunForc]]</td><td>Cancel running or waiting Fast/Unload request</td></tr>
<tr><td>[[$FunImg]]</td><td>Retrieve data from active Fast/Unload request into image</td></tr>
<tr><td>[[$FunList]]</td><td>$list of active and enqueued Fast/Unload requests</td></tr>
<tr><td>[[$FunLoad]]</td><td>Fast/Unload records in Model 204 list or found set</td></tr>
<tr><td>[[$FunPurg]]</td><td>Purge running or waiting Fast/Unload request</td></tr>
<tr><td>[[$FunSkip]]</td><td>Skip to next output record for $FunImg, $FunsStr</td></tr>
<tr><td>[[$FunsStr]]</td><td>Retrieve data from active Fast/Unload request into string</td></tr>
<tr><td>[[$FunWait]]</td><td>Wait until asynchronous Fast/Unload request completes</td></tr>
<tr><td>[[$Getg]]</td><td>Information stored by a $SETG function.</td></tr>
<tr><td>[[$GetL]]</td><td>Line number of the current line on the page on the user's terminal or on the output data set specified by a USE command.</td></tr>
<tr><td>[[$GetP]]</td><td>Page number currently on the user's terminal or on the output data set specified by a USE command.</td></tr>
<tr><td>[[$GrmLoc]]</td><td>Location of a missing member.</td></tr>
<tr><td>[[$GrmName]]</td><td>File name of a missing member.</td></tr>
<tr><td>[[$GrnLeft]]</td><td>Number of optional files that may fail before MAXFAIL is exceeded.</td></tr>
<tr><td>[[$GrnMiss]]</td><td>Number of missing members.</td></tr>
<tr><td>[[$GunZip]]</td><td>Decompress a longstring with GUNZIP</td></tr>
<tr><td>[[$GZip]]</td><td>Compress a longstring with GZip</td></tr>
<tr><td>[[$HexA]]</td><td>Convert hexadecimal string to EBCDIC equivalent</td></tr>
<tr><td>[[$HPage]]</td><td>String of special characters whose length is equal to the value specified as the $HPage argument.</td></tr>
<tr><td>[[$Hsh]]</td><td>A hash value from a converted string value. A hash value is a distinct numeric representation of a given string value.</td></tr>
<tr><td>[[$IHexA]]</td><td>Convert EBCDIC string to hexadecimal equivalent</td></tr>
<tr><td>[[$ImgInf]]</td><td>Retrieve image item by variable name</td></tr>
<tr><td>[[$ImgOvl]]</td><td>Replace image item value</td></tr>
<tr><td>[[$Incrg]]</td><td>Performs simple arithmetic on global variables.</td></tr>
<tr><td>[[$IncStat]]</td><td>Increment local system statistic</td></tr>
<tr><td>[[$Index]]</td><td>After comparing two strings, a number equal to the first position within the first string at which the second string appears; the same function as $SCAN.</td></tr>
<tr><td>[[$Inflate]]</td><td>Decompress a longstring with inflate</td></tr>
<tr><td>[[$ItsOpen]]</td><td>Whether or not a file is open.</td></tr>
<tr><td>[[$ItsRemote]]</td><td>Whether the current file or group is remote or scattered.</td></tr>
<tr><td>[[$JobAuth]]</td><td>Determine if user has authorization for USE $JOB</td></tr>
<tr><td>[[$Jobcode]]</td><td>Allows a request that is part of one step of a <var class="product">Model 204</var> batch run to communicate with a subsequent step.</td></tr>
<tr><td>[[$JpStat]]</td><td>Retrieve Janus port's statistics into string</td></tr>
<tr><td>[[$JpStatL]]</td><td>Retrieve statistics for set of Janus pors into $list</td></tr>
<tr><td>[[$LangSpc]]</td><td>String containing the binary value of a character in a specified language.</td></tr>
<tr><td>[[$LangSrt]]</td><td>A binary string translated to sort according to the NLSORT macro for the specified language.</td></tr>
<tr><td>[[$LangUst]]</td><td>Previously $LangSrt'ed string translated back to its original form.</td></tr>
<tr><td>[[$Len]]</td><td>Length of a value in a field.</td></tr>
<tr><td>[[$List_Add_Ordered]]</td><td>Add an item to an ordered $list</td></tr>
<tr><td>[[$List_Add_Unique_Ordered]]</td><td>Conditionally add an item to an ordered $list</td></tr>
<tr><td>[[$List_Add_Unique]]</td><td>Conditionally add an item to a $list</td></tr>
<tr><td>[[$List_Capture]]</td><td>Capture print data to $list</td></tr>
<tr><td>[[$List_Conv_Item]]</td><td>Convert $list to single delimited $list item</td></tr>
<tr><td>[[$List_Copy_Items]]</td><td>Copy items between $lists</td></tr>
<tr><td>[[$List_Diff_Item]]</td><td>Differences between $list and delimited $list item</td></tr>
<tr><td>[[$List_Global and $List_Session]]</td><td>Access/create global/session $list</td></tr>
<tr><td>[[$List_Global_Del and $List_Session_Del]]</td><td>Delete global/session $lists</td></tr>
<tr><td>[[$List_Global_List and $List_Session_List]]</td><td>List global/session $lists</td></tr>
<tr><td>[[$List_MaxIL]]</td><td>Return maximum $list item length</td></tr>
<tr><td>[[$List_Print]]</td><td>Display contents of a $list</td></tr>
<tr><td>[[$ListAdd_Lstr]]</td><td>Add longstring as new $list item</td></tr>
<tr><td>[[$ListAdd]]</td><td>Add string as new $list item</td></tr>
<tr><td>[[$ListAddI]]</td><td>Add image as new $list item</td></tr>
<tr><td>[[$ListAdj]]</td><td>Adjust length of $list item</td></tr>
<tr><td>[[$ListChk]]</td><td>Validate a $list identifier</td></tr>
<tr><td>[[$ListCmp]]</td><td>Compare two $lists and produce $list describing differences</td></tr>
<tr><td>[[$ListCnt]]</td><td>Number of items in $list</td></tr>
<tr><td>[[$ListCpy]]</td><td>Copy $list</td></tr>
<tr><td>[[$ListDel]]</td><td>Release CCATEMP storage used for $list</td></tr>
<tr><td>[[$ListFind]]</td><td>Find string in $list</td></tr>
<tr><td>[[$ListFindI and $ListFindI_Up]]</td><td>Find image item in $list</td></tr>
<tr><td>[[$ListFindI_Sub]]</td><td>Build $list subset based on image item</td></tr>
<tr><td>[[$ListILn]]</td><td>Length of $list item</td></tr>
<tr><td>[[$Listimg_Copy]]</td><td>Copy a $list's image association</td></tr>
<tr><td>[[$ListImg]]</td><td>Associate an image with a $list</td></tr>
<tr><td>[[$ListInf_Lstr]]</td><td>Retrieve $list item into longstring</td></tr>
<tr><td>[[$ListInf]]</td><td>Retrieve $list item into string</td></tr>
<tr><td>[[$ListInfI]]</td><td>Retrieve $list item into image</td></tr>
<tr><td>[[$ListIns_Lstr]]</td><td>Insert string into a $list</td></tr>
<tr><td>[[$ListIns]]</td><td>Insert string into a $list</td></tr>
<tr><td>[[$ListInsI]]</td><td>Insert image into a $list</td></tr>
<tr><td>[[$ListLoc]]</td><td>Locate string in $list</td></tr>
<tr><td>[[$ListLup]]</td><td>Locate string in $list, searching backwards</td></tr>
<tr><td>[[$ListMove]]</td><td>Move a $list</td></tr>
<tr><td>[[$ListNew]]</td><td>Create empty $list</td></tr>
<tr><td>[[$ListNewA]]</td><td>Create array of empty $lists</td></tr>
<tr><td>[[$ListNewAI]]</td><td>Create array of empty $lists associated with image</td></tr>
<tr><td>[[$ListNewI]]</td><td>Create empty $list associated with image</td></tr>
<tr><td>[[$ListOvl]]</td><td>Overlay part of $list item with string</td></tr>
<tr><td>[[$ListOvlI]]</td><td>Overlay part of $list item with image item</td></tr>
<tr><td>[[$ListRem]]</td><td>Remove item from $list</td></tr>
<tr><td>[[$ListRep_Lstr]]</td><td>Replace a $list item with a longstring</td></tr>
<tr><td>[[$ListRep]]</td><td>Replace a $list item with a string</td></tr>
<tr><td>[[$ListRepI]]</td><td>Replace $list item with an image</td></tr>
<tr><td>[[$ListRst]]</td><td>Restore global $list</td></tr>
<tr><td>[[$ListSav and $ListSave]]</td><td>Save global $list</td></tr>
<tr><td>[[$ListSavL]]</td><td>Count and names of available global $lists</td></tr>
<tr><td>[[$ListSort and $ListSrt]]</td><td>Sort $list</td></tr>
<tr><td>[[$ListSub]]</td><td>Create $list that is subset of input $list</td></tr>
<tr><td>[[$ListUpd]]</td><td>Produce $list from input $list using $list of updates</td></tr>
<tr><td>[[$Lowcase]]</td><td>A lower case string translated from an uppercase or mixed case string</td></tr>
<tr><td>[[$LstFld]]</td><td>Field names in a file, along with their field descriptions, into an image.</td></tr>
<tr><td>[[$LstProc]]</td><td>Information that is stored for a procedure.</td></tr>
<tr><td>[[$Lstr_Add_UserBuffer]]</td><td>Add longstring to user buffer</td></tr>
<tr><td>[[$Lstr_Base64_Decode]]</td><td>Convert from base 64 to byte string</td></tr>
<tr><td>[[$Lstr_Base64_Encode]]</td><td>Convert byte string to base 64</td></tr>
<tr><td>[[$Lstr_C2X]]</td><td>Convert byte string to hexadecimal</td></tr>
<tr><td>[[$Lstr_Get_Image and $Lstr_Set_Image]]</td><td>Longstring to/from image</td></tr>
<tr><td>[[$Lstr_Get_Userbuffer]]</td><td>Get user buffer contents to a longstring</td></tr>
<tr><td>[[$Lstr_Global and $Lstr_Session]]</td><td>Bind to global/session longstring</td></tr>
<tr><td>[[$Lstr_Global_Del and $Lstr_Session_Del]]</td><td>Delete global or session longstring</td></tr>
<tr><td>[[$Lstr_Global_Get and $Lstr_Session_Get]]</td><td>Get global or session longstring</td></tr>
<tr><td>[[$Lstr_Global_Set and $Lstr_Session_Set]]</td><td>Set global or session longstring</td></tr>
<tr><td>[[$Lstr_Index]]</td><td>Find a string inside a longstring</td></tr>
<tr><td>[[$Lstr_Left]]</td><td>Leftmost characters of a longstring</td></tr>
<tr><td>[[$Lstr_Len]]</td><td>Length of a longstring</td></tr>
<tr><td>[[$Lstr_Parse]]</td><td>Part of longstring preceding character in delimiter set</td></tr>
<tr><td>[[$Lstr_ParseX]]</td><td>Part of longstring following character in delimiter set</td></tr>
<tr><td>[[$Lstr_Right]]</td><td>Rightmost characters of a longstring</td></tr>
<tr><td>[[$Lstr_Set_UserBuffer]]</td><td>Set user buffer to longstring value</td></tr>
<tr><td>[[$Lstr_Substr]]</td><td>Substring of a longstring</td></tr>
<tr><td>[[$Lstr_SubWord]]</td><td>Substring of a longstring using word counts</td></tr>
<tr><td>[[$Lstr_Translate]]</td><td>Translate longstring</td></tr>
<tr><td>[[$Lstr_Unblank]]</td><td>Remove extraneous blanks from longstring</td></tr>
<tr><td>[[$Lstr_Windex]]</td><td>Return the position of a word within a long string</td></tr>
<tr><td>[[$Lstr_Word]]</td><td>Return a word from a long string</td></tr>
<tr><td>[[$Lstr_Words]]</td><td>Return the number of words in a long string</td></tr>
<tr><td>[[$Lstr_X2C]]</td><td>Convert from hexadecimal to byte string</td></tr>
<tr><td>[[$Lstr]]</td><td>Treat a string as longstring</td></tr>
<tr><td>[[$MisGrup]]</td><td>Group name if the error occurred in group context, null if in file context.</td></tr>
<tr><td>[[$MisLoc]]</td><td>Location of a missing member or file.</td></tr>
<tr><td>[[$MisName]]</td><td>File name of a missing member or file.</td></tr>
<tr><td>[[$MisNum]]</td><td>Number of files that failed in a group.</td></tr>
<tr><td>[[$MisStmt]]</td><td>Statement that caused the ON unit to be entered.</td></tr>
<tr><td>[[$Mod]]</td><td>Remainder that results when one argument is divided by the another argument.</td></tr>
<tr><td>[[$Occurs]]</td><td>Whether a field has the OCCURS attribute.</td></tr>
<tr><td>[[$Oneof]]</td><td>Table lookup that can replace a series of IF conditions.</td></tr>
<tr><td>[[$Pack]]</td><td>Packed decimal representation of a string.</td></tr>
<tr><td>[[$Pad]]</td><td>Designated character padded to the left.</td></tr>
<tr><td>[[$PadR]]</td><td>Designated character padded to the right</td></tr>
<tr><td>[[$Parse]]</td><td>Part of string preceding character in delimiter set</td></tr>
<tr><td>[[$ParseX]]</td><td>Part of string following character in delimiter set</td></tr>
<tr><td>[[$Post]]</td><td>Indicates that an event has occurred; the thread waiting on an ECB can resume processing.</td></tr>
<tr><td>[[$PrcLEx]]</td><td>$list of information about procedures in file</td></tr>
<tr><td>[[$PrcLExG]]</td><td>$list of information about procedures in group or file</td></tr>
<tr><td>[[$Priorty]]</td><td>Change a user's priority</td></tr>
<tr><td>[[$Proc_List]]</td><td>$list of information about procedures in file</td></tr>
<tr><td>[[$Proc_ListG]]</td><td>$list of information about procedures in group or file</td></tr>
<tr><td>[[$Proc_Touch]]</td><td>Change a procedure's last-update date and user</td></tr>
<tr><td>[[$ProcCls]]</td><td>Close procedure before reaching end</td></tr>
<tr><td>[[$ProcDat]]</td><td>Add lines from procedure to $list</td></tr>
<tr><td>[[$ProcGet]]</td><td>Next line of procedure</td></tr>
<tr><td>[[$ProcLoc]]</td><td>Locate any of set of strings in procedure</td></tr>
<tr><td>[[$ProcOpn]]</td><td>Open procedure for $ProcDat, $ProcGet, $ProcLoc</td></tr>
<tr><td>[[$Random_Seed]]</td><td>Build seed specifying series of $Random results</td></tr>
<tr><td>[[$Random]]</td><td>Get next random number</td></tr>
<tr><td>[[$RdProc]]</td><td>Lines of a User Language procedure, retrieved in sequential order, that is stored in a <var class="product">Model 204</var> file.</td></tr>
<tr><td>[[$Read]]</td><td>An echo of the data a user enters as a request is evaluated</td></tr>
<tr><td>[[$ReadInv]]</td><td>Performs the same function as $READ, except that input from the terminal is not echoed.</td></tr>
<tr><td>[[$ReadLc]]</td><td>An echo of the data a user enters as a request is evaluated, except that case translation is deactivated, regardless of the current *UPPER or *LOWER setting.</td></tr>
<tr><td>[[$RegexMatch]]</td><td>Whether string matches regex</td></tr>
<tr><td>[[$RegexReplace]]</td><td>Replace matching strings</td></tr>
<tr><td>[[$Remote]]</td><td>VTAMNAME value of the originating <var class="product">Model 204</var> region when using SNA Communications Server (formerly VTAM) TRANSFER to transfer between <var class="product">Model 204</var> regions.</td></tr>
<tr><td>[[$ResetN]]</td><td>Reset or view M204 parameter</td></tr>
<tr><td>[[$Reverse]]</td><td>Reversed order of a string.</td></tr>
<tr><td>[[$RlcFile]]</td><td>Name of the file in which the last record locking conflict occurred.</td></tr>
<tr><td>[[$RlcRec]]</td><td>Internal record number for which the last record locking conflict occurred.</td></tr>
<tr><td>[[$RlcUid]]</td><td>ID of the user who caused an ON FIND CONFICT or ON RECORD LOCKING CONFLICT. If the conflicting user is on a remote node, $RLCUID also returns the name of the node.</td></tr>
<tr><td>[[$RlcUsr]]</td><td>User number of the user with which the request conflicted when the last record locking conflict occurred.</td></tr>
<tr><td>[[$Round]]</td><td>Number, rounded to a specified number of decimal places.</td></tr>
<tr><td>[[$Scan]]</td><td>After comparing two strings, a number equal to the first position within the first string at which the second string appears; the same function as $INDEX.</td></tr>
<tr><td>[[$Sclass]]</td><td>Current user's subsystem user class.</td></tr>
<tr><td>[[$Screen_attr]]</td><td>Get screen item attributes as a blank-delimited string</td></tr>
<tr><td>[[$Screen_clear]]</td><td>Clear tagged and/or modified attributes in a screen</td></tr>
<tr><td>[[$Screen_mod]]</td><td>Set modified attribute for a screen item</td></tr>
<tr><td>[[$ScrHide]]</td><td>Hide lines in SCREEN</td></tr>
<tr><td>[[$ScrSize]]</td><td>Change size of field on SCREEN</td></tr>
<tr><td>[[$ScrWide]]</td><td>Allow SCREEN to accept fields wider than 79</td></tr>
<tr><td>[[$Session_$Session_Id_$Session_Owner_and_$Session_Timeout|$Session, $Session_Id, $Session_Owner,    and $Session_Timeout]]</td><td>Return values for currently open session</td></tr>
<tr><td>[[$Session_Close]]</td><td>Close an open session</td></tr>
<tr><td>[[$Session_Create]]</td><td>Create a new session</td></tr>
<tr><td>[[$Session_Delete]]</td><td>Delete a session</td></tr>
<tr><td>[[$Session_List]]</td><td>Get list of sessions</td></tr>
<tr><td>[[$Session_Open]]</td><td>Open a session</td></tr>
<tr><td>[[$Setg_Subsys_List]]</td><td>Get list of subsystem-wide globals</td></tr>
<tr><td>[[$Setg_Subsys]]</td><td>Set subsystem-wide global</td></tr>
<tr><td>[[$Setg_Sys_List]]</td><td>Get list of system-wide globals</td></tr>
<tr><td>[[$Setg_Sys]]</td><td>Set system-wide global</td></tr>
<tr><td>[[$Setg]]</td><td>A created or changed entry in the global variable section of GTBL.</td></tr>
<tr><td>[[$SetL]]</td><td>Sets the current line counter for the output device currently in effect.</td></tr>
<tr><td>[[$SetP]]</td><td>Sets the current page number for the output device currently in effect.</td></tr>
<tr><td>[[$SetStat]]</td><td>Set local system statistic</td></tr>
<tr><td><div id="datetime"></div>[[$Sir_Date]]</td><td>Get current datetime</td></tr>
<tr><td>[[$Sir_DateFmt]]</td><td>Validate datetime format</td></tr>
<tr><td><div id="daten"></div>[[$Sir_DateN]]</td><td>Current date and time as number of seconds/300</td></tr>
<tr><td>[[$Sir_DateND]]</td><td>Current date as number of days</td></tr>
<tr><td>[[$Sir_DateNM]]</td><td>Current date and time as number of milliseconds</td></tr>
<tr><td>[[$Sir_DateNS]]</td><td>Current date and time as number of seconds</td></tr>
<tr><td>[[$Sir_Date2N]]</td><td>Convert datetime string to number of seconds/300</td></tr>
<tr><td>[[$Sir_Date2ND]]</td><td>Convert datetime string to number of days</td></tr>
<tr><td>[[$Sir_Date2NM]]</td><td>Convert datetime string to number of milliseconds</td></tr>
<tr><td>[[$Sir_Date2NS]]</td><td>Convert datetime string to number of seconds</td></tr>
<tr><td>[[$Sir_Login]]</td><td>Perform secured web or sockets login</td></tr>
<tr><td>[[$Sir_ND2Date]]</td><td>Convert datetime number of days to string</td></tr>
<tr><td>[[$Sir_NM2Date]]</td><td>Convert datetime number of milliseconds to string</td></tr>
<tr><td>[[$Sir_NS2Date]]</td><td>Convert datetime number of seconds to string</td></tr>
<tr><td>[[$Sir_N2Date]]</td><td>Convert datetime number of seconds/300 to string</td></tr>
<tr><td>[[$Sir_Wild]]</td><td>Test string against a wildcard string</td></tr>
<tr><td>[[$SirJGet]]</td><td>Place audit trail data on $list</td></tr>
<tr><td>[[$SirMsg]]</td><td>Line of current $SirMsgP procedure</td></tr>
<tr><td>[[$SirMsgP]]</td><td>Load procedure for retrieval via $SirMsg</td></tr>
<tr><td>[[$SirParm]]</td><td>Set user-specific value, controlling Sirius products</td></tr>
<tr><td>[[$SirProd]]</td><td>Determine availability of Sirius product or capability</td></tr>
<tr><td>[[$SirSite]]</td><td>Current Sirius customer site ID</td></tr>
<tr><td>[[$SirTime]]</td><td>Current time as YYDDDHHMISSXX</td></tr>
<tr><td>[[$SirVer]]</td><td>Current version number of Sirius product</td></tr>
<tr><td>[[$SirWarn]]</td><td>Send warning or message to user(s)</td></tr>
<tr><td>[[$Slstats]]</td><td>Resets the recording of since-last statistics anywhere within a request.</td></tr>
<tr><td>[[$SndMail]]</td><td>Send an email message</td></tr>
<tr><td>[[$Sndx]]</td><td>SOUNDEX code of an argument.</td></tr>
<tr><td>[[$Square]]</td><td>A number multiplied by itself.</td></tr>
<tr><td>[[$SsStat]]</td><td>Retrieve subsystem's statistics into string</td></tr>
<tr><td>[[$SsStatL]]</td><td>Retrieve statistics for set of subsystems into $list</td></tr>
<tr><td>[[$Stat]]</td><td>Current value of any user statistic.</td></tr>
<tr><td>[[$StatD]]</td><td>Calculate differences and rates for statistics strings</td></tr>
<tr><td>[[$StatLD]]</td><td>Calculate differences and rates for statistics $lists</td></tr>
<tr><td>[[$Status]]</td><td>The success or failure of the last executed external I/O or program communication statement.</td></tr>
<tr><td>[[$StatusD]]</td><td>More detailed description of a condition returned by $STATUS.</td></tr>
<tr><td>[[$Str]]</td><td>Treat a longstring as string</td></tr>
<tr><td>[[$StrAnd]]</td><td>Bit-wise AND two strings</td></tr>
<tr><td>[[$Strip]]</td><td>A number with suppressed leading zeros.</td></tr>
<tr><td>[[$StrOr]]</td><td>Bit-wise OR two strings</td></tr>
<tr><td>[[$StrXor]]</td><td>Bit-wise exclusive OR two strings</td></tr>
<tr><td>[[$SubCnt]]</td><td>Count occurrences of one string in another</td></tr>
<tr><td>[[$SubErs]]</td><td>Remove occurrence of one string from another</td></tr>
<tr><td>[[$SubIns]]</td><td>Insert string inside another string</td></tr>
<tr><td>[[$SubRep]]</td><td>Replace occurrences of string</td></tr>
<tr><td>[[$Substr]]</td><td>Substring of a string.</td></tr>
<tr><td>[[$Subsys]]</td><td>Status of an APSY subsystem.</td></tr>
<tr><td>[[$SyStat]]</td><td>Retrieve system statistics into string</td></tr>
<tr><td>[[$TableC]]</td><td>Information provided by TABLEC command</td></tr>
<tr><td>[[$TermId]]</td><td>Terminal ID of current user thread</td></tr>
<tr><td>[[$Time]]</td><td>Current time in hh:mm:ss format.</td></tr>
<tr><td>[[$TkStat]]</td><td>Retrieve task's statistics into string</td></tr>
<tr><td>[[$TkStatL]]</td><td>Retrieve statistics for all tasks into $list</td></tr>
<tr><td>[[$TsoAtt]]</td><td>Attach program in user's TSO address space</td></tr>
<tr><td>[[$TsoCall]]</td><td>Call program in user's TSO address space</td></tr>
<tr><td>[[$TsoCan]]</td><td>Cancel program invoked via $TsoAtt</td></tr>
<tr><td>[[$TsoCmd]]</td><td>Invoke command in user's TSO address space</td></tr>
<tr><td>[[$TsoExec]]</td><td>Invoke CLIST in user's TSO address space</td></tr>
<tr><td>[[$TsoExit]]</td><td>Terminate TSO full screen interface session, stack command</td></tr>
<tr><td>[[$TSOId]]</td><td>TSO userid user's thread</td></tr>
<tr><td>[[$TSOStat]]</td><td>Status of program invoked via $TsoAtt</td></tr>
<tr><td>[[$TSOWait]]</td><td>Wait for program invoked via $TsoAtt to complete</td></tr>
<tr><td>[[$Unbin]]</td><td>Value converted from binary to string representation.</td></tr>
<tr><td>[[$Unbind_and_$UnbindW]]</td><td>$Unbind and $UnbindW: Unbind resource previously bound via $Bind</td></tr>
<tr><td>[[$Unblank]]</td><td>Contents of an argument, removing leading and trailing blanks, and compressing multiple embedded blanks to one blank character.</td></tr>
<tr><td>[[$Unfloat]]</td><td>Character string that represents a numeric counted string of 4 or 8 bytes, which contains a floating point.</td></tr>
<tr><td>[[$Unpack]]</td><td>Unpacked decimal data </td></tr>
<tr><td>[[$UnPost]]</td><td>Resets a specified Event Control Block (ECB) to an unposted state.</td></tr>
<tr><td>[[$UnqRec]]</td><td>In the case of a uniqueness violation, returns the file-relative record number of the record that already contains the field name = value pairIf no uniqueness violation occurred. returns -1.</td></tr>
<tr><td>[[$UnSpace]]</td><td>Normalize spaces and quotes</td></tr>
<tr><td>[[$Upcase]]</td><td>An uppercase string converted from a lower or mixed case string.</td></tr>
<tr><td>[[$Update]]</td><td>Name of the group update file or the current file.</td></tr>
<tr><td>[[$UpdFile]]</td><td>Name of the file in which a field level constraint violation has occurred, or a blank if no violation occurred.</td></tr>
<tr><td>[[$UpdFld]]</td><td>Name of the field for which a field level constraint violation has occurred, or a blank if no violation occurred.</td></tr>
<tr><td>[[$UpdLoc]]</td><td>Location name (node name) of the current update unit (Parallel Query Option/204 only).</td></tr>
<tr><td>[[$UpdOval]]</td><td>Value of the original field occurrence causing a constraint violation, when invoked from an ON FCC unit following the detection of an AT-MOST-ONE field-level constraint conflict. </td></tr>
<tr><td>[[$UpdRec]]</td><td>File-relative record number of the record whose update caused a field level constraint violation, or -1 if no violation occurred.</td></tr>
<tr><td>[[$UpdStat]]</td><td>Numeric value denoting the type of field level constraint violation that has occurred, or 0 if no violation occurred.</td></tr>
<tr><td>[[$UpdStmt]]</td><td>Type of User Language updating statement causing a field level constraint violation, or a blank if no violation occurred.</td></tr>
<tr><td>[[$UpdVal]]</td><td>Field value causing a field level constraint violation, or a blank if no violation occurred.</td></tr>
<tr><td>[[$UseASA]]</td><td>Prevent carriage control in USE output</td></tr>
<tr><td>[[$User]]</td><td>User's user number.</td></tr>
<tr><td>[[$Userid]]</td><td>User ID under which the user is logged in.</td></tr>
<tr><td>[[$UsrPriv]]</td><td>Whether a user ID has been granted specific <var class="product">Model 204</var> privileges.</td></tr>
<tr><td>[[$UsStat]]</td><td>Retrieve user's statistics into string</td></tr>
<tr><td>[[$UsStatL]]</td><td>Retrieve statistics for set of users into $list</td></tr>
<tr><td>[[$Verify]]</td><td>Whether every character in one string is present in a second string.</td></tr>
<tr><td>[[$View]]</td><td>Value of a parameter.</td></tr>
<tr><td>[[$Vnum]]</td><td>Whether a given argument is in a valid format for a SORT BY VALUE NUMERICAL statement or for any type of mathematical operation.</td></tr>
<tr><td>[[$Wait]]</td><td>Suspend a user until an Event Control Block (ECB) is posted.</td></tr>
<tr><td>[[$WakeUp]]</td><td>Pause user until specified time</td></tr>

<tr><td>[[List of Janus Web Server $functions|$Web_xxx]]</td><td>List of Janus Web Server $functions</td></tr>
<tr><td>[[$Windex]]</td><td>Word number of first occurrence of word in phrase</td></tr>
<tr><td>[[$Word]]</td><td>P word in a specified string, delimited by a blank or optionally specified character.</td></tr>
<tr><td>[[$Words]]</td><td>Number of words in a specified string, delimited by a blank or optionally specified character.</td></tr>
<tr><td>[[$X2C]]</td><td>One-byte EBCDIC characters translated from a string of 2-byte hexadecimal character.</td></tr>
<tr><td>[[$X2D]]</td><td>Convert hex string to integer</td></tr>
</table>
</div>

==Using functions==
You can use functions in several ways, including, as a term in:
<ul>
<li>An expression in a variable assignment statement, for example:</li>
</ul>
%X=$EDIT(2573,'99999')

<ul>
<li>The specifications in a PRINT statement</li>
</ul>

A PRINT statement can include a function call anywhere a field name can be used. For example:
PRINT $EDIT(2573,'99999')

<ul>
<li>An expression in a conditional statement, for example:</li>
</ul>
IF $EDIT(2573,'99999') EQ 02573 THEN...

<ul>
<li>An expression which serves as the argument to another function, for example:</li>
</ul>
%L=$LEN($EDIT(2573,'99999'))


The direct use of function calls in some statements, such as FIND, results in compilation errors. 

====Comparing successful and unsuccessful $function code====

If your request is coded as follows:
BEGIN
$EDIT(2573,'99999')
END


The following error is your result:
*** 1 M204.0229: INVALID STATEMENT $EDIT(2573,'99999')


However, if you code your request as follows, it works properly:
BEGIN
PRINT $EDIT(2573,'99999')
* Or *
* %X=$EDIT(2573,'99999') *
END


===Function return values===

Each function returns a single value to the calling request. For example, this function sets %A equal to the user's login account name:
%a = $account


This function causes the length of the current value of the FULLNAME field to be compared to 10:
IF $LEN(FULLNAME) GT 10 THEN
.
.
.


===Function arguments===

Some functions require one or more arguments which allow you to pass information to the subroutine. Some functions take no arguments. Arguments must be enclosed in parentheses and separated by commas. For example:
IF $READ('CONTINUE?') EQ 'YES' THEN
.
.
.
%X = $mod(COUNT IN CT, %BASE)


====Rules for function arguments====

Function arguments follow the normal rules for arithmetic expressions. Arguments can include other function calls and can perform any type of computation. See the section [[Using variables and values in computation#Expressions|Expressions]] for detailed information on expression syntax.

====Argument evaluation and conversion====

<var class="product">Model 204</var> evaluates each argument to a function as either a string or a number. When this data type conflicts with the data type required by the function, the following rules apply:
<ul>
<li>If an argument is expected to be numeric but is a string, <var class="product">Model 204</var> converts the string to a number according to the conversion rules described in the assignment statement discussion in [[Using variables and values in computation#Relationship between %variable assignment and declaration|Relationship between %variable assignment and declaration]] and [[Using variables and values in computation#Conversion|Conversion]]. </li>
</li>
<li>If an argument is expected to be a string but is numeric, <var class="product">Model 204</var> converts the number to a string. </li>
</li>
<li>If the original number contains decimal places, they are lost during the conversion.</li>
</li>
</ul>

==User-written functions==

In addition to the functions provided by <var class="product">SOUL</var>, some customer sites write their own functions based on their particular needs.
Before using any user-written functions, make sure that your site's FUNU module has been reassembled with the macro library supplied with the current release. Also, please be sure to carefully test your user-written functions before your system goes into production. 

<blockquote class="note">
Notes:
<ul>
<li>It is recommended that all user-written functions use the STMG/LMG Assembly Language instructions to save and restore any registers that are modified.
<li>The RESULT macro does not work in Model 204 Version 5.1 and later. Change any use of the RESULT macro in $functions to use the standard LEAVENUM, LEAVEF0 and LEAVESTR macros.
<li>In addition to the above considerations, see the [[Model 204 installation#FUNU|installation instructions relating to FUNU]].
</ul></blockquote>

Customers are individually responsible for any functions they write. Rocket Software takes no responsibility for user-written functions or their documentation.

[[Category:SOUL]]

CurrentRecordId (Record function)

2025-03-25T02:33:47Z

Alex: /* Usage notes */

{{Template:Record:CurrentRecordId subtitle}}

Get the <var class="product">Imagine Transparency</var> recordId for current (innermost) record <var>For</var> loop.
==Syntax==
{{Template:Record:CurrentRecordId syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%string</th><td>The recordId of the <var>For</var> loop record on <var class="product">Imagine</var> if the record is in a file that is an <var class="product">Imagine Transparency</var> file, or an empty string, otherwise.</td></tr>
<tr><th nowrap="true"><var>%(Record In </var>filOrGrp name<var>)</var></th>
<td>The class name in parentheses denotes a shared method. <var>CurrentRecordId</var> can also be invoked via a <var>Record</var> object variable, which may be <var>Null</var>.</td></tr>
</table>
==Usage notes==

The recordId for <var class="product">Imagine</var> associated records is an 8-byte binary string value. This can be used to create another <var>Record</var> object with the [[NewFromRecordId (Record function)|NewFromRecordId]] function though there is really no good reason to create another <var>Record</var> object this way, or it could be passed to the <var class="product">Imagine</var> broker, probably after converting it to hex. Note, however, that while recordIds uniquely identify any record in <var class="product">Imagine</var>, <var class="product">Imagine</var> still needs to know the <var class="product">Imagine</var> file that holds the record to locate it.


==Examples==
==See also==
{{Template:Record:CurrentRecordId footer}}

RecordId (Record function)

2025-03-25T02:33:32Z

Alex: /* Usage notes */

{{Template:Record:RecordId subtitle}}

Get the <var class="product">Imagine Transparency</var> recordId for the <var>Record</var> object.
==Syntax==
{{Template:Record:RecordId syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%string</th><td>The recordId of the record on <var class="product">Imagine</var> if the record is in a file that is an <var class="product">Imagine Transparency</var> file, or an empty string, otherwise.</td></tr>
<tr><th>record</th>
<td><var>Record</var> object</td></tr>
</table>

==Usage notes==

The recordId for <var class="product">Imagine</var> associated records is an 8-byte binary string value. This can be used to create another <var>Record</var> object with the [[NewFromRecordId (Record function)|NewFromRecordId]] function though there is really no good reason to create another <var>Record</var> object this way, or it could be passed to the <var class="product">Imagine</var> broker, probably after converting it to hex. Note, however, that while recordIds uniquely identify any record in <var class="product">Imagine</var>, <var class="product">Imagine</var> still needs to know the <var class="product">Imagine</var> file that holds the record to locate it.


==Examples==
==See also==
{{Template:Record:RecordId footer}}

RecordId (Record function)

2025-03-25T02:32:50Z

Alex: /* Syntax terms */

{{Template:Record:RecordId subtitle}}

Get the <var class="product">Imagine Transparency</var> recordId for the <var>Record</var> object.
==Syntax==
{{Template:Record:RecordId syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%string</th><td>The recordId of the record on <var class="product">Imagine</var> if the record is in a file that is an <var class="product">Imagine Transparency</var> file, or an empty string, otherwise.</td></tr>
<tr><th>record</th>
<td><var>Record</var> object</td></tr>
</table>

==Usage notes==

The recordId for <var class="product">Imagine</var> associated records is an 8-byte binary string value. This can be used to create another <var>Record</var> object with the [[NewFromRecordId (Record function)|NewFromRecordId]] function though there is really no good reason to create another <var>Record</var> object this way, or it could be passed to the <var class="product">Imagine</var> broker, probably after converting it to hex. Note, however, that while recordIds uniquely identify any record in <var class="product">Imagine</var>, <var class="product">Imagine</var> still needs to know the <var class="product">Imagine</var> file that holds the record to locate it.
==Examples==
==See also==
{{Template:Record:RecordId footer}}

CurrentRecordId (Record function)

2025-03-25T02:32:26Z

Alex:

RecordId (Record function)

2025-03-24T23:13:03Z

Alex:

{{Template:Record:RecordId subtitle}}

Get the <var class="product">Imagine Transparency</var> recordId for the <var>Record</var> object.
==Syntax==
{{Template:Record:RecordId syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%string</th><td>The recordId of the record on <var class="product">Imagine</var> if the record is in a file that is an <var class="product">Imagine Transparency</var> file. or an empty string, otherwise.</td></tr>
<tr><th>record</th>
<td><var>Record</var> object</td></tr>
</table>
==Usage notes==

The recordId for <var class="product">Imagine</var> associated records is an 8-byte binary string value. This can be used to create another <var>Record</var> object with the [[NewFromRecordId (Record function)|NewFromRecordId]] function though there is really no good reason to create another <var>Record</var> object this way, or it could be passed to the <var class="product">Imagine</var> broker, probably after converting it to hex. Note, however, that while recordIds uniquely identify any record in <var class="product">Imagine</var>, <var class="product">Imagine</var> still needs to know the <var class="product">Imagine</var> file that holds the record to locate it.
==Examples==
==See also==
{{Template:Record:RecordId footer}}

NewFromRecordId (Record function)

2025-03-24T23:03:09Z

Alex: /* Syntax terms */

{{Template:Record:NewFromRecordId subtitle}}

This constructor method creates a <var>Record</var> object from a recordId. This is only valid if the record is an [[Imagine Transparency]] record.
==Syntax==
{{Template:Record:file:NewFromRecordId syntax}}
{{Template:Record:group:NewFromRecordId syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%fileRecord</th><td>A file context <var>Record</var> object</td></tr>
<tr><th>%groupRecord</th><td>A group context <var>Record</var> object</td></tr>
<tr><th nowrap="true"><var>[%(Record In </var>filOrGrp name<var>):]</var></th>
<td>The optional class name in parentheses denotes a [[Notation conventions for methods#Constructors|virtual constructor]]. See [[#Usage notes|"Usage notes"]], below, for more information about invoking a virtual constructor.</td></tr>
<tr><th>recordId</th>
<td>The recordId to be used to locate the record. This must be an 8-byte (string) binary value.</td></tr>
<tr><th>filename</th>
<td>The name of the file in the group (for a group context call) used to locate the record. This must be a string value.</td></tr>
</table>

==Usage notes==
==Examples==
==See also==
{{Template:Record:NewFromRecordId footer}}

NewFromRecordId (Record function)

2025-03-24T21:46:56Z

Alex: /* Syntax terms */

{{Template:Record:NewFromRecordId subtitle}}

This constructor method creates a <var>Record</var> object from a recordId. This is only valid if the record is an [[Imagine Transparency]] record.
==Syntax==
{{Template:Record:file:NewFromRecordId syntax}}
{{Template:Record:group:NewFromRecordId syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%record</th><td>A <var>Record</var> object</td></tr>
<tr><th nowrap="true"><var>[%(Record In </var>filOrGrp name<var>):]</var></th>
<td>The optional class name in parentheses denotes a [[Notation conventions for methods#Constructors|virtual constructor]]. See [[#Usage notes|"Usage notes"]], below, for more information about invoking a virtual constructor.</td></tr>
<tr><th>recordId</th>
<td>The recordId to be used to locate the record. This must be an 8-byte binary value.</td></tr>
</table>

==Usage notes==
==Examples==
==See also==
{{Template:Record:NewFromRecordId footer}}

NewFromRecordId (Record function)

2025-03-24T21:18:23Z

Alex:

{{Template:Record:NewFromRecordId subtitle}}

This constructor method creates a <var>Record</var> object from a recordId. This is only valid if the record is an [[Imagine Transparency]] record.
==Syntax==
{{Template:Record:file:NewFromRecordId syntax}}
{{Template:Record:group:NewFromRecordId syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%outRecord</th><td><var>Record</var> object</td></tr>
<tr><th nowrap="true"><var>[%(Record In </var>filOrGrp name<var>):]</var></th>
<td>The optional class name in parentheses denotes a [[Notation conventions for methods#Constructors|virtual constructor]]. See [[#Usage notes|"Usage notes"]], below, for more information about invoking a virtual constructor.</td></tr>
<tr><th>string</th>
<td>string</td></tr>
</table>

==Usage notes==
==Examples==
==See also==
{{Template:Record:NewFromRecordId footer}}

NewFromRecordId (Record function)

2025-03-24T21:16:42Z

Alex: /* Syntax */

{{Template:Record:NewFromRecordId subtitle}}

This page is [[under construction]].
==Syntax==
{{Template:Record:file:NewFromRecordId syntax}}
{{Template:Record:group:NewFromRecordId syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%outRecord</th><td><var>Record</var> object</td></tr>
<tr><th nowrap="true"><var>[%(Record In </var>filOrGrp name<var>):]</var></th>
<td>The optional class name in parentheses denotes a [[Notation conventions for methods#Constructors|virtual constructor]]. See [[#Usage notes|"Usage notes"]], below, for more information about invoking a virtual constructor.</td></tr>
<tr><th>string</th>
<td>string</td></tr>
</table>

==Usage notes==
==Examples==
==See also==
{{Template:Record:NewFromRecordId footer}}

NewFromRecordId (Record function)

2025-03-24T18:47:39Z

Alex: /* Syntax */

{{Template:Record:NewFromRecordId subtitle}}

This page is [[under construction]].
==Syntax==
{{Template:Record:file:NewFromRecordId syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%outRecord</th><td><var>Record</var> object</td></tr>
<tr><th nowrap="true"><var>[%(Record In </var>filOrGrp name<var>):]</var></th>
<td>The optional class name in parentheses denotes a [[Notation conventions for methods#Constructors|virtual constructor]]. See [[#Usage notes|"Usage notes"]], below, for more information about invoking a virtual constructor.</td></tr>
<tr><th>string</th>
<td>string</td></tr>
</table>

==Usage notes==
==Examples==
==See also==
{{Template:Record:NewFromRecordId footer}}