17.10 - Options - Call-Level Interface Version 2

Teradata® Call-Level Interface Version 2 Reference for Workstation-Attached Systems

Product
Call-Level Interface Version 2
Release Number
17.10
Release Date
October 2021
Content Type
Programming Reference
Publication ID
B035-2418-061K
Language
English (United States)

Purpose

Specifies which statement options are used when a request is sent to the database.

Usage Notes

The Options parcel is generated by CLIv2 at the direction of an application.

Parcel Data

The following information applies to the Options parcel.

Flavor Parcel Body Length Parcel Body Fields
85 10 to 18
  • RequestMode: 1 byte
  • Function: 1 byte
  • Select-data: 1 byte
  • Continued-characters-state: 1 byte
  • APH-response: 1 byte
  • Return-statement-info: 1 byte
  • UDTTransformsOff: 1byte
  • Maximum DECIMAL precision: 1 byte (ignored if Field Response-mode)
  • IdentityColumnRetrieval: 1 byte
  • DynamicResultSets: 1 byte
  • If present, SP-ReturnResult: 1 byte
  • If present, PeriodStructOn: 1 byte
  • If present, ColumnInfo: 1 byte
  • If present, TrustedSesions: 1 byte
  • If present, MultiStatementErrors: 1 byte
  • If present, ArrayTransformsOff: 1 byte
  • If present, XMLResponseFormat: 1 byte
  • If present, TASMFastFailReq: 1 byte

Field Notes

The following information applies to Options fields.
  • RequestMode indicates which mode is used to process a response. Settings are as follows:
    • F – specifies Field Mode
    • R – specifies Record Mode
    • I – specifies Indicator Mode
    • M – MultipartIndicator Mode

      If this field contains a binary zero, the database uses the mode specified elsewhere (in the Req, IndicReq, or FMReq parcel) in the request.

      When two or more parcels in a request specify conflicting modes, the database uses the mode specified in the Options parcel.

  • Function corresponds to the Request Processing Option field of the DBCAREA, and indicates whether the intent is to prepare and execute, to prepare, or to execute the request.
    Settings are as follows:
    • E – Specifies that the request should be executed.
    • A binary zero in this field is interpreted as an E.
    • P – Specifies that a PrepInfo parcel is built for each statement in the request. The statements may not contain parameterized SQL.
    • S – Specifies that a PrepInfo parcel is built for each statement in the request. The statements may contain parameterized SQL.
    • B – Specifies that a PrepInfo parcel is built for each statement in the request and that the request should be executed. The statements may contain parameterized SQL. This setting is supported for both Indicator mode and Record mode. For SQL statements that return no data, such as Insert, Update, Delete and DDL statements, an “empty” PrepInfo parcel is returned. Empty means that the column count in the PreInfo parcel is set to zero.
  • Select-data specifies the way data associated with a Large Object is returned, chosen as one of the following ASCII characters:
    • I – If the actual data is to be returned in the initial response.
    • L – If a locator token associated with the data within the transaction is to be returned.
    • S – If a locator token associated with the data within the spool file is to be returned.

      If the field contains a binary zero, a value of 'I' is assumed.

  • Continued-characters-state indicates whether character data crossing response parcels is well-formed within each parcel or only when all relevant parcels are considered. This option has effect only for MultipartIndicator response mode because only in that mode may data cross parcel boundaries. If not applicable, the option is ignored.
    Supported values are:
    • L – The default, specifies that character data crossing response parcels may be in the locked shift state
    • U – Specifies that character data crossing response parcels must be in the unlocked shift state
  • APH-response indicates whether response parcels may use the alternate parcel header. Supported values are:
    • Y – Specifies that alternate parcel headers may be used in response parcels
    • Binary zero – The default, if alternate parcel headers may not be used in response parcels
  • Return-statement-info indicates whether response parcels may use the alternate parcel header. Supported values are:
    • 'Y' – Specifies that StatementInformation response parcels are returned instead of DataInfo[X] and PrepInfo[X] response parcels. This setting is rejected if the ResponseMode option specifies 'F' (Field mode).
    • 'N', – The default, if StatementInformation response parcels may not be used.
  • TrustedSesions allowed indicates the trusted-request options.
    • 'N' – The default. It indicates that this is not a trusted request. If the trusted user possesses the trust-only attribute, this setting prevents “SET QUERY_BAND PROXYUSER...” from being affected.
    • 'Y' – Indicates that this is a trusted request. If the trusted user possesses the trust-only attribute, this setting allows “SET QUERY_BAND PROXYUSER...” to be affected.
  • Maximum DECIMAL precision indicates the precision of decimal data types in responses. Supported values are:
    • A positive value up to a maximum obtained using the DBCHQE SQL-limits query.
    • Binary zero, the default, if the client default, 15, is to be used.
  • IdentityColumnRetrieval indicates whether data is returned in response to an SQL Insert operation when Identity columns are involved. Supported values are:
    • Binary zero, the default, that no fields are returned.
    • 'C' – Specifies that the values for any Identity columns are returned.
    • 'R' – Specifies that the values for all fields in an inserted row that contains Identity columns are returned.
  • DynamicResultSets indicates whether stored procedures may include the results of its SQL requests in the response to the response to the SQL CALL statement invoking the procedure. Supported values are:
    • 'N', – The default, if such results may not be included.
    • 'Y' – If such results may be included.
  • SP-ReturnResult indicates where the results of the associated request are to be returned. Supported values are:
    • 0 – The default, if the results are returned to the stored procedure itself.
    • 1 –If the results are to be returned to the client.
    • 2 – If the results are to be returned to the CALLer of the stored procedure.
    • 3 –If the results are to be returned to both the stored procedure and the client.
    • 4 –If the results are to be returned to both the stored procedure and its CALLer.
  • PeriodStructOn indicates Period data types are treated as Structured UDTs:
    • 'N' – Period data types are treated as simple data types.
    • 'Y' – Period data types are treated as Structured UDTs in honoring the Transforms-off option. Setting PeriodStructOn to 'Y' requires setting the UDTTransformsOff to 'Y' at the same time. If not, the database returns an error since the support of Period as Struct is an extension of the support of Structured UDTs.
  • UDTTransformsOff indicates whether Structured UDTs are transformed into their external type:
    • 'N' – The flag is off and Structured UDTs are transformed into their external type.
    • 'Y' – The flag is on and Structured UDTs are to be returned from the server in the un-translated mode.
  • ColumnInfo allowed indicates whether the response parcels to this request contain large column or extended object name size.
    • 0 – The default, indicates that client can not accept extended object name in response parcels.
    • 1 – Indicates that client can accept extended object name in response parcels.
  • RFU1 through RFU2 are reserved for future use and must be set to binary zero. An error occurs if these fields are not set to binary zero.
  • MultiStatementErrors indicates whether statement independence results are returned.
    • 'N' – The default value, indicates that a problem with any statement in a multi-statement request results in a single Failure parcel indicating which statement had the problem. A problem with any statement in a multi-statement request ends the processing of that request. None of the statements is executed.
    • 'Y' – Indicates that processing is the same unless all errors are of certain limited types, in which case the response to statements having those problems is a StatementError (192) parcel. The responses to all other statements are Success, OK, or ResultSummary parcels. Certain problems with a statement in a multi-statement request allows other statements to be processed.
  • xmlResponseFormat indicates whether XML Data Types are supported. Besides the default value of 0, 'C' is the only other option currently supported. Both result in values being encoded in the character string (text) format. Other options, such as 'B', will be supported in future releases.
    • 0 – The default, indicates that XML values to be returned by the database be encoded in character string (text) format.
    • 'C' – Indicates that XML values to be returned by the database be encoded in character string (text) format.
  • tasmFastFailReq indicates whether the TASM FastFail feature is supported.
    • 'N' – The default, indicates that the TASM FastFail request not be processed.
    • 'Y' – Indicates that the TASM FastFail request be processed.