COMMON-DATA

File	33
Op-Sys	z/OS, z/VSE, BS2000
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	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

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

Relevant Error Codes

Code	Text	z/OS	z/VSE	BS2000
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

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

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

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

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

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

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

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

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

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.