Identifies a compiled Oracle Rdb request. RDML generates request
    handles for statements that contain record selection expressions.
    In almost all cases, it is unnecessary for you to explicitly
    specify request handles.

    You can use a request handle in the following RDML statements:

    o  GET

    o  FOR

    o  START_STREAM

    o  STORE

    o  Statistical Functions (AVERAGE, COUNT, MAX, MIN, TOTAL)

1  –  More

    RDML allows the syntax (REQUEST_HANDLE rh) to go on each statistical
    expression in the GET ... END_GET block, and there is one request per
    statistical expression.  For example,

    GET
       a = COUNT
           (request_handle r1)
            ...;
       b = MAX
           (request_handle r2)
            ...;
    END_GET

2  –  Examples

    The following programs demonstrate the use of the REQUEST_HANDLE
    clause in a FOR statement. These programs:

    o  Declare the variable, REQ1, for a request handle and the local
       variable, "name"

    o  Initialize REQ1 to zero

    o  Assign a value to "name"

    o  Start a transaction

    o  Use the request handle in the first FOR statement

    o  Assign a new value to "name"

    o  Use the same request handle again in the second FOR statement

    By using the same request handle in the second (identical)
    request the program can reuse the code generated in the first
    FOR statement for the second FOR statement; this enhances overall
    performance.

2.1  –  C Example

    #include <stdio.h>
    DATABASE PERS = FILENAME "PERSONNEL";

    DECLARE_VARIABLE name SAME AS PERS.EMPLOYEES.LAST_NAME;
    extern long RDB$RELEASE_REQUEST();
    RDML$HANDLE_TYPE REQ1;

    main()
    {
    REQ1 = 0;
    strcpy(name,"Gray");

    READY PERS;
    START_TRANSACTION READ_ONLY;

    FOR (REQUEST_HANDLE REQ1) E IN PERS.EMPLOYEES
         WITH E.LAST_NAME = name
         printf("%s\n",E.FIRST_NAME);
    END_FOR;

    if ((RDB$RELEASE_REQUEST(RDB$MESSAGE_VECTOR, &REQ1) & 1) == 0)
                             RDML$SIGNAL_ERROR(RDB$MESSAGE_VECTOR);

    COMMIT;
    FINISH;
    }

2.2  –  Pascal Example

    program request (input,output);
    DATABASE PERS = FILENAME 'PERSONNEL';

    DECLARE_VARIABLE OF name SAME AS PERS.EMPLOYEES.LAST_NAME;
    REQ1 : RDML$HANDLE_TYPE;

    begin
    REQ1 := 0;
    name := 'Gray';

    READY PERS;
    START_TRANSACTION READ_ONLY;

    FOR (REQUEST_HANDLE REQ1) E IN PERS.EMPLOYEES
       WITH E.LAST_NAME = name
       writeln (E.FIRST_NAME);
    END_FOR;

    if not RDB$RELEASE_REQUEST(RDB$MESSAGE_VECTOR, REQ1)
    then  RDML$SIGNAL_ERROR(RDB$MESSAGE_VECTOR);

    COMMIT;

    FINISH;
    end.

3  –  Format

  (B)0request-handle =

  qq>( q> REQUEST_HANDLE qqqqqqq> host-variable qqqqq> ) qq>

3.1  –  Format arguments

    host-variable          A valid host language variable.