Customizing functions and translation tables - Revision history

JAL: /* Sizing the CDTB module */ shorten example string

2018-01-09T16:39:20Z

Sizing the CDTB module: shorten example string

← Older revision		Revision as of 16:39, 9 January 2018
Line 410:		Line 410:
	<p>		<p>
	Each table entry requires:</p>		Each table entry requires:</p>
	<p class="code">Number of bytes in ~~the~~ longest code + 1 (for string length) + ~~the~~ number of bytes in ~~the~~ string + 1		<p class="code">Number of bytes in longest code + 1 (for string length) + number of bytes in string + 1
	</p>		</p>
	<p>		<p>
	32 bytes per table is required overhead for header information.</p>		32 bytes per table is required overhead for header information.</p>

	==Converting user-written functions==		==Converting user-written functions==
	<p>		<p>

ELowell at 00:34, 17 November 2016

2016-11-17T00:34:28Z

ELowell: /* Coding requirements for all operating systems */

2016-02-02T22:22:48Z

Coding requirements for all operating systems

← Older revision		Revision as of 22:22, 2 February 2016
Line 455:		Line 455:
	DROP reg		DROP reg
	</p></li>		</p></li>

			<li>As of version 7.7, KU is no longer 4K addressable from KOMM. It has been relocated to KOMM+1100 and must be addressed using grande (‘G’) instructions.
			In addition, all KUP… fields have been removed and replaced by their 64-bit equivalent KUG… fields. <br />
			For example, before 7.7, VTBL might be addressed by using <code>L R1,KUPVT</code>. As of version 7.7, that reference would require <code>LG R1,KUGVT</code>.</li>

	<li>The CSAVE or IOSAVE macros replace the SETAMODE macro in the MACLIB.</li>		<li>The CSAVE or IOSAVE macros replace the SETAMODE macro in the MACLIB.</li>

ELowell: /* Additional requirements for systems using 31-bit architecture */

2016-02-02T22:14:36Z

Additional requirements for systems using 31-bit architecture

← Older revision		Revision as of 22:14, 2 February 2016
Line 471:		Line 471:
	<li>Nearly all <var class="product">Model 204</var> data structures (servers and PCBs, for example) are in 31-bit storage. Pointers to such data structures must be 31-bit addresses. Three-byte address constants, for example <code>AL3(xyz)</code>, cannot be used as pointers.</li>		<li>Nearly all <var class="product">Model 204</var> data structures (servers and PCBs, for example) are in 31-bit storage. Pointers to such data structures must be 31-bit addresses. Three-byte address constants, for example <code>AL3(xyz)</code>, cannot be used as pointers.</li>

	<li>Code that explicitly manipulates <var class="product">Model 204</var> four-byte string codes must be modified to remove the high-order byte from the string code ~~prior to~~ adding KUGVT or KUGST. </li>		<li>Code that explicitly manipulates <var class="product">Model 204</var> four-byte string codes must be modified to remove the high-order byte from the string code before adding: <br />
			KUPVT or KUPST (version 7.6 and lower) <br />
			KUGVT or KUGST (version 7.7 and higher)</li>

	<li>If you invoke a z/OS service that must receive control in 24-bit mode (such as BSAM) use CSAVE or IOSAVE with the <code>AMODE=24</code> parameter. Code CRSTR or IORSTR with the <code>AMODE=31</code> parameter. You cannot reference KOMM or the pushdown list between <code>AMODE=24</code> and <code>AMODE=31</code> brackets.</li>		<li>If you invoke a z/OS service that must receive control in 24-bit mode (such as BSAM) use CSAVE or IOSAVE with the <code>AMODE=24</code> parameter. Code CRSTR or IORSTR with the <code>AMODE=31</code> parameter. You cannot reference KOMM or the pushdown list between <code>AMODE=24</code> and <code>AMODE=31</code> brackets.</li>

ELowell: /* Additional requirements for systems using 31-bit architecture */

2016-02-02T22:08:25Z

Additional requirements for systems using 31-bit architecture

← Older revision		Revision as of 22:08, 2 February 2016
Line 471:		Line 471:
	<li>Nearly all <var class="product">Model 204</var> data structures (servers and PCBs, for example) are in 31-bit storage. Pointers to such data structures must be 31-bit addresses. Three-byte address constants, for example <code>AL3(xyz)</code>, cannot be used as pointers.</li>		<li>Nearly all <var class="product">Model 204</var> data structures (servers and PCBs, for example) are in 31-bit storage. Pointers to such data structures must be 31-bit addresses. Three-byte address constants, for example <code>AL3(xyz)</code>, cannot be used as pointers.</li>

	<li>Code that explicitly manipulates <var class="product">Model 204</var> four-byte string codes must be modified to remove the high-order byte from the string code prior to adding ~~KUPVT~~ or ~~KUPST~~. </li>		<li>Code that explicitly manipulates <var class="product">Model 204</var> four-byte string codes must be modified to remove the high-order byte from the string code prior to adding KUGVT or KUGST. </li>

	<li>If you invoke a z/OS service that must receive control in 24-bit mode (such as BSAM) use CSAVE or IOSAVE with the <code>AMODE=24</code> parameter. Code CRSTR or IORSTR with the <code>AMODE=31</code> parameter. You cannot reference KOMM or the pushdown list between <code>AMODE=24</code> and <code>AMODE=31</code> brackets.</li>		<li>If you invoke a z/OS service that must receive control in 24-bit mode (such as BSAM) use CSAVE or IOSAVE with the <code>AMODE=24</code> parameter. Code CRSTR or IORSTR with the <code>AMODE=31</code> parameter. You cannot reference KOMM or the pushdown list between <code>AMODE=24</code> and <code>AMODE=31</code> brackets.</li>
Line 492:		Line 492:
	</ul></li>		</ul></li>
	</ul>		</ul>

	===Additional requirements for MP/204 (multiprocessing)===		===Additional requirements for MP/204 (multiprocessing)===
	<ul>		<ul>

JAL: minor cleanup

2015-07-14T21:44:00Z

minor cleanup

← Older revision		Revision as of 21:44, 14 July 2015
Line 239:		Line 239:
	<li>Load R2 with the length of the result string.</li>		<li>Load R2 with the length of the result string.</li>

	<li>Issue the LEAVESTR macro at the end of the code, just before POOL or LTORG to drop local addressability.</li>		<li>Issue the LEAVESTR macro at the end of the code, just before <code>POOL</code> or <code>LTORG</code> to drop local addressability.</li>
	</ol></li>		</ol></li>

Line 250:		Line 250:
	<li>Zero R2.</li>		<li>Zero R2.</li>

	<li>Issue the LEAVENUM macro just before POOL or LTORG.</li>		<li>Issue the LEAVENUM macro just before <code>POOL</code> or <code>LTORG</code>.</li>
	</ol></li>		</ol></li>

Line 257:		Line 257:
	<li>Load F0 with the long floating-point number.</li>		<li>Load F0 with the long floating-point number.</li>

	<li>Issue the LEAVEF0 macro just before POOL or LTORG.</li>		<li>Issue the LEAVEF0 macro just before <code>POOL</code> or <code>LTORG</code>.</li>
	</ol></li>		</ol></li>

	</ul></li>		</ul></li>

	<li>To return a ~~longstring~~ value, end the function routine by doing the following:		<li>To return a <var>Longstring</var> value, end the function routine by doing the following:
	<ol>		<ol>
	<li>Code LSTR=YES on the end of the FN macro, along with the S for string output.</li>		<li>Code <code>LSTR=YES</code> on the end of the FN macro, along with the <code>S</code> for string output.</li>

	<li>Load R1 with a pointer to the location of the result longstring minus one. If very long it will have to be above the bar.</li>		<li>Load R1 with a pointer to the location of the result longstring minus one. If very long it will have to be above the bar.</li>

	<li>Load R2 with the length of the result longstring.</li>		<li>Load R2 with the length of the result longstring.</li>
	<li>Issue the LEAVELST macro at the end of the code, just before POOL or LTORG to drop local addressability.</li>
			<li>Issue the LEAVELST macro at the end of the code, just before <code>POOL</code> or <code>LTORG</code> to drop local addressability.</li>
	</ol></li>		</ol></li>

	<li>To avoid affecting the performance of <var class="product">Model 204</var> multithreading operations, ensure that a SOUL function does not invoke any kind of synchronous operating system service that could result in a wait.</li>		<li>To avoid affecting the performance of <var class="product">Model 204</var> multithreading operations, ensure that a SOUL function does not invoke any kind of synchronous operating system service that could result in a wait.</li>

	</ul>		</ul>

JAL: minor formatting

2015-07-14T21:27:54Z

minor formatting

← Older revision		Revision as of 21:27, 14 July 2015
Line 27:		Line 27:

	<li>Make the new function available to the <var class="product">Model 204</var> SOUL compiler by adding an entry to the function table using the FN macro:		<li>Make the new function available to the <var class="product">Model 204</var> SOUL compiler by adding an entry to the function table using the FN macro:
	<p class="syntax">FN <span class="term">function-name</span>, <span class="term">R-type</span>, (<span class="term">A-type</span> [, <span class="term">A-type</span>]...),ROUTINE=		<p class="syntax">FN <span class="term">function-name</span>, <span class="term">R-type</span>, (<span class="term">A-type</span> [, <span class="term">A-type</span>]...), ROUTINE=
	</p>		</p>
	Where:		Where:
Line 45:		Line 45:
	</li>		</li>

	<li><var ~~class="term"~~>ROUTINE=</var> identifies the name on the ENTER macro of the routine that actually implements the function. This allows the name of the $function (the name on the FN macro) to be ~~greater~~ than 7 characters.~~</li>~~		<li><var>ROUTINE=</var> identifies the name on the ENTER macro of the routine that actually implements the function. This allows the name of the $function (the name on the FN macro) to be more than seven characters.
	<p>For example, one of the MQ/204 $functions, $MQ_FIND_QUEUE_ENTITY, has these two entries (not in FUNU) for FN and ENTER:</p>		<p>
			For example, one of the MQ/204 $functions, <var>$MQ_FIND_QUEUE_ENTITY</var>, has these two entries (not in FUNU) for FN and ENTER:</p>

	<p class="code">FN MQ_FIND_QUEUE_ENTITY,S,(S,S),MP=OK,ROUTINE=$MQFNDQ		<p class="code">FN MQ_FIND_QUEUE_ENTITY,S,(S,S),MP=OK,ROUTINE=$MQFNDQ
	...		...
	$MQFNDQ ENTER ZMODE=64		$MQFNDQ ENTER ZMODE=64
	assembly language code for the function		<i>assembly language code for the function</i>
	LEAVESTR		LEAVESTR
	</p>		</p>
Line 57:		Line 58:
	</ul>		</ul>

	<li>Code the function (as described in [[#Coding a function\|Coding a function]].</li>		<li>Code the function (as described in [[#Coding a function\|Coding a function]]).</li>
	</ol>		</ol>

	==Coding a function==		==Coding a function==

	===Coding conventions===		===Coding conventions===
	<p>		<p>

Tbullock: Forgot the LSTR=YES

2015-07-14T18:56:08Z

Forgot the LSTR=YES

← Older revision		Revision as of 18:56, 14 July 2015
Line 262:		Line 262:
	<li>To return a longstring value, end the function routine by doing the following:		<li>To return a longstring value, end the function routine by doing the following:
	<ol>		<ol>
			<li>Code LSTR=YES on the end of the FN macro, along with the S for string output.</li>
	<li>Load R1 with a pointer to the location of the result longstring minus one. If very long it will have to be above the bar.</li>		<li>Load R1 with a pointer to the location of the result longstring minus one. If very long it will have to be above the bar.</li>
	<li>Load R2 with the length of the result longstring.</li>		<li>Load R2 with the length of the result longstring.</li>

Tbullock: Oops messed up the li and ol nesting.

2015-07-14T18:46:44Z

Oops messed up the li and ol nesting.

← Older revision		Revision as of 18:46, 14 July 2015
Line 257:		Line 257:
	<li>Issue the LEAVEF0 macro just before POOL or LTORG.</li>		<li>Issue the LEAVEF0 macro just before POOL or LTORG.</li>
	</ol></li>		</ol></li>

			</ul></li>

	<li>To return a longstring value, end the function routine by doing the following:		<li>To return a longstring value, end the function routine by doing the following:
Line 266:		Line 268:

	<li>To avoid affecting the performance of <var class="product">Model 204</var> multithreading operations, ensure that a SOUL function does not invoke any kind of synchronous operating system service that could result in a wait.</li>		<li>To avoid affecting the performance of <var class="product">Model 204</var> multithreading operations, ensure that a SOUL function does not invoke any kind of synchronous operating system service that could result in a wait.</li>
	~~</ul></li>~~
	</ul>		</ul>

Tbullock: Add longstring - (LTORG is hidden in the POOL macro)

2015-07-14T18:41:13Z

Add longstring - (LTORG is hidden in the POOL macro)

← Older revision		Revision as of 18:41, 14 July 2015
Line 237:		Line 237:
	<li>Load R2 with the length of the result string.</li>		<li>Load R2 with the length of the result string.</li>

	<li>Issue the LEAVESTR macro at the end of the code, just before LTORG to drop local addressability.</li>		<li>Issue the LEAVESTR macro at the end of the code, just before POOL or LTORG to drop local addressability.</li>
	</ol></li>		</ol></li>

Line 248:		Line 248:
	<li>Zero R2.</li>		<li>Zero R2.</li>

	<li>Issue the LEAVENUM macro just before LTORG.</li>		<li>Issue the LEAVENUM macro just before POOL or LTORG.</li>
	</ol></li>		</ol></li>

Line 255:		Line 255:
	<li>Load F0 with the long floating-point number.</li>		<li>Load F0 with the long floating-point number.</li>

	<li>Issue the LEAVEF0 macro just before LTORG.</li>		<li>Issue the LEAVEF0 macro just before POOL or LTORG.</li>
			</ol></li>

			<li>To return a longstring value, end the function routine by doing the following:
			<ol>
			<li>Load R1 with a pointer to the location of the result longstring minus one. If very long it will have to be above the bar.</li>
			<li>Load R2 with the length of the result longstring.</li>
			<li>Issue the LEAVELST macro at the end of the code, just before POOL or LTORG to drop local addressability.</li>
	</ol></li>		</ol></li>

Line 261:		Line 268:
	</ul></li>		</ul></li>
	</ul>		</ul>

	===Coding messages===		===Coding messages===
	<p>		<p>

← Older revision		Revision as of 00:34, 17 November 2016
Line 1:		Line 1:
	==Overview==		==Overview==
	<p>		<p>
	User-written SOUL functions are stored in the user function module FUNU. The FUNU module is distributed as a skeletal module containing a table for functions and arguments, and the assembler code for one function. You can list the contents of FUNU using the procedures given in the Rocket Model 204 Installation Guide for your operating system.</p>		User-written SOUL functions are stored in the user function module FUNU. The FUNU module is distributed as a skeletal module containing a table for functions and arguments, and the assembler code for one function. You can list the contents of FUNU using the procedures given in the Rocket [[Model 204 installation\|Model 204 Installation Guide]] for your operating system.</p>
	<p>		<p>
	The Encoding/Decoding facility uses the translation tables contained in the distributed CDTB module. The <var>$Code</var> and <var>$Decode</var> functions access the translation tables to allow the use of both coded and string values of fields. The contents of the translation tables can be listed by using the procedures listed in the Rocket ~~<var class="product">~~Model 204~~</var>~~ Installation Guide for your operating system.</p>		The Encoding/Decoding facility uses the translation tables contained in the distributed CDTB module. The <var>$Code</var> and <var>$Decode</var> functions access the translation tables to allow the use of both coded and string values of fields. The contents of the translation tables can be listed by using the procedures listed in the Rocket [[Model 204 installation\|Model 204 Installation Guide]] for your operating system.</p>
	<p>		<p>
	You can store messages and return codes for user-written functions in the MSGU module. </p>		You can store messages and return codes for user-written functions in the MSGU module. </p>
Line 11:		Line 11:
	If you are migrating to 31-bit or multiprocessing environments, review the conversion considerations summarized in [[#Converting user-written functions\|Converting user-written functions]]. </p>		If you are migrating to 31-bit or multiprocessing environments, review the conversion considerations summarized in [[#Converting user-written functions\|Converting user-written functions]]. </p>
	<p>		<p>
	For general directions on assembly and link-editing, see the Rocket ~~<var class="product">~~Model 204~~</var>~~ Installation Guide for your operating system. </p>		For general directions on assembly and link-editing, see the Rocket [[Model 204 installation\|Model 204 Installation Guide]] for your operating system. </p>

	==Adding functions to the FUNU module==		==Adding functions to the FUNU module==
Line 384:		Line 384:
	===Customizing the sample translation tables===		===Customizing the sample translation tables===
	<p>		<p>
	To modify the distributed sample translation tables (refer also to the Rocket ~~<var class="product">~~Model 204~~</var>~~ Installation Guide for your operating system): </p>		To modify the distributed sample translation tables (refer also to the Rocket [[Model 204 installation\|Model 204 Installation Guide]] for your operating system): </p>
	<ol>		<ol>
	<li>List CDTB with its sequence numbers.</li>		<li>List CDTB with its sequence numbers.</li>
Line 397:		Line 397:
	===Modifying translation tables===		===Modifying translation tables===
	<p>		<p>
	To make additions, deletions, or changes to translation tables (refer also to the Rocket ~~<var class="product">~~Model 204~~</var>~~ Installation Guide for your operating system): </p>		To make additions, deletions, or changes to translation tables (refer also to the Rocket [[Model 204 installation\|Model 204 Installation Guide]] for your operating system): </p>
	<ol>		<ol>
	<li>Modify the source code.</li>		<li>Modify the source code.</li>