FREEMAIN

Release main storage that was acquired by using a GETMAIN request.


FREEMAIN

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

Condition: INVREQ

This command is threadsafe.

Description

FREEMAIN releases the following storage:

Main storage that was acquired by a GETMAIN command issued by the application.
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:

The GETMAIN command is 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.

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.

Start of change To release main storage that was acquired by using a GETMAIN64 request, use the FREEMAIN64 command. See FREEMAIN64. End of change

Options

DATA(data-area)

Specifies the data area of main storage to be released.

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.

The length of storage released is the length that was obtained by the GETMAIN request 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 released is the length obtained by the GETMAIN request.

Conditions

16 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 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 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)

dfhp4_freemain.html | Timestamp icon

Last updated: Thursday, 27 June 2019