$Proc Touch: Difference between revisions

Latest revision as of 22:41, 20 September 2018

Change a procedure's last-update date and user

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

$Proc_Touch lets you change the last updating date/time, account ID, or both, of a Model 204 procedure.

$Proc_Touch is a callable function that accepts four string arguments and returns a numeric completion code.

Syntax

[%result =] $Proc_Touch (filename, procname, datetime, id)

Syntax terms

%result	Integer that indicates the success of the function.
filename	Name of file containing the procedure. If this argument is null, blank, or not specified, the current default file name is used. The file must be open.
procname	Name of the procedure to be "touched," that is, whose last-updating information is to be modified.
datetime	Date/time specification in either of the following formats: `YYDDDHHMISSXX` or `YYYYDDDHHMISSXX`. If `YY` is used, `CENTSPAN` is 1975. This argument may be a date and time in the future. If this argument is null or omitted, the current date and time is used. For more information about the CENTSPAN mechanism,
id	Account ID (ten-character maximum) to become the last updator. If `id` is not supplied, is null, or is blank, the ID of the `$Proc_Touch` caller is used. Note: This need not be the name of a valid user (this value is not validated, and it may include embedded blanks).

Return codes

0 - Success 1 - Procedure is in use 2 - Procedure does not exist or is secured 3 - Procedure name missing 4 - File name invalid 5 - No update privileges in file 6 - Invalid touch time 7 - Invalid account ID

Usage notes

Besides its use internally by SirLib to set more meaningful date/time stamps, $Proc_Touch is also useful for correcting the results of Model 204 COPY PROC commands (when the old date/time is lost because OLDDATE was not specified).
These restrictions apply to a $Proc_Touch operation:
- It must not be issued in the middle of another updating transaction.
- It is not part of an update unit and cannot be backed out.
- No roll-forward information is logged (or processed), so the effect of a $Proc_Touch could get lost if recovery is run.

Examples

In the following example, procedure COMP in file TESTPROC, last updated by user JACK, is "touched" to acquire an older date and user JACK3 as the last updating date and user:

Begin %RC is float OPEN FILE TESTPROC %RC = $Proc_Touch('TESTPROC', 'COMP', '200436411111111', 'JACK3') Print 'TOUCH return code is: ' %RC End

After this request finishes, the result of a DISPLAY PROC LIST command shows the modified date of the request and user JACK3 for the last update for procedure COMP:

COMP 12/29/04 11:11:11 136 JACK3

Products authorizing $Proc_Touch

@@ Line 2: / Line 2: @@
 <span class="pageSubtitle">Change a procedure's last-update date and user</span>
-<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $Proc_Touch function.</p>
+<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $Proc_Touch function.</p>
 <var>$Proc_Touch</var> lets you change the last updating date/time, account ID, or both, of a <var class="product">Model 204</var> procedure.
-Introduced in <var class="product">[[Sirius Mods]]</var> Version 6.7, <var>$Proc_Touch</var> is a [[Calling Sirius Mods $functions|callable]] function that accepts four string arguments and returns a numeric completion code.
+<var>$Proc_Touch</var> is a [[Calling Sirius Mods $functions|callable]] function that accepts four string arguments and returns a numeric completion code.
 ==Syntax==
-<p class="syntax"><section begin="syntax" /> [%result =] $Proc_Touch (filename, procname, datetime, id)
+<p class="syntax">[%result =] $Proc_Touch (filename, procname, datetime, id)
-<section end="syntax" /></p>
+</p>
 ===Syntax terms===
@@ Line 16: / Line 16: @@
 <tr><th>%result</th>
 <td>Integer that indicates the success of the function.</td></tr>
 <tr><th>filename</th>
 <td>Name of file containing the procedure. If this argument is null, blank, or not specified, the current default file name is used. The file must be open.</td></tr>
 <tr><th>procname</th>
 <td>Name of the procedure to be "touched," that is, whose last-updating information is to be modified.</td></tr>
 <tr><th>datetime</th>
+<td>Date/time specification in either of the following formats: <var>YYDDDHHMISSXX</var> or <var>YYYYDDDHHMISSXX</var>. If <code>YY</code> is used, <var>[[Datetime string formats#Using CENTSPAN|CENTSPAN]]</var> is 1975. This argument may be a date and time in the future. If this argument is null or omitted, the current date and time is used. For more information about the CENTSPAN mechanism, </td></tr>
-<td>Date/time specification in either of the following formats: <var>YYDDDHHMISSXX</var> or <var>YYYYDDDHHMISSXX</var>. If <tt>YY</tt>. is used, CENTSPAN is 1975. This argument may be a date and time in the future. If this argument is null or omitted, the current date and time is used. For more information about the CENTSPAN mechanism, </td></tr>
 <tr><th>id</th>
-<td>Account ID (ten-character maximum) to become the last updator. If <var class="term">id</var> is not supplied, is null, or is blank, the ID of the <var>$Proc_Touch</var> caller is used. <p>'''Note: ''' This need not be the name of a valid user (this value is not validated, and it may include embedded blanks). </blockquote>
+<td>Account ID (ten-character maximum) to become the last updator. If <var class="term">id</var> is not supplied, is null, or is blank, the ID of the <var>$Proc_Touch</var> caller is used.
-</td></tr></table>
+<p>
+'''Note: ''' This need not be the name of a valid user (this value is not validated, and it may include embedded blanks).</p></td></tr>
+</table>
-Besides its use internally by <var class="product">[[SirLib]]</var> to set more meaningful date/time stamps, <var>$Proc_Touch</var> is also useful for correcting the results of <var class="product">Model 204</var> COPY PROC commands (when the old date/time is lost because OLDDATE was not specified).
+===Return codes===
+<p class="code">0 - Success
+- Procedure is in use
+- Procedure does not exist or is secured
+- Procedure name missing
+- File name invalid
+- No update privileges in file
+- Invalid touch time
+- Invalid account ID
+</p>
-'''Note:''' These restrictions apply to a <var>$Proc_Touch</var> operation:
+==Usage notes==
+<ul>
+<li>Besides its use internally by <var class="product">[[SirLib]]</var> to set more meaningful date/time stamps, <var>$Proc_Touch</var> is also useful for correcting the results of <var class="product">Model 204</var> <var>COPY PROC</var> commands (when the old date/time is lost because <code>OLDDATE</code> was not specified).
+<li>These restrictions apply to a <var>$Proc_Touch</var> operation:
 <ul>
 <li>It must not be issued in the middle of another updating transaction.
 <li>It is not part of an update unit and cannot be backed out.
 <li>No roll-forward information is logged (or processed), so the effect of a <var>$Proc_Touch</var> could get lost if recovery is run.
+</ul>
 </ul>
+==Examples==
 In the following example, procedure COMP in file TESTPROC, last updated by user JACK, is "touched" to acquire an older date and user JACK3 as the last updating date and user:
 <p class="code"> Begin
@@ Line 49: / Line 68: @@
 </p>
-<p class="code">
+==Products authorizing {{PAGENAMEE}}==
-- Success
-- Procedure is in use
-- Procedure does not exist or is secured
-- Procedure name missing
-- File name invalid
-- No update privileges in file
-- Invalid touch time
-- Invalid account ID
-</p>
-<p class="caption">$Proc_Touch Error Codes
-</p>
 <ul class="smallAndTightList">
-<li>Sirius Functions
+<li>[[Sirius Functions]]
 <li>[[SirLib]]
 </ul>
-<p class="caption">Products authorizing $Proc_Touch
-</p>
 [[Category:$Functions|$Proc_Touch]]