FREEMAIN

Release main storage acquired by a GETMAIN command.

Read syntax diagramSkip visual syntax diagram
FREEMAIN

>>-FREEMAIN--+-DATA(data-area)--------+------------------------><
             '-DATAPOINTER(ptr-value)-'   

Condition: INVREQ

This command is threadsafe.

Note for dynamic transaction routing: Using FREEMAIN of storage GETMAINed with SHARED, or of a resource defined with RELOAD=YES that has been LOADed could create inter-transaction affinities that adversely affect the use of dynamic transaction routing. See the CICS® Application Programming Guide for more information about transaction affinities.

Description

FREEMAIN releases main storage previously acquired by a GETMAIN command issued by the application, or by a LOAD for a program, map, or table, defined with RELOAD=YES. If the task that GETMAINed the storage or LOADed the program does not release it, CICS releases it at task end, unless:
  • The GETMAIN command specified the SHARED option.
  • The program is defined with RELOAD=YES.
  • The program is defined with RELOAD=NO but was LOADed with the HOLD option.

In the first two cases, the storage remains allocated until some other task issues a FREEMAIN to release it. In the third case, the program remains available until it is RELEASEd by another task.

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 issuing the FREEMAIN 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.

This storage must have been acquired by a previous GETMAIN command, except in the case of BMS pages. (For more guidance about BMS pages, see the description of the SET option in the CICS Application Programming Guide.)

Note that this option specifies the data area that was acquired by the GETMAIN command, not the pointer reference that was set to that address. You must use the DATAPOINTER option to specify a pointer-reference: DATA and DATAPOINTER are mutually exclusive. Therefore, in assembler language, “data-area” must be a relocatable expression that is a data reference; in COBOL or C it must be a data name; and in PL/I it must be a data reference. (See the CICS Application Programming Guide for a discussion of argument values.)

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

DATAPOINTER(ptr-value)
specifies the address of the main storage to be released. 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 released is the length obtained by the GETMAIN.

Conditions

INVREQ
RESP2 values:
1
The storage specified by the DATA or DATAPOINTER parameter is not storage acquired by a GETMAIN command.
2
The storage area specified by the DATA or DATAPOINTER parameter is in CICS-key storage, and the program issuing the FREEMAIN command is in user-key.

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 could free the storage by 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 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)