The ALLOCATE DESCRIPTOR statement allocates an SQL descriptor.
Invocation
This statement can only be embedded
in an application program, SQL function, SQL procedure, or trigger.
It cannot be issued interactively. It is an executable statement that
cannot be dynamically prepared. It must not be specified in REXX.
Authorization
None required.
Syntax

.-SQL-. .-LOCAL--.
>>-ALLOCATE--+-----+--DESCRIPTOR--+--------+--SQL-descriptor-name-->
'-GLOBAL-'
.-WITH MAX--20-------------------.
>--+--------------------------------+--------------------------><
'-WITH MAX--+-integer----------+-'
'-integer-variable-'
Description
- LOCAL
- Defines the scope of the name of the descriptor to be local to
the program invocation. The descriptor will not be known outside this
scope. For example, a program called from another separately compiled
program cannot use a descriptor that was allocated by the calling
program. The scope of the descriptor is also limited to the thread
in which the program that contains the descriptor is running. For
example, if the same program is running in two separate threads in
the same job, the second thread cannot use a descriptor that was allocated
by the first thread.
- GLOBAL
- Defines the scope of the name of the descriptor to be global to
the SQL session. The descriptor will be known to any program that
executes using the same database connection.
- SQL-descriptor-name
- Names the descriptor to allocate. The name must not be the same
as a descriptor that already exists with the specified scope.
- WITH MAX
- The descriptor is allocated to support the specified maximum number
of items. If this clause is not specified, the descriptor is allocated
with a maximum of 20 items.
- integer
- Specifies the number of items to allocate. The value of integer must
be greater than zero and not greater than 8000.
- integer-variable
Specifies an integer variable (or decimal or numeric
variable with zero scale) that contains the number of items to allocate.
It cannot be a global variable. The value of integer-variable must
be greater than zero and not greater than 8000.
Notes
Descriptor persistence: Local descriptors
are implicitly deallocated based on the CLOSQLCSR option:
- For ILE programs, if CLOSQLCSR(*ENDACTGRP) is specified (the default),
local descriptors are implicitly deallocated when the activation group
ends. If CLOSQLCSR(*ENDMOD) is specified, local descriptors are implicitly
deallocated on exit from the module.
- For OPM programs, if CLOSQLCSR(*ENDPGM) is specified (the default),
local descriptors are implicitly deallocated when the program ends.
If CLOSQLCSR(*ENDSQL) is specified, local descriptors are implicitly
deallocated when the first SQL program on the call stack ends. If
CLOSQLCSR(*ENDJOB) is specified, local descriptors are implicitly
deallocated when the job ends.
Global descriptors are implicitly deallocated when the
activation group ends.
Both local and global descriptors can be explicitly deallocated
using the DEALLOCATE DESCRIPTOR statement.
Examples
Allocate a descriptor called 'NEWDA'
large enough to hold 20 items.
EXEC SQL ALLOCATE DESCRIPTOR 'NEWDA'
WITH MAX 20