SirLib programmer's reference - Revision history

JAL: mention RKWeb equivalents

2017-06-21T23:13:55Z

mention RKWeb equivalents

← Older revision		Revision as of 23:13, 21 June 2017
Line 1:		Line 1:
	~~<!-- Page name: SirLib programmer's reference-->~~

	<p class="caption" style="width:550px">SirPro procedure list screen</p>		<p class="caption" style="width:550px">SirPro procedure list screen</p>
	<p class="figure">[[File:SlibProcList.png\|550px]]</p>		<p class="figure">[[File:SlibProcList.png\|550px]]</p>
Line 7:		Line 5:
	programmer in the <var class="product">SirLib</var>-controlled environment.		programmer in the <var class="product">SirLib</var>-controlled environment.
	This screen, and others like it, provide access to all procedure activity		This screen, and others like it, provide access to all procedure activity
	in <var class="product">Model 204</var>.		in <var class="product">Model 204</var>.
	Details on the use of <var class="product">SirPro</var>, including managed update commands, are		Details on the use of <var class="product">SirPro</var>, including managed update commands, are contained in the [[SirPro]] pages.
	contained in the [[SirPro]] pages.		Managed update prefix commands are the only part of <var class="product">SirPro</var> discussed in this document.
	Managed update prefix commands are the only part of <var class="product">SirPro</var> discussed in
	this document.		<p class="note"><b>Note:</b> You access a similar procedure list in [[RKWeb]] by selecting <code>Build > Edit</code> and clicking the <b>Open Procedure List</b> button. Prefix commands are not available in RKWeb, however, and require the SirPro TN3270 interface. </p>

	The <var>X</var>, <var>Q</var>, <var>N</var>, <var>K</var>, and <var>Z</var> prefix commands are used to generate "working,"		The <var>X</var>, <var>Q</var>, <var>N</var>, <var>K</var>, and <var>Z</var> prefix commands are used to generate "working,"
	Base, and Sequenced copies of procedures and to generate updates from		Base, and Sequenced copies of procedures and to generate updates from those copies.
	those copies.
	The programmer types one of these managed update commands to the left of the		The programmer types one of these managed update commands to the left of the
	selected procedure and presses Enter.		selected procedure and presses Enter.
	<var class="product">SirPro</var> then presents one of the managed update screens to get further		<var class="product">SirPro</var> then presents one of the managed update screens to get further details on the managed update.
	details on the managed update.
	Those screens are shown in the following detailed sections.		Those screens are shown in the following detailed sections.

	{{Template:SirPro commands}}		{{Template:SirPro commands}}

JAL: replace command content with a template

2015-10-28T22:47:42Z

replace command content with a template

Show changes

JAL: minor cleanup

2015-10-28T21:57:55Z

minor cleanup

Show changes

JAL: misc cleanup

2015-10-28T20:57:00Z

misc cleanup

Show changes

JAL: misc formatting

2015-10-28T18:31:30Z

misc formatting

← Older revision		Revision as of 18:31, 28 October 2015
Line 96:		Line 96:
	</table>		</table>

			===Q command processing===
			This section's content provides a deeper understanding of how the command works; although knowing the processing details are not a requirement to use the product.

	When the <var>Q</var> command is executed, <var class="product">SirLib</var> looks in the		When the <var>Q</var> command is executed, <var class="product">SirLib</var> looks in the
	source file for a procedure named <code>BASE.<i>procname</i></code>, where		source file for a procedure named <code>BASE.<i>procname</i></code>, where
Line 141:		Line 144:
	Subsequent new lines that are part of the same update are incremented by a		Subsequent new lines that are part of the same update are incremented by a
	power of 10 less than the last sequence of numbers for the section of code. Later changes that apply to the same section again begin numbering at their starting sequence number plus 1, and they continue to increment at the next lowest available power of 10.		power of 10 less than the last sequence of numbers for the section of code. Later changes that apply to the same section again begin numbering at their starting sequence number plus 1, and they continue to increment at the next lowest available power of 10.

	~~Fortunately,~~ the ~~programmer doesn't have to understand any of this in~~		===Understanding the sequence numbers===
	~~order for it to work.~~ The lower-order digit(s) of the sequence numbers in a <var>SEQ</var> procedure~~, however,~~ indicate the number of times a section of code has been changed. The sequence numbers themselves indicate whether the <var>XCompare</var> is able to "fit" changes into the same section of code again.		The lower-order digit(s) of the sequence numbers in a <var>SEQ</var> procedure indicate the number of times a section of code has been changed. The sequence numbers themselves indicate whether the <var>XCompare</var> is able to "fit" changes into the same section of code again.
	For example, a section of code with sequence numbers like the following		For example, a section of code with sequence numbers like the following
	indicates that changes still "fit" in the hundreds and tens columns:		indicates that changes still "fit" in the hundreds and tens columns:

JAL: mixed case for XCOMPARE

2015-10-28T18:03:09Z

mixed case for XCOMPARE

← Older revision		Revision as of 18:03, 28 October 2015
Line 22:		Line 22:
	Those screens are shown in the following detailed sections.		Those screens are shown in the following detailed sections.

	==Q (~~SEQUENCE~~) command==		==Q (Sequence) command==
	"Sequencing" is the managed update method by which programmers		"Sequencing" is the managed update method by which programmers
	make copies of procedures to work on.		make copies of procedures to work on.
Line 257:		Line 257:
	</table>		</table>

	==N (~~NEW~~) command==		==N (New) command==
	Preceding a procedure by an <var>N</var> in the <var class="product">SirPro</var> edit screen tells the		Preceding a procedure by an <var>N</var> in the <var class="product">SirPro</var> edit screen tells the
	system to generate an update procedure, similar to that produced by <var>X</var>, but containing <i>all</i> lines of the specified procedure, because it is a new procedure to the system.		system to generate an update procedure, similar to that produced by <var>X</var>, but containing <i>all</i> lines of the specified procedure, because it is a new procedure to the system.
Line 305:		Line 305:
	</table>		</table>

	==K (~~KLOBBER~~) command==		==K (Klobber) command==
	Prefixing a procedure with a <var>K</var> command in the <var class="product">SirPro</var> edit screen directs <var class="product">SirLib</var> to generate an update procedure that		Prefixing a procedure with a <var>K</var> command in the <var class="product">SirPro</var> edit screen directs <var class="product">SirLib</var> to generate an update procedure that
	will cause the deletion of the indicated procedure.		will cause the deletion of the indicated procedure.
	<p class="note"><b>Note:</b> Managed update deletes are always logical deletes, allowing deleted procedures to be recovered at any time when the file is reconfigured. For this reason, an empty (zero-line) version of the deleted procedure is left in the file, and it should not be physically deleted. </p>		<p class="note"><b>Note:</b> Managed update deletes are always logical deletes, allowing deleted procedures to be recovered at any time when the file is reconfigured. For this reason, an empty (zero-line) version of the deleted procedure is left in the file, and it should not be physically deleted. </p>
	<p>		<p>
	The <var>K</var> prefix command presents a <b>Klobber ~~Procedure~~</b> screen: </p>		The <var>K</var> prefix command presents a <b>Klobber procedure</b> screen: </p>

	<p class="caption" style="width:450px">Generating a logical delete of a procedure in SirPro</p>		<p class="caption" style="width:450px">Generating a logical delete of a procedure in SirPro</p>
Line 356:		Line 356:
	</table>		</table>

	==Z (~~RESEQUENCE~~) command==		==Z (Resequence) command==
	The sequence numbers generated by <var class="product">SirLib</var> are for the most part of no concern to SOUL programmers.		The sequence numbers generated by <var class="product">SirLib</var> are for the most part of no concern to SOUL programmers.
	However, if a large number of update procedures are generated which		However, if a large number of update procedures are generated which

JAL: mixed case for XCOMPARE

2015-10-28T16:14:28Z

mixed case for XCOMPARE

JAL: mixed case for XCOMPARE

2015-10-28T16:04:53Z

mixed case for XCOMPARE

JAL: minor cleanup

2015-10-27T21:24:19Z

minor cleanup

Show changes

JAL: resize graphics

2015-10-19T22:33:36Z

resize graphics

← Older revision		Revision as of 22:33, 19 October 2015
Line 34:		Line 34:
	procedure groups are recommended for development apsys.		procedure groups are recommended for development apsys.

	<p class="caption" style="width:~~522px~~">SirPro screen for generating SEQ and working procedure copies</p>		<p class="caption" style="width:450px">SirPro screen for generating SEQ and working procedure copies</p>
	<p class="figure">[[File:SlibSeqProc.png\|~~522px~~]]</p>		<p class="figure">[[File:SlibSeqProc.png\|450px]]</p>

	The <var>Q</var> command tells <var class="product">SirLib</var> to generate both a copy of the selected		The <var>Q</var> command tells <var class="product">SirLib</var> to generate both a copy of the selected
Line 209:		Line 209:
	The <var>X</var> prefix command presents an <var>XCOMPARE</var> screen:		The <var>X</var> prefix command presents an <var>XCOMPARE</var> screen:

	<p class="caption" style="width:~~527px~~">SirPro XCOMPARE screen</p>		<p class="caption" style="width:450px">SirPro XCOMPARE screen</p>
	<p class="figure">[[File:SlibXcompare.png\|~~527px~~]]</p>		<p class="figure">[[File:SlibXcompare.png\|450px]]</p>

	<table class="thJustBold">		<table class="thJustBold">
Line 290:		Line 290:
	The <var>N</var> prefix command presents a Create New Procedure screen:		The <var>N</var> prefix command presents a Create New Procedure screen:

	<p class="caption" style="width:~~524px~~">Generating a New update procedure</p>		<p class="caption" style="width:450px">Generating a New update procedure</p>
	<p class="figure">[[File:SlibCreateNew.png\|~~524px~~]]</p>		<p class="figure">[[File:SlibCreateNew.png\|450px]]</p>

	<table class="thJustBold">		<table class="thJustBold">
Line 343:		Line 343:
	The <var>K</var> prefix command presents a <b>Klobber Procedure</b> screen:		The <var>K</var> prefix command presents a <b>Klobber Procedure</b> screen:

	<p class="caption" style="width:~~526px~~">Generating a logical delete of a procedure in SirPro</p>		<p class="caption" style="width:450x">Generating a logical delete of a procedure in SirPro</p>
	<p class="figure">[[File:SlibKlobber.png\|~~526px~~]]</p>		<p class="figure">[[File:SlibKlobber.png\|450px]]</p>

	<table class="thJustBold">		<table class="thJustBold">
Line 399:		Line 399:
	The <var>Z</var> command presents a <b>Resequence Procedure</b> screen:		The <var>Z</var> command presents a <b>Resequence Procedure</b> screen:

	<p class="caption" style="width:~~527px~~">Resequencing a procedure in SirPro</p>		<p class="caption" style="width:450px">Resequencing a procedure in SirPro</p>
	<p class="figure">[[File:SlibResequence.png\|~~527px~~]]</p>		<p class="figure">[[File:SlibResequence.png\|450px]]</p>

	<table class="thJustBold">		<table class="thJustBold">

← Older revision		Revision as of 16:14, 28 October 2015
Line 35:		Line 35:
	<p class="figure">[[File:SlibSeqProc.png\|450px]]</p>		<p class="figure">[[File:SlibSeqProc.png\|450px]]</p>

	The <var>Q</var> command tells <var class="product">SirLib</var> to generate both a copy of the selected procedure (the copy that the programmer will work on) and a "sequenced" copy of the procedure (a copy containing sequence or line numbers), which will later be used as comparison input for the <var>~~Xcompare~~</var> command.		The <var>Q</var> command tells <var class="product">SirLib</var> to generate both a copy of the selected procedure (the copy that the programmer will work on) and a "sequenced" copy of the procedure (a copy containing sequence or line numbers), which will later be used as comparison input for the <var>XCompare</var> command.
	Building these copies is always the first programming step in generating		Building these copies is always the first programming step in generating
	a managed update.		a managed update.
Line 133:		Line 133:

	The sequenced version of a procedure should never be changed, as it is		The sequenced version of a procedure should never be changed, as it is
	the "before" image for the <var>~~Xcompare~~</var> that will eventually generate the update procedure. Sequence numbers should not concern programmers for the most part, though there are a few times when it is worth knowing something about how they work.		the "before" image for the <var>XCompare</var> that will eventually generate the update procedure. Sequence numbers should not concern programmers for the most part, though there are a few times when it is worth knowing something about how they work.

	The <var>Q</var> command automatically begins sequencing at 10000, and it		The <var>Q</var> command automatically begins sequencing at 10000, and it
	increments each line in the <code>BASE.<i>procname</i></code> procedure by 10000. As changes are generated, the <var>~~Xcompare~~</var> function generates new line numbers for lines of code being inserted and replaced.		increments each line in the <code>BASE.<i>procname</i></code> procedure by 10000. As changes are generated, the <var>XCompare</var> function generates new line numbers for lines of code being inserted and replaced.
	The <var>~~Xcompare~~</var> algorithm attempts to number the first new line of code beginning with a sequence number 1 greater than its starting point in the existing sequence (this applies to Inserts and Replaces: it is irrelevant for Deletes).		The <var>XCompare</var> algorithm attempts to number the first new line of code beginning with a sequence number 1 greater than its starting point in the existing sequence (this applies to Inserts and Replaces: it is irrelevant for Deletes).

	Subsequent new lines that are part of the same update are incremented by a		Subsequent new lines that are part of the same update are incremented by a
Line 143:		Line 143:

	Fortunately, the programmer doesn't have to understand any of this in		Fortunately, the programmer doesn't have to understand any of this in
	order for it to work. The lower-order digit(s) of the sequence numbers in a <var>SEQ</var> procedure, however, indicate the number of times a section of code has been changed. The sequence numbers themselves indicate whether the <var>~~Xcompare~~</var> is able to "fit" changes into the same section of code again.		order for it to work. The lower-order digit(s) of the sequence numbers in a <var>SEQ</var> procedure, however, indicate the number of times a section of code has been changed. The sequence numbers themselves indicate whether the <var>XCompare</var> is able to "fit" changes into the same section of code again.
	For example, a section of code with sequence numbers like the following		For example, a section of code with sequence numbers like the following
	indicates that changes still "fit" in the hundreds and tens columns:		indicates that changes still "fit" in the hundreds and tens columns:
Line 163:		Line 163:
	Replace (<code>./R</code>) commands operate slightly differently than		Replace (<code>./R</code>) commands operate slightly differently than
	Insert, but the outcome looks very similar.		Insert, but the outcome looks very similar.
	If changes no longer "fit" within the sequence numbers, <var>~~Xcompare~~</var> still generates an update procedure for this section of code, but the update procedure is unnecessarily long, and <var class="product">SirLib</var> might lose its ability to detect update collisions. In this case, a Resequence is required, as described later in this page.		If changes no longer "fit" within the sequence numbers, <var>XCompare</var> still generates an update procedure for this section of code, but the update procedure is unnecessarily long, and <var class="product">SirLib</var> might lose its ability to detect update collisions. In this case, a Resequence is required, as described later in this page.

	Once an initial update is coded and the update procedure saved in		Once an initial update is coded and the update procedure saved in
Line 171:		Line 171:
	insertion of the update code.		insertion of the update code.

	==X (~~Xcompare~~) command==		==X (XCompare) command==
	Prefixing a procedure by an <var>X</var> in <var class="product">SirPro</var> tells the <var class="product">SirLib</var> system		Prefixing a procedure by an <var>X</var> in <var class="product">SirPro</var> tells the <var class="product">SirLib</var> system
	to compare the specified procedure against a matching "sequenced"		to compare the specified procedure against a matching "sequenced"
	procedure, generating another procedure that contains the differences		procedure, generating another procedure that contains the differences
	between the two. The <var>X</var> prefix command presents an <var>~~Xcompare~~</var> screen:		between the two. The <var>X</var> prefix command presents an <var>XCompare</var> screen:

	<p class="caption" style="width:450px">SirPro ~~Xcompare~~ screen</p>		<p class="caption" style="width:450px">SirPro XCompare screen</p>
	<p class="figure">[[File:SlibXcompare.png\|450px]]</p>		<p class="figure">[[File:SlibXcompare.png\|450px]]</p>

Line 210:		Line 210:
	<table class="thJustBold">		<table class="thJustBold">
	<tr><th>FixFile</th>		<tr><th>FixFile</th>
	<td>Name of <var class="product">Model 204</var> file to contain the update procedure produced by this invocation of <var>~~Xcompare~~</var>.</td></tr>		<td>Name of <var class="product">Model 204</var> file to contain the update procedure produced by this invocation of <var>XCompare</var>.</td></tr>

	<tr><th>Password</th>		<tr><th>Password</th>
Line 245:		Line 245:
	The default sync count value is 2, which works well for the vast majority of cases. </p>		The default sync count value is 2, which works well for the vast majority of cases. </p>
	<p>		<p>
	Increasing the sync count may reduce the number of difference lines found, resulting in smaller update procedures, or it may have no effect at all beyond a minor performance penalty in the <var>~~Xcompare~~</var> operation.		Increasing the sync count may reduce the number of difference lines found, resulting in smaller update procedures, or it may have no effect at all beyond a minor performance penalty in the <var>XCompare</var> operation.
	In a very few cases it may produce larger output procedures.		In a very few cases it may produce larger output procedures.
	An entered value of <code>*</code> tells <var>~~Xcompare~~</var> to repeat the compare operation, increasing the sync count from 1 until it reaches a value that no longer produces a smaller output procedure.		An entered value of <code>*</code> tells <var>XCompare</var> to repeat the compare operation, increasing the sync count from 1 until it reaches a value that no longer produces a smaller output procedure.
	This is the worst-performing option for running <var>~~Xcompare~~</var>, but it almost always generates the smallest possible output procedure.		This is the worst-performing option for running <var>XCompare</var>, but it almost always generates the smallest possible output procedure.
	Unless changes are massive and many, the size of the output procedure is fairly irrelevant, and adjusting the sync count has little utility.</p></td></tr>		Unless changes are massive and many, the size of the output procedure is fairly irrelevant, and adjusting the sync count has little utility.</p></td></tr>

← Older revision		Revision as of 16:04, 28 October 2015
Line 133:		Line 133:

	The sequenced version of a procedure should never be changed, as it is		The sequenced version of a procedure should never be changed, as it is
	the "before" image for the <var>~~XCOMPARE~~</var> that will eventually generate the update procedure. Sequence numbers should not concern programmers for the most part, though there are a few times when it is worth knowing something about how they work.		the "before" image for the <var>Xcompare</var> that will eventually generate the update procedure. Sequence numbers should not concern programmers for the most part, though there are a few times when it is worth knowing something about how they work.

	The <var>Q</var> command automatically begins sequencing at 10000, and it		The <var>Q</var> command automatically begins sequencing at 10000, and it
	increments each line in the <code>BASE.<i>procname</i></code> procedure by 10000. As changes are generated, the <var>~~XCOMPARE~~</var> function generates new line numbers for lines of code being inserted and replaced.		increments each line in the <code>BASE.<i>procname</i></code> procedure by 10000. As changes are generated, the <var>Xcompare</var> function generates new line numbers for lines of code being inserted and replaced.
	The <var>~~XCOMPARE~~</var> algorithm attempts to number the first new line of code beginning with a sequence number 1 greater than its starting point in the existing sequence (this applies to Inserts and Replaces: it is irrelevant for Deletes).		The <var>Xcompare</var> algorithm attempts to number the first new line of code beginning with a sequence number 1 greater than its starting point in the existing sequence (this applies to Inserts and Replaces: it is irrelevant for Deletes).

	Subsequent new lines that are part of the same update are incremented by a		Subsequent new lines that are part of the same update are incremented by a
Line 143:		Line 143:

	Fortunately, the programmer doesn't have to understand any of this in		Fortunately, the programmer doesn't have to understand any of this in
	order for it to work. The lower-order digit(s) of the sequence numbers in a <var>SEQ</var> procedure, however, indicate the number of times a section of code has been changed. The sequence numbers themselves indicate whether the <var>~~XCOMPARE~~</var> is able to "fit" changes into the same section of code again.		order for it to work. The lower-order digit(s) of the sequence numbers in a <var>SEQ</var> procedure, however, indicate the number of times a section of code has been changed. The sequence numbers themselves indicate whether the <var>Xcompare</var> is able to "fit" changes into the same section of code again.
	For example, a section of code with sequence numbers like the following		For example, a section of code with sequence numbers like the following
	indicates that changes still "fit" in the hundreds and tens columns:		indicates that changes still "fit" in the hundreds and tens columns:
Line 163:		Line 163:
	Replace (<code>./R</code>) commands operate slightly differently than		Replace (<code>./R</code>) commands operate slightly differently than
	Insert, but the outcome looks very similar.		Insert, but the outcome looks very similar.
	If changes no longer "fit" within the sequence numbers, <var>~~XCOMPARE~~</var> still generates an update procedure for this section of code, but the update procedure is unnecessarily long, and <var class="product">SirLib</var> might lose its ability to detect update collisions. In this case, a Resequence is required, as described later in this page.		If changes no longer "fit" within the sequence numbers, <var>Xcompare</var> still generates an update procedure for this section of code, but the update procedure is unnecessarily long, and <var class="product">SirLib</var> might lose its ability to detect update collisions. In this case, a Resequence is required, as described later in this page.

	Once an initial update is coded and the update procedure saved in		Once an initial update is coded and the update procedure saved in
Line 171:		Line 171:
	insertion of the update code.		insertion of the update code.

	==X (~~XCOMPARE~~) command==		==X (Xcompare) command==
	Prefixing a procedure by an <var>X</var> in <var class="product">SirPro</var> tells the <var class="product">SirLib</var> system		Prefixing a procedure by an <var>X</var> in <var class="product">SirPro</var> tells the <var class="product">SirLib</var> system
	to compare the specified procedure against a matching "sequenced"		to compare the specified procedure against a matching "sequenced"
	procedure, generating another procedure that contains the differences		procedure, generating another procedure that contains the differences
	between the two. The <var>X</var> prefix command presents an <var>~~XCOMPARE~~</var> screen:		between the two. The <var>X</var> prefix command presents an <var>Xcompare</var> screen:

	<p class="caption" style="width:450px">SirPro ~~XCOMPARE~~ screen</p>		<p class="caption" style="width:450px">SirPro Xcompare screen</p>
	<p class="figure">[[File:SlibXcompare.png\|450px]]</p>		<p class="figure">[[File:SlibXcompare.png\|450px]]</p>

Line 210:		Line 210:
	<table class="thJustBold">		<table class="thJustBold">
	<tr><th>FixFile</th>		<tr><th>FixFile</th>
	<td>Name of <var class="product">Model 204</var> file to contain the update procedure produced by this invocation of <var>~~XCOMPARE~~</var>.</td></tr>		<td>Name of <var class="product">Model 204</var> file to contain the update procedure produced by this invocation of <var>Xcompare</var>.</td></tr>

	<tr><th>Password</th>		<tr><th>Password</th>
Line 245:		Line 245:
	The default sync count value is 2, which works well for the vast majority of cases. </p>		The default sync count value is 2, which works well for the vast majority of cases. </p>
	<p>		<p>
	Increasing the sync count may reduce the number of difference lines found, resulting in smaller update procedures, or it may have no effect at all beyond a minor performance penalty in the <var>~~XCOMPARE~~</var> operation.		Increasing the sync count may reduce the number of difference lines found, resulting in smaller update procedures, or it may have no effect at all beyond a minor performance penalty in the <var>Xcompare</var> operation.
	In a very few cases it may produce larger output procedures.		In a very few cases it may produce larger output procedures.
	An entered value of <code>*</code> tells <var>~~XCOMPARE~~</var> to repeat the compare operation, increasing the sync count from 1 until it reaches a value that no longer produces a smaller output procedure.		An entered value of <code>*</code> tells <var>Xcompare</var> to repeat the compare operation, increasing the sync count from 1 until it reaches a value that no longer produces a smaller output procedure.
	This is the worst-performing option for running <var>~~XCOMPARE~~</var>, but it almost always generates the smallest possible output procedure.		This is the worst-performing option for running <var>Xcompare</var>, but it almost always generates the smallest possible output procedure.
	Unless changes are massive and many, the size of the output procedure is fairly irrelevant, and adjusting the sync count has little utility.</p></td></tr>		Unless changes are massive and many, the size of the output procedure is fairly irrelevant, and adjusting the sync count has little utility.</p></td></tr>