15.10 - Query Environment Parameters (QEP) - Call-Level Interface Version 2

Teradata Call-Level Interface Version 2 Reference for Mainframe-Attached Systems

prodname
Call-Level Interface Version 2
vrm_release
15.10
category
Programming Reference
featnum
B035-2417-035K

The following table defines the DBCHQEP area. All fields are set by the application with the exception of QEPRDLEN, which is set by CLIv2. The field names in all languages are the same, except that the C field names are case-sensitive. They appear in the following table in upper and lower case immediately below the field names in Assembler, COBOL and PL/I.

A mnemonic is provided for QEPLEVEL. The name is the same for all languages, including C, and is QEPLVLC.

 

Field Name

Offset

Length

Description

QEPLEVEL

(qepLevel)

00

1

Unsigned numeric format of the parameter list.

Must be set to 4.

QEPITEM

(qepItem)

01

1

Unsigned numeric item to be queried.

Valid item codes and their descriptions are listed in the table following this table.

QEPTLEN

(qepTLen)

02

2

Unsigned numeric length of the TDP identifier addressed by QEPTIDP, if one is provided.

When a TDP identifier is required but a length of zero is specified, the default identifier in the HSHSPB is used.

QEPTIDP

(qepTIDP)

04

4

Pointer to an area containing the TDP identifier, if one is provided.

The full TDP identifier must be specified. One character abbreviations are valid only within a logon string.

If the TDP identifier is not specified, the syntax of the TDP identifier is described in.

QEPCONN

(qepConn)

04

4

Unsigned numeric CLIv2 connection number, if required.

QEPFILL1

08

3

Not used.

Must be set to 0.

QEPVRF

(varyingResultFmt for C; VARYINGRESULTFMT for COBOL; VARYING_RESULT_FMT for PL/I)

11

1

Varyingresultformat must be one of the following:

  • 0, the default, or just characters as an unsigned 1‑byte integer that specifies the format of variable-length character results, where 0 has a mnemonic of QEPVRFC (QER_varRsltFmtChar for C, CHAR for COBOL; QER_VAR_RSLT_FMT_CHAR for PL/I)
  • 2 for a 2-byte unsigned integer that contains the number of characters followed by the characters, where 2 has a mnemonic of QEPVRF2C (QER_varRsltFmtShIntChar for C, LEN9999CHAR for COBOL; QER_VAR_RSLT_FMT_VARCHAR for PL/I).
  • The use of QEPVRF2C increases the size of the result by two bytes. While the specification must always be valid, it has no effect for results that do not consist of a variable-length character string (currently only Databaseaccesspath).

    QEPRALEN

    (qepRALen)

    12

    2

    Unsigned numeric length of the area in which the result of the query is returned.

    QEPRDLEN

    (qepRDLen)

    14

    2

    Unsigned numeric length of the data returned.

    Set to the length of the data returned (up to the size of the area as specified by the QEPRALEN field).

    QEPRAP

    (qepRAP)

    16

    4

    Pointer to the area in which the result of the query is returned.

    The area pointed to is defined by CLIv2.

    QEPMLID

    (qepMLid)

    20

    2

    Characters specifying the language to be used for any CLIv2 error message associated with the request. When a language is commonly used in several countries the Country Id may be specified to select messages that are unique to that country.

     

     

     

    The Language Id is defined by the ISO 639 standard. The value is in EBCDIC, and both lower and upper case characters are permitted (lower case characters are permitted since ISO 639 favors them for the Language Id).

     

     

     

    If not specified, the default value provided in the HSHSPB is used. If no HSHSPB default exists, EN is assumed. Refer to “DBCHUEP” on page 231 for derails of each supported language.

     

     

     

    Note: The only language for which messages are distributed is United States English (Language Id of 'EN', optional Country Id of 'US'), although Teradata in the various countries or customers may provide additional languages.

     

     

     

    The mechanism by which the CLIv2 error messages may be defined in other languages is described in “Chapter 14 Message Definitions” on page 417.

     

     

     

    If a message must be returned but messages are not available in the specified language, then the message number with fixed message text of '(REQUIRED MESSAGE TABLE IS NOT AVAILABLE)' in United States English will be returned.

     

     

     

    For example, the message 'CLI0187 MISSING PARAMETER' would be presented as:

    CLI0187 (REQUIRED MESSAGE TABLE IS NOT AVAILABLE)

    QEPMCID

    (qepMCid)

    22

    2

    Characters specifying the country variant of the language to be used for any CLIv2 error message associated with the request. The value specifies a two character Country Id. Since the Country Id qualifies the language, Language Id must also be specified.

     

     

     

    When a language is commonly used in several countries, the Country Id may be used to select messages that are unique to a specific country.

     

     

     

    The Country Id is defined by the ISO 31661 standard. The value is in EBCDIC, and both lower and upper case characters are permitted (lower case characters are permitted to prevent confusion in remembering which ISO standard favors lower case).

     

     

     

    If not specified, the default value provided in the HSHSPB is used. If no HSHSPB default exists, US is assumed. Refer to “Country Id” on page 84 for details of supported countries.

     

     

     

    If a message must be returned but messages are not available in the specified language, then the message number with fixed message text of '(REQUIRED MESSAGE TABLE IS NOT AVAILABLE)' in United States English will be returned.

     

     

     

    For example, the message 'CLI0187 MISSING PARAMETER' would be presented as:

    CLI0187 (REQUIRED MESSAGE TABLE IS NOT AVAILABLE)

    QEPMSGCS

    (qepMsgCS)

    24

    4

    Pointer to a 30 byte area that contains the name of the character set to be used for messages. The value is in upper case EBCDIC.

     

     

     

    If not specified, the default value provided in the HSHSPB is used. If no HSHSPB default exists, EBCDIC is assumed.

     

     

     

    Refer to “Character Set Pointer” on page 78 for details on the supported character set names.

    QEPMSGP

    (qepMsgP)

    28

    4

    Pointer to an area into which any error message will be placed when a non-zero return code occurs.

     

     

     

    QEPMSGM specifies the length of the area pointed to by QEPMSGP. If an error occurred while building the message, QEPRMRC will contain a CLIv2 return code. When this code is not zero, the text of the message may or may not be usable, depending on the nature of the error.

     

     

     

    The character set used to construct the message is indicated by QEPMSGCS. If not specified, the default value provided in the HSHSPB is used. If no HSHSPB default exists, EBCDIC is assumed.

     

     

     

    When a zero return code is reflected, any text from a previous error is overwritten with spaces in the character set indicated by QEPMSGCS, and QEPRMLEN is zeroed.

    QEPMSGM

    (qepMsgM)

    32

    2

    Unsigned numeric length in bytes of the area pointed to by QEPMSGP. The value is equivalent to the maximum length of a message that can be returned in that area. If QEPMSGP is not specified, this value is ignored.

    QEPRMLEN

    (qepRMLen)

    34

    2

    Unsigned numeric length in bytes of the message returned in the area addressed by QEPMSGP. If QEPMSGP is not specified, this value is not returned.

    QEPRMRC

    (qepRMRC)

    36

    2

    Unsigned numeric CLIv2 return code for any error that occurred while constructing the message. If no error occurred, binary zeroes are returned.

    QEPRC

    (qepRC)

    38

    2

    Unsigned numeric CLIv2 return code that occurred while processing this DBCHQEP. If no error occurred, binary zeroes are returned.

    QEPTIDP8

    (qepTIdP8)

    40

    8

    Reserved, must be binary zeroes.

    QEPRAP8

    (qepRAP8)

    48

    8

    Reserved, must be binary zeroes.

    QEPMCSP8

    (qepMCSP8)

    56

    8

    Reserved, must be binary zeroes.

    QEPMSGP8

    (qepMsgP8)

    64

    8

    Reserved, must be binary zeroes.

    QEPRQST

    (qepRqst)

    72

    4

    Unsigned numeric CLIv2 request number, if required.

    QEPTOKEN

    (qepToken)

    76

    4

    Binary token, initially zero, thereafter as returned by the previous incomplete query Available‑character‑sets request