15.10 - DBCAIRX Elements - 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

Immediately following the header are one or more elements. Each element will either:

  • Contain the actual data
  • Address the actual data
  • When the Eyecatcher field contains 'IRX8' and the Level field contains a value of '1', there is one element format, which either contains the data or addresses the data. New development should use only a Level of '1'; a value of 0 is deprecated. Such elements are described by Figure 6.

    Figure 6: DBCAIRX Element When Eyecatcher is 'IRX8‘ and Level 1

    Deprecated Elements

    When either the Eyecatcher field contains 'IRX8' and the Level field contains a value of '0', the Eyecatcher field contains 'IRX', or the Eyecatcher field contains 'DBCX', there are two element formats, one format contains the data and the other format addresses the data. The Element Type field indicates which; if the leftmost bit is '0' the element contains the data; if '1', the element addresses the data. Elements containing the data are described by Figure 7.

    Figure 7: Deprecated DBCAIRX Element Containing Actual Data

    Elements addressing the data have one of two forms, depending upon the value of the Eyecatcher field. When the Eyecatcher field is 'IRX8' and Level = '0', Figure 8 describes the element; when the Eyecatcher field is 'IRX' or 'DBCX', Figure 9 describes the element.

    Figure 8: DBCAIRX Element When Eyecatcher is 'IRX8‘ and Level 0
    Figure 9: Deprecated DBCAIRX Element When Eyecatcher is 'IRX' or 'DBCX'

    The sections that follow describe each of the fields in DBCAIRX. The fields are given in alphabetical order.

    Data Address

    The Data Address field specifies the address of the parcel body. The symbolic name depends upon the Eyecatcher field.

     

     

    The variable name for Data Address is...

    In this language...

    IRX8

    IRX & DBCX

    COBOL

    D8XILPPT

    DBXILPPT

    PL/I

    D8XILPPT

    DBXILPPT

    C

    d8xilpPt

    dbxilpPt

    IBM Assembler

    D8XILPPT

    DBXILPPT

     

    This routine...

    Does this for Data Address...1

    DBCHINI

    DBCHCL

    reads (IRQ; IWPF)


    1
    An en dash (–) means unavailable or not applicable.

     

    Data Address is used by...

    To...

    applications

    write

    Data Length

    When the Eyecatcher is ‘IRX‘ or ‘DBCX‘ the Data Length field specifies the length of the parcel body addressed by the Data Address field.

    The minimum value is 0 and:

     

    The maximum value is...

    If Maximum Parcel is set to...

    32763

    O

    65531

    H

     

    In this language...

    The variable name for Data Length is...

    COBOL

    DBXILPLN

    PL/I

    DBXILPLN

    C

    dbxilpLn

    IBM Assembler

    DBXILPLN

     

    This routine...

    Does this for Data Length...1

    DBCHINI

    DBCHCL

    reads (IRQ; IWPF)


    1
    An en dash (–) means unavailable or not applicable.

     

    Data Length is used by...

    To...

    applications

    write

    Data Size

    When the Eyecatcher is 'IRX8' the Data Size field specifies the length of the parcel body addressed by the Data Address field.

    The minimum value is 0 and:

     

    The maximum value is...

    If Maximum Parcel is set to...

    32763

    O

    65531

    H

    The symbolic name depends upon both the Eyecatcher and Level fields:

     

     

    The variable name for Data Size is...

    In this language...

    IRX8 and Level 0

    IRX8 and Level 1

    COBOL

    D8XILPLN

    D8XIEPLN

    PL/I

    D8XILPLN

    D8XIEPLN

    C

    d8xilpLn

    d8xiepLn

    IBM Assembler

    D8XILPLN

    D8XIEPLN

     

    This routine...

    Does this for Data Size...1

    DBCHINI

    DBCHCL

    reads (IRQ; IWPF)


    1
    An en dash (–) means unavailable or not applicable.

     

    Data Size is used by...

    To...

    applications

    write

    Element Length

    Element Length contains the length of the individual element.

     

    The maximum value is...

    If Maximum Parcel is set to...

    32767

    O

    65535

    H

    The symbolic name depends upon the Eyecatcher field.

     

     

    The variable name for Element Length is...

    In this language...

    IRX8

    IRX & DBCX

    COBOL

    D8XILLEN

    DBXILLEN

    PL/I

    D8XILLEN

    DBXILLEN

    C

    d8xilLen

    dbxilLen

    IBM Assembler

    D8XILLEN

    DBXILLEN

     

    This routine...

    Does this for Element Length...1

    DBCHINI

    DBCHCL

    reads (IRQ; IWPF)


    1
    An en dash (–) means unavailable or not applicable.

     

    Element Length is used by...

    To...

    applications

    write

    Element Type

    When the Eyecatcher field contains 'IRX8' and the Level field contains '1', Element Type indicates the type of element; currently only a Parcel element is supported and is indicated by an Element Type of '1' (mnemonic of 'D8XIETP' in all languages).

    When either the Eyecatcher field contains 'IRX8' and the Level field contains '0', the Eyecatcher field contains 'IRX', or the Eyecatcher field contains 'DBCX', the Element Type not only indicates whether the parcel data is in the element or simply addressed by the element, but also specifies the parcel flavor. If the leftmost bit is zero, then the parcel body is contained in the element itself; if this bit is one, then the parcel body is addressed by the element. The remainder of the field contains the parcel flavor.

    The symbolic name depends upon both the Eyecatcher and Level fields:

     

     

    The variable name for Element Type is...

    In this language...

    IRX8 and Level 0

    IRX8 and Level 1

    IRX & DBCX

    COBOL

    D8XILTYP

    D8XIETYP

    DBXILTYP

    PL/I

    D8XILTYP

    D8XIETYP

    DBXILTYP

    C

    d8xilTyp

    d8xieTyp

    dbxilTyp

    IBM Assembler

    D8XILTYP

    D8XIETYP

    DBXILTYP

     

    This routine...

    Does this for Element Type...1

    DBCHINI

    DBCHCL

    reads (IRQ; IWPF)


    1
    An en dash (–) means unavailable or not applicable.

     

    Element Type is used by...

    To...

    applications

    write

    A mnemonic is provided for the high-order bit and should be used. The symbolic name depends upon the Eyecatcher field. The name is the same for all languages, including C. For 'IRX' and 'DBCX' the name is DBXILTP. For 'IRX8' the name is D8BXILTP.

    Any value in Element Type greater than 4095 gives a nonzero return code. Any value in Element Type less than 4096 and not a valid parcel flavor will result in an error being returned from the Teradata Database.

    If the high‑order bit is off in Element Type, the element data contains a parcel body. However, if the high‑order bit is on in Element Type, the element data contains a pointer to the actual parcel body and the length of the pointed to parcel body. Element Length in this case always contains 10.

    Eyecatcher

    Eyecatcher in the DBCAIRX is used for self‑documentation, validation, and debugging. The symbolic name depends upon the Eyecatcher field.

     

     

    The variable name is...

    In this language. . .

    for Eyecatcher and ‘IRX8‘

    for Eyecatcher and ‘IRX‘ or ‘DBCX‘

    IBM Assembler, COBOL, or PL/I

    D8XIID

    DBXIID

    C

    d8xiId

    dbxiId

     

    This routine...

    Does this for Eyecatcher...1

    DBCHINI

    DBCHCL

    reads (IRQ; IWPF)


    1
    An en dash (–) means unavailable or not applicable.

     

    Eyecatcher is used by...

    To...

    applications

    write

    Eyecatcher is set to 'IRX8', 'IRX', or 'DBCX' by the application before calling DBCHCL for the Initiate Request function.

    Note: Apostrophes are not used in Eyecatcher.

    New development should use only the 'IRX8' form. The others are deprecated.

    Level

    When the Eyecatcher is 'IRX8', the Level field specifies the format of the extension.

     

    In this language...

    The variable name for Level is...

    IBM Assembler, COBOL, or PL/I

    D8XCLVL

    C

    d8xcLvl

     

    This routine...

    Does this for Level...1

    DBCHINI

    DBCHCL

    reads (CON)


    1
    An en dash (–) means unavailable or not applicable.

     

    Level is used by...

    To...

    applications

    write

    Level may have values of “1” or “0”. If the value is:

    "1" it indicates that only one element format exists. New development should use only this value.

    "0" it indicates that two element formats exist. This value is deprecated.

    Next Pointer

    If nonzero, Next Pointer points to another DBCAIRX to form a linked list of DBCAIRX extensions. For implicit Connects, Connect extensions (DBCACNX) may also be included. The symbolic name depends upon the Eyecatcher field.

     

     

    The variable name for Next Pointer is...

    In this language...

    IRX8

    IRX & DBCX

    IBM Assembler, COBOL, or PL/I

    D8XINEXT

    DBXINEXT

    C

    d8xiNext

    dbxiNext

     

    This routine...

    Does this for Next Pointer...1

    DBCHINI

    DBCHCL

    reads (IRQ; IWPF)


    1
    An en dash (–) means unavailable or not applicable.

     

    Next Pointer is used by...

    To...

    applications

    write

    The sequence in which the DBCAIRX extensions are linked is the same sequence in which the parcels contained in DBCAIRXs are built in the request buffer.

    If there is only one DBCAIRX, or if this is the last DBCAIRX in the linked list, then set Next Pointer to zero or PL/I null pointer.

    Parcel Flavor

    The Parcel Flavor field specifies the flavor of the parcel. Values greater than 32767 are rejected by CLIv2; values that are not valid for the Teradata Database being used will be rejected by the Database.

     

    In this language...

    The variable name for Parcel Flavor is...

    IBM Assembler, COBOL, or PL/I

    D8XIEPF

    C

    d8xiePF

     

    This routine...

    Does this for Parcel Flavor...

    DBCHCL

    reads (IRQ; IWPF)

    Total Length

    If ‘DBCX‘ was specified in Eyecatcher, Total Length specifies the length of one DBCAIRX in bytes.

     

    In this language...

    The variable name for Total Length is...

    IBM Assembler, COBOL, or PL/I

    DBXILEN

    C

    dbxiLen

     

    This routine...

    Does this for Total Length...1

    DBCHINI

    DBCHCL

    reads (IRQ; IWPF)


    1
    An en dash (–) means unavailable or not applicable.

     

    Total Length is used by...

    To...

    applications

    write

    Total Length must be set by the application before calling DBCHCL. This length is validated against the sum of the lengths of the individual elements in the DBCAIRX plus the header. If it is not correct, the Teradata Database sends a nonzero return code.

    Total Size

    If ‘IRX8 or IRX‘ was specified in Eyecatcher, Total Size specifies the length of one DBCAIRX in bytes.

     

     

    The variable name for Total Size is...

    In this language...

    IRX8

    IRX

    IBM Assembler, COBOL, or PL/I

    D8XISIZE

    DBXISIZE

    C

    d8xiSize

    dbxiSize

     

    This routine...

    Does this for Total Size...1

    DBCHINI

    DBCHCL

    reads (IRQ; IWPF)


    1
    An en dash (–) means unavailable or not applicable.

     

    Total Size is used by...

    To...

    applications

    write

    Total Size must be set by the application before calling DBCHCL. This size is validated against the sum of the sizes of the individual elements in the DBCAIRX plus the header. If it is not correct, the Teradata Database sends a nonzero return code.