START POOL - Teradata Director Program

Teradata® Director Program Reference

Product
Teradata Director Program
Release Number
17.10
Published
October 2021
Language
English (United States)
Last Update
2021-11-02
dita:mapPath
bvb1608578422774.ditamap
dita:ditavalPath
obe1474387269547.ditaval
dita:id
B035-2416
Product Category
Teradata Tools and Utilities

Purpose

Establishes and enables a session pool.

A session pool is not used if the session requests any CLIv2 DBCAREA Workload specification, or if the Utility-workload, the Statement-status=D, or the Extended-load options are specified.

Session pools are not supported for utilities such as FastLoad, MultiLoad, Archive/Recovery, and FastExport. Because utility programs use special internal run strings, they do not work with session pools.

Syntax



where:

filename
z/OS data set file, defined in the TDP startup procedure, that contains START POOL commands.
If specified, it must be the only argument specified by the command.
number
Number of sessions that are to be established for the pool.
This is a required argument unless DDNAME is specified.
The deprecated specification FILE is equivalent to DDNAME.
Number can be no larger than the maximum number of sessions (MAXSESS) that has been set by the installation, or the session capacity of the database
jobname
Indication that the pool is restricted to a job named jobname. (You can establish several pools with the same logon string, but with different job names.)
runstring
Optional run string argument that is used when establishing pool sessions.
The default is DBC/SQL. TEQUEL can also be specified.
poolid
Optional, unique identifier of up to eight alphanumeric characters that identifies the pool.
If omitted, TDP assigns the pool an identifier in the form POOLnnnn, where nnnn is an ascending number, beginning with 1.
character_set_name
Character set name with a maximum of 30 characters, to be used in this pool for logons. Choose from the following, having EBCDIC characteristics:
  • EBCDIC
  • EBCDIC037_0E
  • EBCDIC273_0E
  • EBCDIC277_0E
  • HANGULEBCDIC933_1II
  • KANJIEBCDIC5026_0I
  • KANJIEBCDIC5035_0I
  • KATAKANAEBCDIC
  • SCHEBCDIC935_2IJ
  • TCHEBCDIC937_3IB
Or one of the following, having ASCII characteristics:
  • ARABIC1256_6A0
  • ASCII
  • CYRILLIC1251_2A0
  • HANGUL949_7R0
  • HANGULKSC5601_2R4
  • HEBREW1255_5A0
  • KANJIEUC_0U
  • KANJISJIS_0S
  • LATIN1_0A
  • LATIN1250_1A0
  • LATIN1252_0A
  • LATIN1252_3A0
  • LATIN1254_7A0
  • LATIN1258_8A0
  • LATIN9_0A
  • SCHGB2312_1T0
  • SCHINESE936_6R0
  • TCHBIG5_1R0
  • TCHINESE950_8R0
  • THAI874_4A0
  • UTF8

Or UTF16

Or any user-defined character set established using the TDP SET USERCS command.
Although other names can be specified, their characteristics (the codepoint for the space, comma, apostrophe, and quotation symbols; the codepoints for control characters; the encoding scheme, and the rules for monocasing) are assumed to be as for EBCDIC.
This character set also defines the characters that can be used in the logon string of the LOGON operand. If omitted, the default TDP character set is used to process this logon string.
Since the character set must be known prior to the interpretation of the LOGON value, if CHARSET is needed it should precede LOGON to ensure proper parsing. If CHARSET for other than the TDP default character set follows LOGON, the command is not rejected but a TDP2712 warning message is issued since the logon string can not be properly interpreted, depending on the characteristics of the character set.
NULLPSWD
Optional password in the logon string (specified by the LOGON option).
This keyword enables the use of session pools for which TDP has authenticated the database system userid.
The deprecated specification NULLPWD is equivalent to NULLPSWD.
session_attributes
List of available attributes for all sessions for this pool, as described below.
If the database does not support a specified attribute, the pool does not start. If an attribute is not specified, but the database has been configured with a default attribute, the default is used.
  • TWOPC – Causes TDP to establish all sessions in the pool as Two-phase commit sessions.
  • TERADATA – Indicates that Teradata transaction semantics are to be used.

    This keyword is mutually exclusive with the ANSI keyword.

  • ANSI – Indicates that ANSI transaction semantics are to be used.

    This keyword is mutually exclusive with the TERADATA keyword.

  • DATEFORM – Indicates how dates are processed by the database. DATEFORM values are:
    • ANSI – Indicates that ANSI date format is to be used.
    • TERADATA – Indicates that Teradata date format is to be used.
    • DEFAULT – Indicates that the database uses the default date format associated with the user/database. Since TDP does not know which format the database uses when DEFAULT is specified, only sessions that also specify (or default to) DEFAULT will use the pool.

    If DATEFORM is omitted, DATEFORM DEFAULT is assumed.

  • SQL2 – Generates a warning when SQL not conforming with to the FIPS 127-2 language standard is used.

    This keyword is mutually exclusive with the SQL3 keyword.

  • SQL3 – Generates a warning when SQL not conforming with to the FIPS 127-3 language standard is used.

    This keyword is mutually exclusive with the SQL2 keyword.

  • STMTSTAT – Indicates that StatementStatus response parcels may be returned instead of Success, OK, Error, Failure, ErrorInformation, and StatementError parcels. But specifying STMTSTAT does not guarantee that StatementStatus parcels are returned; it only permits them. Receipt of a StatementStatus parcel for one request does not guarantee that the other parcels will not be returned for other requests. There are two deprecated values for STMTSTAT that may be present for compatibility, but should not be specified otherwise:
    • ORIGINAL is equivalent to not specifying STMTSTAT.
    • ENHANCED is equivalent to specifying STMTSTAT without ENHANCED.
username ,password ,‘acctid’
The logon string to be used to log the pool sessions on to the database.
The password is optional if the NULLPSWD option is also specified.
This argument is required unless DDNAME is specified.
The userid, password, and account name each consist of characters from the current TDP character set (SET CHARSET). When supported by the current character set, EBCDIC double-byte characters can be included by preceding each contiguous group of them with the Shift-out control character, X’0E’, and following this group with the Shift-in control character, X’0F’. Neither commas, apostrophes, nor quotation marks can be specified as double-byte characters.
The database processes the logon string characters left to right, even for character sets normally associated with right to left languages such as Hebrew or Arabic.
If the TDP default character set is not appropriate for the logon string, the proper character set must be specified by the CHARSET operand. If CHARSET for other than the TDP default character set follows LOGON, the command is not rejected but a TDP2712 warning message is issued since the logon string might not be properly interpreted, depending on the characteristics of the character set.
The deprecated specification STRING is equivalent to LOGON.
While the database permits spaces outside apostrophes before a comma in the logon string, they might not be present since such spaces in TDP command syntax are delimiters and indicate the end of the logon string. However, the presence of such spaces in the logon string are ignored when comparing it to this logon string.

Usage Notes

A START POOL command is not processed by TDP until at least one START CP or START NP command and the RUN command have been processed (that is, until at least one CP or NP has been started). Thus, if a START POOL command occurs in the TDP startup data set (TDPPARM) before either of these commands, the START POOL command is not processed until a CP or NP is attached and started.

A START POOL command might not be processed for one of the following reasons:
  • The command contains syntax errors.
  • A pool having the same logon string (and jobname, if appropriate) already exists.
  • Logons are disabled.
  • The poolid argument of the command is not unique.

When a character set that is not valid is specified, the following message displays:

TDP2711 THE "CHARSET" VALUE IS NOT SUPPORTED

A START POOL command is rejected if a pool already exists with the same logon string JOB specification and session attributes (TWOPC, ANSI/TERADATA, DATEFORM, SQL2/SQL3, STMTSTAT).

JOB Specification and Session Attributes

The JOB jobname and session attributes restriction is used to reserve pool sessions only for application logon requests that are associated with the specified job and session attributes. If a request matches the restriction of an established pool and the pool has no sessions available (not in use) to satisfy the request, the request is rejected. This is true even if an unrestricted pool (that is, one with no restriction) exists with the same logon string.

Any logon request that has the same logon string as an unrestricted pool can use sessions from the pool, regardless of the job or address space of the application (provided, of course, that a restricted pool for that job does not also exist).

To be considered a match, the logon string of the application must be identical to the logon string of the pool. Specification of NULLPSWD does not affect comparison of the logon strings.

The TDP ENABLE POOL STATUS and ENABLE POOL DETAIL commands may be used to request messages when a session cannot be satisfied from a session pool.

If the user password is changed for a userid being used in a session pool, the userid can log on to the database with the old password while the session pool is active.

Use of DDNAME Option

It might be necessary to use the DDNAME filename specification of the START POOL command and include the command in a data set (under z/OS) that is accessed during TDP startup in the following situations:

  • When a START POOL command exceeds the maximum length (128 characters) allowed for a console command. Because a logon string can contain up to 278 bytes, including commas, apostrophes, and quotation marks (a maximum of 92 bytes for each specification—username, password, account identifier), it is possible that the START POOL command can exceed 128 characters.
  • When it is necessary to protect the security of a password that is used in the logon string of a START POOL command.

TDP supports sequential files with fixed or varying length unspanned record formats and any logical record length supported by the device/operating system. If the records are fixed 80byte records, columns 73 through 80 are reserved for traditional sequence numbers and are ignored; otherwise, the entire record is used. Records containing only blanks are ignored. If the first non-blank characters of a record are /*, the record is considered a comment and ignored. Commands can be continued onto multiple records using continuation characters. If the last non-blank character is a minus sign, the minus sign is discarded and the command continues with the first column of the next record. If the last non-blank character is a plus sign, the plus sign is discarded and the command continues with the first non-blank column of the next record. A command can be continued onto any number of records.

While all characters for all records are normally EBCDIC, the value of the LOGON option can be in another character set. Care must be taken to ensure that the final byte of the logon string appearing at the end of a command is not a value that could be taken as an EBCDIC continuation character when no continuation is intended. To prevent this, a semicolon can be added to the end of any command. The semicolon is discarded before the command is processed.

NULLPSWD indicates that the database can process logon requests for the sessions even if they do not supply a password. This requires that the userid be GRANTed WITH NULL PASSWORD authority to the database. See Teradata Vantage™ - Advanced SQL Engine Security Administration, B035-1100. The DBC userid always requires a password so NULLPSWD is effectively ignored for this userid.

Use of NULLPSWD Option

Understand that using NULLPSWD in conjunction with GRANTing WITH NULL PASSWORD allows unrestricted access to that userid unless a TDPUAX or TDPLGUX exit is provided to control use of this userid by other means that a password. If exits are used to provide such control, should they be disabled, either explicitly by the DISABLE command, or implicitly as a result of TDPLGUX ABENDing, access is unrestricted.

Completion Messages

When the START POOL command is accepted for processing by TDP, the following message is displayed:

TDP0866 ADDING number SESSIONS TO POOL ID: poolid

When the START POOL command has been processed, the following message is displayed:

TDP 0881 POOL ID: poolid IS NOW ENABLED

Example START POOL Commands

The following example demonstrates how to set up session pools to be used by an application. In this example, nine session pools are established for Accounts Receivable, Accounts Payable, and Finance. These pools are accessed only through transactions from JOB CICS.

Under z/OS, the following DD statements are added to the startup JCL for TDP:

//TDPPARM   DD DSN=DBC.TDPPARM,DISP=SHR
//ACCTREC   DD DSN=DBC.ACCTREC,DISP=SHR
//ACCTPAY   DD DSN=DBC.ACCTPAY(POOLPARM),DISP=SHR
//FINANCE   DD DSN=DBC.FINANCE(POOLPARM),DISP=SHR

The <dbcpfx>.TDPPARM data set and the TDPn TDPCMD fm file contain the following commands:

ENABLE LOGONS
START CP6B0
START CP6B2
START POOL DDNAME ACCTREC
START POOL DDNAME ACCTPAY
START POOL DDNAME FINANCE
RUN 

These commands are all echoed to the operator console. The commands contained in the data sets or files that are identified by the ddnames or FILEDEFs referenced by the START POOL commands are not echoed to the system console.

The contents of ACCTREC (data set or file) are:

START POOL NUM 15 JOB CICS LOGON AR,MONEYIN
START POOL NUM 25 JOB CICS LOGON AR,MONEYIN,’ACCT1’
START POOL NUM 40 JOB CICS -
  LOGON AR,MONEYIN,’ACCT2’ 

The contents of ACCTPAY (data set or file) are:

START POOL NUM 20 JOB CICS LOGON AP,MONEYOUT,’ACCT1’
START POOL NUM 30 JOB CICS -
  LOGON AP,MONEYOUT,’ACCT2’
START POOL NUM  5 JOB CICS LOGON AP,MONEYOUT,’ACCT3’ 

The contents of FINANCE (data set or file) are:

START POOL NUM 2 JOB CICS LOGON FIN,SPENDIT,’DEPT1’
START POOL NUM 1 JOB CICS LOGON FIN,SPENDIT,’DEPT2’
START POOL NUM 3 JOB CICS LOGON FIN,SPENDIT,’DEPT3’ 

Note that these session pools are established only after CP6B0 and CP6B2 are started.