FREEMAIN

Release main storage that was acquired by using a GETMAIN command or by using a LOAD command for a program, map, or table that is defined with RELOAD=YES.

Syntax

FREEMAIN

Condition:

This command is threadsafe.

NOHANDLE, RESP, and RESP2 are common options that can be added to all EXEC CICS commands to process error conditions. They are not explicitly included in the command syntax diagram and option descriptions. For information about these common options and EXEC CICS command syntax, see EXEC CICS command format and programming considerations.

Description

FREEMAIN releases the following storage:

Main storage that was acquired by a GETMAIN command that is issued by the application. To release main storage that was acquired by using a GETMAIN64 request, use the FREEMAIN64 command. See FREEMAIN64.
Main storage that was acquired by a LOAD command for a program, map, or table that is defined with RELOAD=YES.

If the task that acquired the storage or loaded the program does not release it, CICS® releases the storage at task end, except for in the following situations:

GETMAIN specified the SHARED option. The storage remains allocated until another task issues a FREEMAIN or FREEMAIN64 request to release it.
The program is defined with RELOAD=YES. The storage remains allocated until another task issues a FREEMAIN or FREEMAIN64 request to release it.
The program is defined with RELOAD=NO but was loaded with the HOLD option. The program remains available until it is released by another task.

If a program is running under a task that is defined with TASKDATAKEY(USER) on the TRANSACTION resource definition, do not explicitly use FREEMAIN or FREEMAIN64 but allow the storage to be freed as part of the task termination.

Note: In the first two situations listed, using FREEMAIN might create inter-transaction affinities that adversely affect the use of dynamic transaction routing. For more information about transaction affinities, see Affinity.

You can release CICS-key storage from a program only if it is being executed in CICS-key. If the previously acquired storage was obtained from CICS-key storage, and the program that issues the FREEMAIN request is in user-key, an INVREQ condition occurs with a RESP2 value of 2.

Options

DATA(data-area)

Specifies the data area of main storage to be released.

In assembler, data-area must be a relocatable expression that is a data reference. In COBOL or C®, it must be a data name. In PL/I, it must be a data reference.

The length of storage that is released is the length that was obtained by the GETMAIN command and not necessarily the length of the data area.

DATAPOINTER(ptr-value)

Specifies the address of the main storage to be released, as a pointer reference. This option is an alternative to the DATA option, and specifies the pointer reference that was returned by a GETMAIN command using the SET option.

The length of storage that is released is the length that is obtained by the GETMAIN command.

Conditions

16 INVREQ

RESP2 values:

1: The storage that is specified by the DATA or DATAPOINTER parameter is not storage that is acquired by a GETMAIN command.
2: The storage area that is specified by the DATA or DATAPOINTER parameter is in CICS-key storage, and the program that issues the FREEMAIN command is in user-key.
3: The storage area that is specified by the DATA or DATAPOINTER parameter is maintained by CICS, and any FREEMAIN request that attempts to release CICS-maintained storage areas is rejected.

Default action: terminate the task abnormally.

Example: COBOL

DATA DIVISION.
WORKING-STORAGE SECTION.
77  AREA-POINTER    USAGE IS POINTER.
LINKAGE SECTION.
  01  WORKAREA          PIC X(100).
PROCEDURE DIVISION.
  EXEC CICS GETMAIN SET(AREA-POINTER)
  LENGTH(100)
  END-EXEC.
      .
  SET ADDRESS OF WORKAREA TO AREA-POINTER.
      .
      .
  EXEC CICS FREEMAIN DATA(WORKAREA)
  END-EXEC.
  EXEC CICS RETURN
  END-EXEC.

Alternatively, the previous COBOL example can free the storage by using the following command:

EXEC CICS FREEMAIN DATAPOINTER(AREA-POINTER)
END-EXEC.

Example: C

#pragma XOPTS(CICS);
#define MAINSIZE 100;
main()
{
 char              *buffer;
 struct eib_record dfheiptr;
 EXEC CICS ADDRESS EIB(dfheiptr);
 EXEC CICS GETMAIN SET(buffer)
                   LENGTH(MAINSIZE);
 buffer[2] = 'a';
   .
   .
 EXEC CICS FREEMAIN DATA(buffer);
 EXEC CICS RETURN;
}

Example: PL/I

DCL AREA_PTR    POINTER,
    WORKAREA    CHAR(100) BASED(AREA_PTR);
  .
  .
  .
EXEC CICS GETMAIN SET(AREA_PTR) LENGTH(100);
  .
EXEC CICS FREEMAIN DATA(WORKAREA);

Example: Assembler

WORKAREA   DS   CL100
  .
  .
           EXEC CICS GETMAIN SET(9) LENGTH(100)
           USING  WORKAREA,9
           EXEC CICS FREEMAIN DATA(WORKAREA)

Alternatively, you can free storage by using the DATAPOINTER option as shown in the following example:

WORKAREA  DS   CL100
  .
          EXEC CICS GETMAIN SET(9) LENGTH(100)
          USING  WORKAREA,9
  .
  .
          DROP   9
  .
          EXEC CICS FREEMAIN DATAPOINTER(9)