Model 204 environment for UL/DB2

Overview

The UL/DB2 Interface is supported in the Online and BATCH204 environments.

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.

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.

Preparing a Model 204 environment

To prepare a Model 204 environment to support UL/DB2, you must:

1. Set the User 0 parameters.
2. Define the LINK, PROCESSGROUP, and PROCESS.
3. Open the link.

These tasks are described in the following sections.

Setting the UL/DB2 User 0 parameters

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.

UL/DB2 has two required and two optional User 0 parameters.

The required UL/DB2 User 0 parameters are:

• DB2THRD
• DB2PLAN

You must explicitly set a value for both DB2THRD and DB2PLAN.

The optional UL/DB2 User 0 parameters are:

• DB2QUOTE, which has a default of an apostrophe (')
• DB2POINT, which has a default of a decimal point (.)

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.

Setting the XMEMOPT and XMEMSVC parameters

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, XMEMOPT and XMEMSVC. See Security processing for more information about setting these parameters.

Setting the SPCORE parameter

Each UL/DB2 user requires 1300 bytes of SPCORE.

Setting User 0 parameters in the CCAIN input stream

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.

The following example shows the positioning of the User 0 parameter line within the CCAIN input stream:

//CCAIN DD * * User 0 parameters . . .

For more information on setting User 0 parameters, see the following wiki topics:

User 0 parameters

Overview of Model 204 parameters

Overview of Model 204 commands

RESET command not supported

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.

VIEW command supported

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.

DB2THRD parameter

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

Syntax

DB2THRD=nnnnn

where:

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

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

DB2PLAN parameter

The DB2PLAN parameter indicates the PLAN name created by the DBRM BIND.

Syntax

DB2PLAN=name

where:

name is the PLAN name created by the DBRM BIND. For more information on the PLAN name, see Granting PLAN and table privileges.

DB2QUOTE parameter

Note: The DB2QUOTE parameter depends on the systemwide definitions made by your DB2 DBA. Consult with your DBA before setting this parameter.

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 (').

Syntax

DB2QUOTE=symbol

where:

symbol is the character to be used as the DB2 string delimiter.

For more information on the DB2 string delimiter, see the IBM DATABASE 2 Installation Guide.

DB2POINT parameter

Note: The DB2POINT parameter depends on the systemwide definitions made by your DB2 DBA. Consult with your DBA before setting this parameter.

DB2POINT is an optional parameter that specifies the symbol to be used as the decimal point. DB2POINT has a default value of period (.).

Syntax

DB2POINT=symbol

where:

symbol is the character to be used as the DB2 decimal point.

For more information on the DB2 decimal point, see the IBM DATABASE 2 Installation Guide.

Defining the LINK, PROCESSGROUP, and PROCESS

The following DEFINE commands are required for UL/DB2. The DEFINE commands identify the entities that underlie UL/DB2.

These commands are fully documented in the Rocket Model 204 Commands wiki pages:

• DEFINE LINK command: UL/DB2
• DEFINE PROCESSGROUP command: UL/DB2
• DEFINE PROCESS command: User Language to DB2

Guidelines for using the DEFINE commands

The following guidelines apply when using the DEFINE commands:

• User zero or system manager privileges are required.
• 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.

  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.

• You can specify the DEFINE commands in any order.

Controlling links

You use the following commands to control links between Model 204 and DB2:

• The OPEN LINK command enables the link specified in the DEFINE LINK command. It is required to establish the connection between Model 204 and DB2.
• The CLOSE LINK command disables an open link to prohibit users from accessing DB2 after initialization has completed.
• The STOP LINK 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.

Placing the LINK commands

You can place these commands in the User 0 stream, within a User Language procedure, or you can issue them at the command level.

Required privileges

To issue these commands, you must have User 0, system manager, or system administrator privileges.

Security processing

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.

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.

No external security in place

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

External security in place

An external security system can be used to validate DB2 requests.

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.

Taking advantage of operating system Cross-Memory Services

If you have an external security subsystem installed and are running Model 204 from an authorized library, then you can take advantage of operating system Cross-Memory Services. To do so, you must:

• Have Cross-Memory SVC installed. See the Rocket Model 204 installation documentation for IBM z/OS for information on installing M204XSVC.
• Set two User 0 parameters to ensure that a Model 204 run uses cross-memory. These User 0 parameters are XMEMOPT and XMEMSVC.
  • Set XMEMOPT to X'04' to force Model 204 to initialize the Cross-Memory environment.
  • Set XMEMSVC to the SVC number used when M204XSVC was installed.

  Note: If XMEMOPT was already set for another Model 204 feature, you do not need to set it again.

Authorization exit DSN3@ATH

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.

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 DATABASE 2 Administration Guide, Volume 1 for instructions on installing the Model 204-distributed DSN3@ATH over the existing copy.

Note: If you have modified the existing DSN3@ATH, you must make the same modifications to the Model 204 DSN3@ATH authorization exit.

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 204 user ID is used as the DB2 primary authorization ID (AIDLPRIM) and the default SQL ID.

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.

Granting PLAN and table privileges

To execute a program containing SQL statements, a Model 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 204 user must have appropriate table privileges for that table. Again, the DB2 DBA grants table privileges to users.

Using the BUMP command with UL/DB2

You can use the Model 204 BUMP command to terminate a UL/DB2 user.

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

Using the MONITOR command with UL/DB2

Use the MONITOR command to see the current usage of a Model 204 link, processgroup, or process.

Syntax

MONITOR {LINK | PROCESSGROUP | PROCESS} entityname [[EVERY] n]

Where:

entityname is the name specified on the DEFINE LINK, DEFINE PROCESSGROUP, or DEFINE PROCESS command.

n is the number of seconds Model 204 waits after completing a display before beginning the next display.

Output

The output of the MONITOR command for UL/DB2 is a single line that contains the items listed in the following table.

MONITOR command output

Term	Meaning
LOCAL ID	Blank (no meaning)
MAXSES	Maximum number of threads allowed. The value of the DB2THRD parameter.
BNDSES	Number of threads currently in use. (Threads that are in use or on the chain.)
CONVS	Threads currently active to DB2. (WAIT type 32. Model 204 WAIT, the thread is talking to DB2.)
FLGS	Link status flags: A -- Active S -- Stopped C -- Being closed
TRAN	Type of transport: LOCL -- Local
PROTO	Type of communication protocol: CAF -- Call Attach Facility

See also

• UL/DB2
• Model 204 environment for UL/DB2
• UL/DB2 and SQL statements
• UL/DB2 error codes and messages
• UL/DB2 request example
• UL/DB2 internals