1.13 Locator

Organization of this section
(1) Overview
(2) Rules

(1) Overview

A locator is data containing a 4-byte value that identifies a specific data value on the server. The use of a locator allows you to process an SQL statement that handles data without storing the entity for the data on a client.

(2) Rules

  1. The following table lists types of locators that are available.

    Table 1-37 Types of locators

    TypeDescription
    BLOB locatorHas a value that identifies BLOB type data values on the server.
    BINARY locatorHas a value that identifies BINARY type data values on the server.
  2. The following table lists how to specify a locator and locations where a locator can be specified.

    Table 1-38 Locator specification method and locations where one can be specified

    TypeSpecification methodSpecifiable locations
    BLOB locatorEmbedded variableAnywhere a BLOB type embedded variable can be specified.
    BINARY locatorEmbedded variableAnywhere a BINARY type embedded variable can be specified.
    However, if the data type of the allocated data on the server is an embedded variable of a locator of the BINARY type with a maximum length of 32,001 bytes or greater, a BINARY locator can be specified only in those locations where BINARY-type embedded variables with a maximum length of 32,001 bytes or greater can be specified.
  3. Locators to which data values on the server are not allocated are invalid.
  4. When a locator is specified in one of the following locations, a data value is allocated to the locator, and the locator is enabled. In a given transaction, enabled locators can be specified in SQL statements, in the same way as data of the corresponding data type.
    • INTO clause of the single-row SELECT statement
    • INTO clause of the FETCH statement
    • Target of an assignment statement
    • An argument in the CALL statement with respect to the OUT or INOUT parameter for the procedure
    • INTO clause of the EXECUTE statement
  5. A locator is disabled in the following cases:
    • When specified in the FREE LOCATOR statement
    • When the COMMIT statement is executed
    • When the ROLLBACK statement is executed
    • When the DISCONNECT statement is executed
    • Automatic COMMIT when the PURGE TABLE statement is executed
    • Automatic COMMIT during execution of a definition SQL statement when YES is specified in the PDCMMTBFDDL client environment variable
    • Transaction termination through implicit rollback
  6. An error results if a disabled locator is specified in an SQL statement that handles allocated data or in the FREE LOCATOR statement.
  7. If multiple locators that identify the same data on the server are created by specifying embedded variables for the locators in the target of assignment statement format 2 or in the assignment value, and if any of those locators is disabled, the other locators remain enabled.
  8. If another set of data is allocated to an enabled locator to which data is already allocated, the original value of the locator remains enabled.
  9. Overwriting the value of a locator by a UAP coding language disables the locator. In some cases, any data that is different from the data before the overwriting is identified.
  10. Assigning the value of an enabled locator to a disabled locator by means of a UAP coding language enables the disabled locator, and the data that is the same as the assignment source locator is identified. In this case, disabling either locator disables both locators.