COMMON-DATA

#### Search Results

Search

# COMMON-DATA

File | 33
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).

## Fields

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.

## Relevant Error Codes

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

## Field Descriptions

Field Name | Format/Length
--- | ---
`CURRENT-ENTRIES` | (N5)

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

Field Name | Format/Length
--- | ---
`DATA` | (A250)

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
--- | ---
`DATA-ID` | (A12)

`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-ID`s.

Field Name | Format/Length
--- | ---
`DELETE-ENTRY` | (A3)

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
--- | ---
`ENTRY-LENGTH` | (N3)

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
--- | ---
`ENTRY-NUMBER` | (N5)

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
--- | ---
`FUNCTION` | (A8)

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
--- | ---
`NUMBER-OF-ENTRIES` | (N5)

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
--- | ---
`PROTECT` | (A8)

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.

### On this page

- Fields
- Relevant Error Codes
- Field Descriptions
- Example
- Supplementary Information about COMMON-DATA