View source for Model 204 environment for UL/DB2

==Overview==
<p>
The UL/DB2 Interface is supported in the Online and BATCH204 environments.</p>
<p>
An Online is a multiuser program that runs in its own address space. Each Online is a separate entity, requiring its own system files, buffers, control tables, and servers.</p>
<p>
BATCH204 is a single-user Model 204 job; therefore there are no terminal interfaces. Input is only possible from the User 0 input stream. BATCH204 requires its own system files, buffers, control tables, and servers.</p>

==Preparing a Model 204 environment==
<p>
To prepare a Model 204 environment to support UL/DB2, you must:</p>
<ol>
<li>
Set the User 0 parameters.
<li>
Define the LINK, PROCESSGROUP, and PROCESS.</li>
<li>
Open the link.</li>
</ol>
<p>
These tasks are described in the following sections.</p>

==Setting the UL/DB2 User 0 parameters==
<p>
Model 204 uses User 0 parameters to configure its address space (Online or BATCH204). User 0 parameters are specified in the input stream of the job invoking Model 204.</p>
<p>
UL/DB2 has two required and two optional User 0 parameters. </p>
<p>
The required UL/DB2 User 0 parameters are:</p>
<ul>
<li>
DB2THRD</li>
<li>
DB2PLAN</li>
</ul>
<p>
You must explicitly set a value for both DB2THRD and DB2PLAN.</p>
<p>
The optional UL/DB2 User 0 parameters are:</p>
<ul>
<li>
DB2QUOTE, which has a default of an apostrophe (')</li>
<li>
DB2POINT, which has a default of a decimal point (.)</li>
</ul>
<p>
You can set a value for either or both DB2QUOTE and DB2POINT. If you do not set a value for either DB2QUOTE or DB2POINT, each parameter assumes its default value.</p>

===Setting the XMEMOPT and XMEMSVC parameters===
<p>
If your site uses the ACF2 external security package and you want to take advantage of operating system Cross-Memory Services, you must set two additional User 0 parameters, <var>[[XMEMOPT parameter|XMEMOPT]]</var> and <var>[[XMEMSVC parameter|XMEMSVC]]</var>. See [[#Security processing|Security processing]] for more information about setting these parameters.</p>

===Setting the SPCORE parameter===
<p>
Each UL/DB2 user requires 1300 bytes of <var>[[SPCORE parameter|SPCORE]]</var>.</p>

===Setting User 0 parameters in the CCAIN input stream===
<p>
You set the UL/DB2 User 0 parameters on the first line of the CCAIN input stream. The User 0 parameter line is the first line of the CCAIN input data set, after any DEFINE commands, in a Batch or Online system.</p>
<p>
The following example shows the positioning of the User 0 parameter line within the CCAIN input stream:</p>
<p class="syntax"> //CCAIN DD *
 *  <span class="term">User 0 parameters</span>
 .
 .
 .</p>
<p>
For more information on setting User 0 parameters, see the following wiki topics:</p>

<p>[[Defining the runtime environment (CCAIN)#User 0 parameters|User 0 parameters]]</p>
<p>[[Overview of Model 204 parameters]]</p>
<p>[[Overview of Model 204 commands]]</p>

====RESET command not supported====
<p>
You cannot use the RESET command to reset the UL/DB2 User 0 parameters. You can set them only on the User 0 parameter line in the CCAIN input stream.</p>

====VIEW command supported====
<p>
You can use the VIEW command during an Online run to display the current User 0 parameter settings. See the Rocket Model 204 Commands wiki pages for more information.</p>

===DB2THRD parameter===
<p>
The DB2THRD parameter specifies the number of DB2 threads (TCBs) to allocate for a Model 204 run. </p>

====Syntax====
<p class="syntax">DB2THRD=<var class="term">nnnnn</var></p>
<p>
where:</p>
<p>
<var class="term">nnnnn</var> is a number that specifies the maximum number of DB2 threads to allocate for a Model 204 run. The number that is best for your site depends on the types of transactions that you process. If you typically perform complex tasks, you might want to allocate a thread for each user. If you typically perform simple tasks, you might want to allocate one thread for every ten users.</p>
<p class="note"><b>Note:</b> If the value of DB2THRD is greater than the value of the NUSERS parameter, Model 204 resets the value of DB2THRD to the value of NUSERS and writes an error message in the job log.</p>

===DB2PLAN parameter===
<p>
The DB2PLAN parameter indicates the PLAN name created by the DBRM BIND. </p>

====Syntax====
<p class="syntax">DB2PLAN=<span class="term">name</span>
</p>
<p>
where:</p>
<p>
<var class="term">name</var> is the PLAN name created by the DBRM BIND. For more information on the PLAN name, see [[#Granting PLAN and table privileges|Granting PLAN and table privileges]].</p>

===DB2QUOTE parameter===

<p class="note"><b>Note:</b> The DB2QUOTE parameter depends on the systemwide definitions made by your DB2 DBA. Consult with your DBA before setting this parameter.</p>
<p>
DB2QUOTE is an optional parameter that specifies the symbol to be used as the DB2 string delimiter. DB2QUOTE has a default value of an apostrophe ('). </p>

====Syntax====
<p class="syntax">DB2QUOTE=<span class="term">symbol</span>
</p>
<p>where:</p>
<p>
<var class="term">symbol</var> is the character to be used as the DB2 string delimiter.</p>
<p>
For more information on the DB2 string delimiter, see the <var class="book">IBM DATABASE 2 Installation Guide</var>.</p>

===DB2POINT parameter===

<p class="note"><b>Note:</b> The DB2POINT parameter depends on the systemwide definitions made by your DB2 DBA. Consult with your DBA before setting this parameter.</p>
<p>
DB2POINT is an optional parameter that specifies the symbol to be used as the decimal point. DB2POINT has a default value of period (.).</p>

====Syntax====
<p class="syntax">DB2POINT=<span class="term">symbol</span>
</p>
<p>where:
</p>
<p>
<var class="term">symbol</var> is the character to be used as the DB2 decimal point. </p>
<p>
For more information on the DB2 decimal point, see the <var class="book">IBM DATABASE 2 Installation Guide</var>.</p>

==Defining the LINK, PROCESSGROUP, and PROCESS==
<p>
The following DEFINE commands are required for UL/DB2. The DEFINE commands identify the entities that underlie UL/DB2.</p>
<p>
These commands are fully documented in the Rocket Model 204 Commands wiki pages:</p>
<ul>
<li>
[[DEFINE LINK command: UL/DB2]]</li>
<li>
[[DEFINE PROCESSGROUP command: UL/DB2]]</li>
<li>
[[DEFINE PROCESS command: User Language to DB2]]</li>
</ul>

===Guidelines for using the DEFINE commands===
<p>
The following guidelines apply when using the DEFINE commands:</p>
<ul>
<li>
User 0 or system manager privileges are required.</li>
<li>
Typically, you place the DEFINE commands in the User 0 stream in the CCAIN input file. This placement allows the entities to be defined when Model 204 starts.

<p>Alternatively, you can place the DEFINE commands inside a Model 204 procedure that is invoked within the User 0 stream. This allows you to set up or change the definitions without restarting Model 204.</p></li>
<li>
You can specify the DEFINE commands in any order.</li>
</ul>

==Controlling links==
<p>You use the following commands to control links between Model 204 and DB2:</p>

<ul>
<li>
The <var>[[OPEN LINK command|OPEN LINK]]</var> command enables the link specified in the <var>[[DEFINE LINK command: UL/DB2|DEFINE LINK]]</var> command. It is required to establish the connection between Model 204 and DB2.</li>
<li>
The <var>[[CLOSE LINK: TPROCESS, Transfer Control link, or UL/DB2|CLOSE LINK]]</var> command disables an open link to prohibit users from accessing DB2 after initialization has completed.</li>
<li>
The <var>[[STOP command: Stopping a Horizon or Model 204 SQL link or processgroup|STOP LINK]]</var> command sets the link entity in a drain state. That is, no new users are allowed to access DB2, and current users can continue until they end the connection normally.</li>
</ul>

===Placing the LINK commands===
<p>You can place these commands in the User 0 stream, within a User Language procedure, or you can issue them at the command level. </p>

===Required privileges===
<p>To issue these commands, you must have User 0, system manager, or system administrator privileges.</p>

==Security processing==
<p>
To use DB2 resources, a Model 204 user must be authorized to access the DB2 subsystem and, once that connection has been established, to access specific DB2 resources. This section describes how DB2 determines if a Model 204 user has access authorization, both with and without an external security package installed.</p>
<p>
To access the DB2 subsystem, Model 204 supplies a primary authorization ID to DB2 at connection time. How this processing is done depends on whether an external security package is in place. </p>

===No external security in place===
<p>
If there is no external security system, DB2 uses the USER parameter on the JOB statement as the primary authorization identifier. If there is no USER parameter, the primary authorization ID is set to the default authorization ID, which was set when DB2 was installed (UNKNOWN AUTHID on install panel DSNTIPP).</p>

===External security in place===
<p>
An external security system can be used to validate DB2 requests.</p>
<p>
To fully use an external security subsystem to validate the DB2 requests, one of the Model 204 security interfaces must be installed and the Model 204 load member must be in an APF-authorized load library. If the load library is not authorized, then DB2 validates the request as if there were no external security system in place. See [[#No external security in place|No external security in place]].</p>

====Taking advantage of operating system Cross-Memory Services====
<p>
If you have an external security subsystem installed and are running Model&nbsp;204 from an authorized library, then you can take advantage of operating system Cross-Memory Services. To do so, you must:</p>
<ul>
<li>Have the Model&nbsp;204 [[Cross-memory facilities CRAM and M204XSVC|M204XSVC]] module linked ([[Model 204 installation on IBM z/OS#xsvc|the default as of version 7.5]]); sites running Model&nbsp;204 7.5 or earlier might have M204XSVC installed as an SVC ([[Release notes for Model 204 version 7.6#M204XSVC as an SVC|which requires zap maintenance]]). </li>

<li>Set two User 0 parameters to ensure that a Model&nbsp;204 run uses cross-memory. These User 0 parameters are <var>[[XMEMOPT parameter|XMEMOPT]]</var> and <var>[[XMEMSVC parameter|XMEMSVC]]</var>.
<ul>
<li>Set <var>XMEMOPT</var> to X'04' to force Model&nbsp;204 to initialize the Cross-Memory environment. 
<p>
If <var>XMEMOPT</var> was already set for another Model&nbsp;204 feature, you do not need to set it again.</p></li>

<li>If M204XSVC is installed as an SVC, set <var>XMEMSVC</var> to the SVC number used when M204XSVC was installed.</li>
</ul>
</ul>

====Authorization exit DSN3@ATH====
<p>
The authorization exit DSN3@ATH is provided by DB2 for security checking during CONNECT processing. The exit as distributed checks for security subsystem installation, and it uses the security subsystem to validate the primary authorization ID and acquire any secondary authorization ID. CA-ACF2 replaces this exit with one of their own, which does identical work, albeit by calling on ACF2 functions.</p>
<p>
As part of UL/DB2, Rocket Software distributes its own version of the DSN3@ATH authorization exit. You must install this Model 204-supplied authorization exit, which is stored in the MACLIB as ACF3SATH, over the existing DSN3@ATH. Refer to Chapter 3 of the <var class="book">DATABASE 2 Administration Guide, Volume 1</var> for instructions on installing the Model&nbsp;204-distributed DSN3@ATH over the existing copy.</p>

<p class="note"><b>Note: </b>If you have modified the existing DSN3@ATH, you must make the same modifications to the Model&nbsp;204 DSN3@ATH authorization exit.</p>
<p>
When this exit is invoked, the active TCB is checked to see if it is a Model 204 subtask. If this TCB is recognizable as Model 204's, the Model&nbsp;204 user ID is used as the DB2 primary authorization ID (AIDLPRIM) and the default SQL ID.</p>
<p>
The authorization exit is driven at connection time, that is, during the Call Attach Facility CONNECT call. CONNECT processing is expensive, so user switching requires careful consideration. A user procedure acquires a subtask TCB at the first EXEC DB2 request and keeps it until the procedure finishes. A long-running procedure can effectively remove the TCB from the pool of available TCBs.</p>

==Granting PLAN and table privileges==
<p>
To execute a program containing SQL statements, a Model&nbsp;204 user must have execution privileges on the PLAN that was created by the BIND. The DB2 DBA can grant privileges to individual user IDs, can make the PLAN public, or do whatever is standard at the site. Also, to access specific DB2 tables, the Model&nbsp;204 user must have appropriate table privileges for that table. Again, the DB2 DBA grants table privileges to users.</p>

==Using the BUMP command with UL/DB2==
<p>
You can use the Model 204 <var>[[BUMP command|BUMP]]</var> command to terminate a UL/DB2 user.</p>
<p>
Depending on the state of that user, however, the BUMP command might have to wait to complete processing. A procedure that is accessing DB2 runs under the subtask's TCB. Model&nbsp;204 considers that user to be in a swappable WAIT state. When you issue a BUMP against such a user, UL/DB2 waits until the user is swapped in and active before executing the BUMP. The user is then restarted, which frees the subtask TCB.</p>

==Using the MONITOR command with UL/DB2==
<p>
Use the <var>[[MONITOR command|MONITOR]]</var> command to see the current usage of a Model&nbsp;204 link, processgroup, or process.</p>

====Syntax====
<p class="syntax">MONITOR {LINK | PROCESSGROUP | PROCESS} <span class="term">entityname</span> [[EVERY] <var class="term">n</var>]
</p>
<p>Where:</p>
<p>
<var class="term">entityname</var> is the name specified on the <var>DEFINE LINK</var>, <var>DEFINE PROCESSGROUP</var>, or <var>DEFINE PROCESS</var> command.</p>
<p>
<var class="term">n</var> is the number of seconds Model&nbsp;204 waits after completing a display before beginning the next display.</p>

====Output====
<p>
The output of the <var>MONITOR</var> command for UL/DB2 is a single line that contains the items listed in the following table.</p>
<table class="thJustBold">
<caption>MONITOR command output</caption>
<tr class="head">
<th>Term</th>
<th>Meaning</th>
</tr>

<tr><th>LOCAL ID</th>
<td>Blank (no meaning)</td></tr>

<tr><th>MAXSES</th>
<td>Maximum number of threads allowed. The value of the <var>[[DB2THRD parameter|DB2THRD]]</var> parameter.</td></tr>

<tr><th>BNDSES</th>
<td>Number of threads currently in use. (Threads that are in use or on the chain.)</td></tr>

<tr>
<th>CONVS</th>
<td>Threads currently active to DB2. (WAIT type 32. Model&nbsp;204 WAIT, the thread is talking to DB2.)</td>
</tr>

<tr><th>FLGS</th>
<td>Link status flags: <br />
A -- Active <br />
S -- Stopped <br />
C -- Being closed</td></tr>

<tr>
<th>TRAN</th>
<td>Type of transport:<br />
LOCL -- Local</td>
</tr>

<tr>
<th>PROTO</th>
<td>Type of communication protocol:<br />
CAF -- Call Attach Facility</td>
</tr>
</table>

==See also==
{{Template:UL/DB2 topic list}}

[[Category:UL/DB2]]