| 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).
|
| 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. |
| Dictionary Field Name | Format/
Length/ Desc/Mu |
Description |
|---|---|---|
| CURRENT-ENTRIES | (N5) | Output field. The value of CURRENT-ENTRIES is set from functions CLOSE, MODIFY, GET and LIST. |
| D | ||
| DATA | (A250) | Relevant for functions MODIFY and GET. The contents of the entry. |
| D | Function MODIFY is expecting the input record in DATA. | |
| Function GET provides the contents of the record in output field DATA. | ||
| DATA-ID | (A12) | Required for all functions except LIST. DATA-ID identifies the name associated with an area of records in the COMMON-DATA. Required as input field in all functions except LIST. |
| D | Function LIST returns all existing DATA-IDs. | |
| DELETE-ENTRY | (A3) | Relevant for function MODIFY. |
| D | Functions MODIFY and DELETE-ENTRY='YES' are used to remove the requested record identified by ENTRY-NUMBER. | |
| 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. |
| D | ||
| 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. |
| D | ||
| FUNCTION | (A8) | Required field. |
| D | Function to be performed. Possible options: | |
| CLOSE Free unused space in a given area. | ||
| CREATE Create a new area identified by | ||
| DATA-ID with size (NUMBER-OF-ENTRIES | ||
| multiplied by 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. | ||
| NUMBER-OF-ENTRIES | (N5) | The maximum number of entries in the area. Required as input field in function CREATE. |
| D | Used as output field in functions CLOSE, MODIFY, GET, LIST. | |
| PROTECT | (A8) | Field used to set or display protection attributes of an area in COMMON-DATA. |
| D | 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: | ||
| 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. |
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.
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.
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.
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.