It is sometimes desirable to acquire virtual storage work area dynamically while a program is being executed, rather than define them when the program is coded. For instance the program may need sizeable intermediate work area that has one or more of the following characteristics:

  • Is variable in size, depending on the processing required during a particular execution of the program.
  • Is not needed for the entire duration of the program's execution.
  • Is perhaps not needed at all during program execution, depending on the nature of the user's request.

CICS Storage Control Program (SCP) controls requests for main storage by the application program. There are two commands available, one for getting the storage (GETMAIN) and another for freeing it (FREEMAIN).

A program can acquire a specified amount of virtual storage by issuing a GETMAIN command. The syntax of this command is:


The SET (ADDRESS of...) option is the address of the acquired storage area toy CICS. The length of the storage area, which you want, should be specified in the LENGTH or FLENGTH option. You can specify either LENGTH or FLENGTH, but not both. Your choice will depend on how much storage is being required and in MVS/XA systems, whether the storage should be allocated above or below the 16-megabyte storage line. The maximum length of storage to be acquired is 65,504 bytes for the LENGTH option and 1,073,741,824 bytes for the FLENGTH option. The INITIMG option determines the initial value to be filled in the storage acquired. The NOSUSPEND option if specified inhibits the NOSTG (No storage) condition and returns to the next instruction. The common exceptional conditions for GETMAIN command are:

  • LENGERR - The length exceeded the limit.
  • NOSTG - No storage is available and the default action is to suspend the task until the storage becomes available.

In MVS/XA environments, CICS application programs can reside above or below the 16MB storage line, and they can be executed either 24-bit or 31-bit addressing mode. (The residence and addressing modes of a program are specified when the program is link edited, using the AMODE and RMODE options of the linkage editor). A program's residence and addressing modes determine the maximum amount of storage, the program can request and whether the storage will be allocated above or below the 16-megabyte line. This in turn affects the choice of the LENGTH and FLENGTH option when coding the GETMA1N command.

Specification of the LENGTH option always causes the storage to be allocated below the 16-megabyte line. This rule applies whether the program is executing in 24-bit mode or 31-bit mode. You should use the LENGTH option when you want to ensure that storage is allocated below the 16-megabyte line. When using the FLENGTH option the location of the storage is determined by the amount requested and the program's addressing mode. The following chart summarizes the rules for specifying the FLENGTH option. The following table shows whether the storage will be allocated above or below the 16-megabyte line, depending on the amount of storage requested and the addressing mode being used to execute the program.

Storage Allocation

Storage Allocation

Notice that requests for less than 4K bytes are always allocated below the 16M line. Notice also that the maximum length depends on whether the program is executing in 24-bit mode or 31-bit mode. For AMODE = 24 programs, the maximum length is 65,504 (64K) bytes and for AMODE = 31 programs, the maximum length is 1,073,741,824 (1024K) bytes. The following example illustrates the usage of the GETMAIN command:

usage of the GETMAIN command

At the completion of the command, the storage of 1000 bytes will be acquired for MEM-area, which would contain null characters.

Although CICS application programs can issue commands to acquire storage dynamically, it is recommended that you use these commands when virtual storage constraints exist in your CICS system. CICS always strives to optimize the use of storage within the CICS region. Random application program requests for storage areas of varying sizes can have adverse effects on the use of storage within the region. As with the use of input areas, there is a trade off between the storage saved for any given task and additional processing that CICS must perform to satisfy GETMAIN requests. Therefore it is best to minimize the use of GETMAIN commands in your CICS application programs.

The storage acquired through GETMAIN should be made free as soon as its requirement is over. This is achieved by issuing a FREEMAIN command. If the FREEMAIN command is not used the acquired storage will be released only at the termination of the task. You cannot issue a FREEMAIN command to release an area that was not acquired using a GETMAIN command. The syntax of the FREEMAIN command is given below:

The DATA parameter is used to specify the name of the storage area to be released.In the CICS macro level, the storage control functions were always used in order to maintain the quasi-re-entrancy of the application programs. But in the CICS command level, the quasi-re-entrancy is automatically guaranteed for COBOL programs. So virtually all CICS command level application programs can be written without using the GETMAIN and FREEMAIN commands.

All rights reserved © 2020 Wisdom IT Services India Pvt. Ltd Protection Status

IBM Mainframe Topics