agent_stack_sz - Agent stack size configuration parameter

Configuration type

Database manager

Applies to

• Database server with local and remote clients
• Database server with local clients
• Partitioned database server with local and remote clients

Parameter type

Configurable

Default [range]

Linux (32-bit)

256 [16 - 1024]

Linux (64-bit) and UNIX

1024 [256 - 32768]

Windows

16 [8 - 1000]

Note: The default value is subject to change by the DB2 Configuration Advisor after initial database creation.

Unit of measure

Pages (4 KB)

When allocated

Linux and UNIX: Stack space (process virtual memory) is allocated as needed or reused in the main DB2 server process when a thread is created. Stack memory is used or committed as necessary.

Windows: AGENT_STACK_SZ represents the initial committed stack memory when a thread is created. Additional stack memory is used or committed as necessary.

When freed

Linux and UNIX: Stack space (process virtual memory) is retained for reuse when threads terminate and are freed when the DB2 server shuts down.

Windows: Stack space and memory are freed when a thread terminates.

On UNIX and Linux, agent_stack_sz is rounded up to the next larger power-of-2 based value. The default settings should be sufficient for most workloads on Linux and UNIX systems.

In Windows environments, this parameter is used to set the initial committed stack size for each agent. Regardless of the setting, each agent stack can grow to the minimum reserved stack size of 256 KB on 32-bit versions of Windows, and 2 MB on 64-bit versions of Windows. If you exceed the minimum reserved stack size, the agent stack might run out of space and return an error.

Windows uses the concepts of a "reserved" stack - the maximum to which the stack can grow, and the "committed" stack - the amount of memory committed to the stack when it is created. In addition, a guard page is added to the specified committed stack size in order to determine the minimum reserved stack space required. For example, with agent_stack_sz (committed stack) set to a value of 16, 1 guard page is added, and so the reserved stack size must be at least 17 pages. The maximum (that is, reserved) agent stack size can be increased by setting agent_stack_sz (that is, the committed stack) to a value that results in a minimum reserved stack size larger than the default reserve stack size of 64 pages. Note that Windows uses multiples of 1 MB for setting reserved stack sizes greater than 256 KB. For example, on 32-bit Windows, setting the agent stack size to a value within the range of [64 - 255] 4-KB pages results in a maximum stack of 1 MB, as 64*4 = 244 KB and 255*4 = 1020 KB round up to 1 MB. Setting the value for agent_stack_sz to a value less than the default reserve stack size has no effect on the maximum limit because the stack still grows as necessary up to the default reserve stack size.

You can change the default reserve stack size by using the db2hdr utility to change the header information for the db2syscs.exe file. The advantage of changing the default reserved stack size using the db2hdr utility is that it provides a finer granularity, therefore allowing the stack size to be set at the minimum required stack size. This conserves virtual address space on 32-bit Windows. However, you have to stop and restart DB2 for a change to the db2syscs.exe process to take effect, and this method must be repeated with any Fix Pack upgrade.

Recommendations:

If you are working with large or complex XML data in a 32-bit Windows environment, you should update the value of agent_stack_sz to at least 64 4-KB pages. Very complex XML schemas might require the value of agent_stack_sz to be much higher during schema registration or during XML document validation.

This limit is sufficient for most database operations.

Notes

• Agent stack memory does not count towards instance memory usage.
• While agent_stack_sz can be configured with a high stack space allocation for maximum usage, on average, only a small amount of allocated stack space is used by a thread. It is only this smaller amount which requires system memory.
• On the HP-UX platform, thread stack space requires a swap reservation. The approximate total swap requirement will be equal to the peak number of threads * (agent_stack_sz). The value of agent_stack_sz in this calculation is rounded up to the next larger power-of-2 value.