COMMON-DATA

File 33
Op-Sys z/OS, z/VSE, BS2000/OSD
Statement FIND, PROCESS
Task Share memory between multiple applications. This memory is accessed by a unique name and is split up into data slots. When this view is to be used, the startup parameter CDATALEN must have a value of greater than 0 (zero).

Common Fields for all Operating Systems

Dictionary Field Name F/L Mu DE Remarks
ERROR-CODE N3      
ERROR-TEXT A58      
NODE N5   D  
NODE-NAME A16   D  
SYSTEM-MESSAGE-CODE A10      
DATA-ID A12   D Required for all functions except LIST.
NUMBER-OF-ENTRIES N5   D Relevant for functions CREATE and LIST.
ENTRY-LENGTH N3   D Relevant for functions CREATE and LIST.
ENTRY-NUMBER N5   D Relevant for functions MODIFY and GET.
DATA A250   D Relevant for functions MODIFY and GET.
CURRENT-ENTRIES N5   D Relevant for functions MODIFY, GET, LIST, CLOSE.
DELETE-ENTRY A3   D Relevant for function MODIFY.
PROTECT A8   D  
FUNCTION A8   D Required field.

Additional Fields Supported for BS2000/OSD

Dictionary Field Name F/L Mu DE Remarks
SYSTEM-CODE

B2

     

Relevant Error Codes

Code Text z/OS z/VSE BS2000/OSD
600 Unknown function. X X X
621 Identifier missing / duplicate / not found. X X X
622 NUMBER-OF-ENTRIES missing or invalid. X X X
623 ENTRY-LENGTH missing or invalid. X X X
624 ENTRY-NUMBER missing or invalid. X X X
625 Cannot allocate area. X X X
626 DATA missing. X X X
627 Field position + length > 250. X X X
629 Area is protected. X X X
746 Serialization running in error. X X X

Field Descriptions

Field Name Format/Length Operating System
CURRENT-ENTRIES (N5) z/OS, z/VSE, BS2000/OSD

Output field. The value of CURRENT-ENTRIES is set from the functions CLOSE, MODIFY, GET and LIST.

Field Name Format/Length Operating System
DATA (A250) z/OS, z/VSE, BS2000/OSD

Relevant for the functions MODIFY and GET. The contents of the entry.

Function MODIFY is expecting the input record in DATA.

Function GET provides the contents of the record in output field DATA.

Field Name Format/Length Operating System
DATA-ID (A12) z/OS, z/VSE, BS2000/OSD

DATA-ID identifies the name associated with an area of records in the COMMON-DATA. Required as input field in all functions except LIST.

Function LIST returns all existing DATA-IDs.

Field Name Format/Length Operating System
DELETE-ENTRY (A3) z/OS, z/VSE, BS2000/OSD

Only used in the function MODIFY as input field.

Functions MODIFY and DELETE-ENTRY='YES' are used to remove the requested record identified by ENTRY-NUMBER.

Field Name Format/Length Operating System
ENTRY-LENGTH (N3) z/OS, z/VSE, BS2000/OSD

The length of each entry in the area. Required input field in the function CREATE. Used as output field in functions CLOSE, MODIFY, GET, LIST.

Field Name Format/Length Operating System
ENTRY-NUMBER (N5) z/OS, z/VSE, BS2000/OSD

Relevant for functions MODIFY and GET.

ENTRY-NUMBER is required as input field if the function MODIFY and DELETE-ENTRY='YES' is used. Otherwise it is not required and is determined implicitly.

The example program below exploits this feature. ENTRY-NUMBER is omitted for the function MODIFY to write all data records and for function GET to read all data records.

Field Name Format/Length Operating System
FUNCTION (A8) z/OS, z/VSE, BS2000/OSD

Function to be performed. Possible options:

Option Explanation
CLOSE  Free unused space in a given area.
CREATE  Create a new area identified by DATA-ID with size (NUMBER-OF- ENTRIES * ENTRY-LENGTH).
DELETE  Delete area identified by DATA-ID.
GET  Get record from given area.
LIST  Generate list of active areas.
MODIFY  Add, modify or delete a record in a given area.
Field Name Format/Length Operating System
NUMBER-OF-ENTRIES (N5) z/OS, z/VSE, BS2000/OSD

The maximum number of entries in the area. Required as input field in function CREATE.

Used as output field in functions CLOSE, MODIFY, GET, LIST.

Field Name Format/Length Operating System
PROTECT (A8) z/OS, z/VSE, BS2000/OSD

Field used to set or display protection attributes of an area in COMMON-DATA.

It is an input field when function CREATE is requested. It is an output field to display protection attributes via function LIST. If protection is omitted, all users are permitted to issue all functions to that area.

The following options are available to restrict the use of an area for other users:

Option Explanation
DELETE Area is DELETE protected. The functions GET, LIST and MODIFY are permitted. Other users can read and modify area but cannot delete it.
MODIFY Area is MODIFY protected. Functions GET and LIST are permitted. Other users can issue function GET to read that area. It is not possible to modify and to delete it.
READ Area is READ protected. Other users cannot issue any function except LIST. It is not possible to read, modify and delete that area.

Example

The following example illustrates the usage of the different COMMON-DATA functions.

It consists of the following steps:

  • list existing COMMON-DATA areas and status information FUNCTION='LIST'

  • create an area in the COMMON-DATA pool FUNCTION='CREATE'

  • write 5 records into the area FUNCTION='MODIFY'

  • remove the third record FUNCTION='MODIFY'

  • compress the area to the used size of 4 records FUNCTION='CLOSE'

  • list the area and status information FUNCTION='LIST'

  • display the contents of the records in the area FUNCTION='GET'

  • remove the area and all records FUNCTION='DELETE'

  DEFINE DATA LOCAL
  1 COMMON-DATA VIEW OF COMMON-DATA
    2 ERROR-CODE
    2 ERROR-TEXT
    2 SYSTEM-CODE
    2 SYSTEM-MESSAGE-CODE
    2 NODE
    2 CURRENT-ENTRIES
    2 DATA
    2 DATA-ID
    2 DELETE-ENTRY
    2 ENTRY-LENGTH
    2 ENTRY-NUMBER
    2 FUNCTION
    2 NUMBER-OF-ENTRIES
    2 PROTECT
  *
  1 #DATA (A250)
  1 #DATA-ID (A12) INIT <'MSGBOX1'>
  1 #ERROR-ID (A30)
  1 #MSGTEXT (A14) INIT <'Message number'>
  1 #NODE (N3) INIT <148>
  1 #I (N1)
  1 #AREA-EXISTS (L) INIT <FALSE>
  1 #PUT-HEADER (L) INIT <TRUE>
  *
  END-DEFINE
  **********************************************************************
  *                                                                    *
  * List all available areas in the COMMON-DATA pool and check if      *
  * our DATA-ID is already created.                                    *
  *                                                                    *
  **********************************************************************
  MOVE 'COMMON-DATA Function LIST (*):' TO #ERROR-ID
  *
  FIND COMMON-DATA WITH NODE = #NODE
                    AND DATA-ID = '*'
                    AND FUNCTION = 'LIST'
  *
      IF COMMON-DATA.ERROR-CODE NE 0
         PERFORM ERROR-HANDLER
         ESCAPE ROUTINE
      END-IF
  *
      IF #PUT-HEADER EQ TRUE
  *
         ASSIGN #PUT-HEADER = FALSE
         WRITE '+-------------------------------------------------------+'
             / '! COMMON-DATA LIST Overview before starting our example !'
             / '+-------------------------------------------------------+'
            // 'Common-Data-Area Number of Entries Current Entries'
               'Length of Entry'
             / '________________ _________________ _______________'
               '_______________'
      END-IF
  *
      WRITE COMMON-DATA.DATA-ID
        17X COMMON-DATA.NUMBER-OF-ENTRIES
        11X COMMON-DATA.CURRENT-ENTRIES
        12X COMMON-DATA.ENTRY-LENGTH
  *
      IF COMMON-DATA.DATA-ID EQ #DATA-ID
         ASSIGN #AREA-EXISTS = TRUE
      END-IF
  *
  END-FIND
  *
  * Exit if area already created
  *
  IF #AREA-EXISTS EQ TRUE
     WRITE / '*** Sample cannot run. DATA-ID already created. ***'
       ESCAPE ROUTINE
  END-IF
  *
  NEWPAGE
  **********************************************************************
  *                                                                    *
  * Create an area in the COMMON-DATA pool.                            *
  *                                                                    *
  **********************************************************************
  MOVE 'COMMON-DATA Function CREATE' TO #ERROR-ID
  *
  PROCESS COMMON-DATA USING
          NODE = #NODE
        , DATA-ID = #DATA-ID
        , ENTRY-LENGTH = 100
        , FUNCTION = 'CREATE'
        , NUMBER-OF-ENTRIES = 10
  *
  IF COMMON-DATA.ERROR-CODE NE 0
     PERFORM ERROR-HANDLER
     ESCAPE ROUTINE
  END-IF
  **********************************************************************
  *                                                                    *
  * Write 5 messages into the COMMON-DATA area.                        *
  *                                                                    *
  **********************************************************************
  MOVE 'COMMON-DATA Function MODIFY (PUT):' TO #ERROR-ID
  *
  FOR #I = 1 TO 5
  *
      COMPRESS #MSGTEXT #I INTO #DATA
  *
      PROCESS COMMON-DATA USING
              NODE = #NODE
            , DATA = #DATA
            , DATA-ID = #DATA-ID
            , FUNCTION = 'MODIFY'
  *
      IF COMMON-DATA.ERROR-CODE NE 0
         PERFORM ERROR-HANDLER
         ESCAPE ROUTINE
      END-IF
  END-FOR
  **********************************************************************
  *                                                                    *
  * Oops, message number 3 was wrong. Remove it.                       *
  *                                                                    *
  **********************************************************************
  MOVE 'COMMON-DATA Function MODIFY (DELETE):' TO #ERROR-ID
  *
  PROCESS COMMON-DATA USING
              NODE = #NODE
            , DATA-ID = #DATA-ID
            , DELETE-ENTRY = 'YES'
            , ENTRY-NUMBER = 3
            , FUNCTION = 'MODIFY'
  *
  IF COMMON-DATA.ERROR-CODE NE 0
      PERFORM ERROR-HANDLER
      ESCAPE ROUTINE
  END-IF
  **********************************************************************
  *                                                                    *
  * Compress allocated area to the size really used for messages.      *
  *                                                                    *
  **********************************************************************
  MOVE 'COMMON-DATA Function CLOSE:' TO #ERROR-ID
  *
  PROCESS COMMON-DATA USING
              NODE = #NODE
            , DATA = #DATA
            , DATA-ID = #DATA-ID
            , FUNCTION = 'CLOSE'
  *
  IF COMMON-DATA.ERROR-CODE NE 0
     PERFORM ERROR-HANDLER
     ESCAPE ROUTINE
  END-IF
  **********************************************************************
  *                                                                    *
  * List our entry to check the status.                                *
  *                                                                    *
  **********************************************************************
  MOVE 'COMMON-DATA Function LIST (1):' TO #ERROR-ID
  *
  FIND COMMON-DATA WITH NODE = #NODE
                    AND DATA-ID = #DATA-ID
                    AND FUNCTION = 'LIST'
  *
      IF COMMON-DATA.ERROR-CODE NE 0
         PERFORM ERROR-HANDLER
         ESCAPE ROUTINE
      END-IF
  *
      IF COMMON-DATA.DATA-ID NE #DATA-ID
         ESCAPE TOP
      END-IF
  *
      WRITE '+-------------------------------------------------------+'
          / '! Status of our area in COMMON-DATA                     !'
          / '+-------------------------------------------------------+'
         // 'Common-Data-Area Number of Entries Current Entries'
            'Length of Entry'
          / '________________ _________________ _______________'
            '_______________'
  *
      WRITE COMMON-DATA.DATA-ID
        17X COMMON-DATA.NUMBER-OF-ENTRIES
        11X COMMON-DATA.CURRENT-ENTRIES
        12X COMMON-DATA.ENTRY-LENGTH
  *
  END-FIND
  *
  NEWPAGE
  **********************************************************************
  *                                                                    *
  * Get all our entries (non-destructive GET).                         *
  *                                                                    *
  **********************************************************************
  ASSIGN #PUT-HEADER = TRUE
  MOVE 'COMMON-DATA Function GET:' TO #ERROR-ID
  *
  FIND COMMON-DATA WITH NODE = #NODE
                    AND DATA-ID = #DATA-ID
                    AND DELETE-ENTRY = 'NO'
                    AND FUNCTION = 'GET'
  *
      IF COMMON-DATA.ERROR-CODE NE 0
         PERFORM ERROR-HANDLER
         ESCAPE ROUTINE
      END-IF
  *
      IF #PUT-HEADER EQ TRUE
  *
         ASSIGN #PUT-HEADER = FALSE
         WRITE '+-------------------------------------------------------+'
             / '! Contents of our area in COMMON-DATA                   !'
             / '+-------------------------------------------------------+'
            // 'Entry-number Data                                    '
             / '____________ ________________________________________'
      END-IF
  *
      WRITE COMMON-DATA.ENTRY-NUMBER
        7X COMMON-DATA.DATA (AL=50)
  *
  END-FIND
  **********************************************************************
  *                                                                    *
  * Remove area in the COMMON-DATA pool.                               *
  *                                                                    *
  **********************************************************************
  MOVE 'COMMON-DATA Function DELETE' TO #ERROR-ID
  *
  PROCESS COMMON-DATA USING
          NODE = #NODE
        , DATA-ID = #DATA-ID
        , FUNCTION = 'DELETE'
  *
  IF COMMON-DATA.ERROR-CODE NE 0
     PERFORM ERROR-HANDLER
     ESCAPE ROUTINE
  END-IF
  **********************************************************************
  *                                                                    *
  * ERROR-HANDLER                                                      *
  *                                                                    *
  **********************************************************************
  DEFINE SUBROUTINE ERROR-HANDLER
     WRITE #ERROR-ID
           COMMON-DATA.ERROR-CODE
           COMMON-DATA.ERROR-TEXT
           COMMON-DATA.SYSTEM-CODE
           COMMON-DATA.SYSTEM-MESSAGE-CODE
  END-SUBROUTINE
  *
  END     

Output from above sample program:

  Page 1                                                    00-11-10 09:02:02

  +-------------------------------------------------------+
  ! COMMON-DATA LIST Overview before starting our example !
  +-------------------------------------------------------+

  Common-Data-Area  Number of Entries Current Entries Length of Entry
  ________________  _________________ _______________ _______________
  TEST-BOX                          7               0             250
  CONTAINER                        20               0              50

  Page 2                                                    00-11-10 09:02:02

  +-------------------------------------------------------+
  ! Status of our area in COMMON-DATA                     !
  +-------------------------------------------------------+

  Common-Data-Area  Number of Entries Current Entries Length of Entry
  ________________  _________________ _______________ _______________
  MSGBOX1                           4               4             100

  Page 3 00-11-10 09:02:02
  +-------------------------------------------------------+
  ! Contents of our area in COMMON-DATA                   !
  +-------------------------------------------------------+

  Entry-number Data
  ____________ ________________________________________
       1       Message number 1
       2       Message number 2
       3       Message number 4
       4       Message number 5

Five records have been written to the area MSGBOX1. After removing the third record and compressing the area, four records are available containing the messages 1, 2, 4, 5.

Supplementary Information about COMMON-DATA

What does COMMON-DATA do?

COMMON-DATA allows you to establish areas to save data records with a fixed record length. These records can be accessed from different applications. The usage is determined by the applications only, for example, when to create and to destroy data records. It is a service for an effective data exchange. The areas are labeled with unique names provided in field DATA-ID.

Which Natural statements must be used with the various FUNCTIONs?

The functions LIST and GET should be requested with a FIND statement. All other functions (CLOSE, CREATE, DELETE, MODIFY) are designed as single requests and should be performed with a PROCESS statement.

How does writing to COMMON-DATA work?

The function MODIFY is used to write records into the data area. The records will be saved in sequential order. The ENTRY-NUMBER can be omitted for writing records with the function MODIFY. The creation of the COMMON-DATA records with explicitly defined entry numbers requires an ascending sequential order. For example, it is not possible to write a record with Entry Number 3 if only Entry Number 1 has been written already.