Communicating between programs and procedures using Dataqueues
A data area is an object used to hold data for access by any job running on the system.
A data area can be used whenever you need to store information of limited size, independent of the existence of procedures or files. Typical uses of data areas are:
• To provide an area to pass information within a job.
• To provide a field that is easily and frequently changed to control references within a job, such as:
– Supplying the next order number to be assigned
– Supplying the next check number
– Supplying the next save/restore media volume to be used
• To provide a constant field for use in several jobs, such as a tax rate or distribution list.
• To provide limited access to a larger process that requires the data area. A data area can be locked to a single user, thus preventing other users from processing at the same time.
Create Data Area (CRTDTAARA) command to create a data area.
Retrieve Data Area (RTVDTAARA) command to view the current value
Change Data Area (CHGDTAARA) command to change data area value.
Display Data Area (DSPDTAARA) command to display the current value.
Delete Data Area (DLTDTAARA) command to delete a data area.
You can journal your data areas.
Types of Data areas:
- Local Data Area
- Group Data Area
- Progarm Initialization Parameter Data Area
- Remote Data Area
Local data area
A local data area is created for each job in the system, including autostart jobs, jobs started on the system by a reader, and subsystem monitor jobs.
The system creates a local data area, which is initially filled with blanks, with a length of 1024 and type *CHAR.
When you submit a job using the SBMJOB command, the value of the submitting job's local data area is copied into the submitted job's local data area.
You can refer to your job's local data area by specifying *LDA for the DTAARA keyword on the CHGDTAARA, RTVDTAARA, and DSPDTAARA commands or *LDA for the substring built-in function (%SST).
The following is true of a local data area:
• The local data area cannot be referred to from any other job.
• You cannot create, delete, or allocate a local data area.
• No library is associated with the local data area.
• You cannot change the local data area in a secondary thread.
The local data area content is not affected by these commands: Transfer Job (TFRJOB), Transfer Batch Job (TFRBCHJOB), Reroute Job (RRTJOB), or Return (RETURN) command.
Group data area
The system creates a group data area when an interactive job becomes a group job (using the Change Group Attributes (CHGGRPA) command).
Only one group data area can exist for a group.
The group data area is deleted when the last job in the group is ended, or when the job is no longer part of the group job.
A group data area, which is initially filled with blanks, has a length of 512 and type *CHAR.
You can use a group data area from within a group job by specifying *GDA for the DTAARA parameter on the CHGDTAARA, RTVDTAARA, and DSPDTAARA commands. A group data area is accessible to all of the jobs in the group.
The following are true for a group data area:
• You cannot use the group data area as a substitute for a character variable on the substring built-in function (%SUBSTRING or %SST). • A group data area cannot be referred to by jobs outside the group.
• You cannot create, delete, or allocate a group data area.
• No library is associated with a group data area.
The contents of a group data area are unchanged by the Transfer to Group Job (TFRGRPJOB) command.
Following command can be used to set the value of the group data area:
CHGDTAARA DTAARA(*GDA) VALUE('January1988')
Retrieve the value of the group data area with the following CL command:
RTVDTAARA DTAARA(*GDA) RTNVAR(&GRPARA)
Program Initialization Parameter data area
A Program Initialization Parameter (PIP) data area (PDA) is created for each prestart job when the job is started.
The object sub-type of the PDA is different than a regular data area.
The PDA can only be referred to by the special value name *PDA.
The size of the PDA is 2000 bytes but the number of parameters contained in it is not restricted.
The RTVDTAARA, CHGDTAARA, and DSPDTAARA CL commands and the RTVDTAARA and CHGDTAARA macro instructions support the special value *PDA for the data area name parameter.
Remote data areas
A remote data area is a data area on a remote system.
You can access remote data areas by using distributed data management (DDM).
You do not need to change or recompile an application program that resides on one system when it retrieves data that resides on a remote system.
To ensure that you are accessing the correct data area, you might need to do one of the following tasks:
• Delete the standard data area and create a DDM data area that has the same name as the original standard data area
• Rename the standard data area You can create a DDM data area by doing the following:
CRTDTAARA DTAARA(LOCALLIB/DDMDTAARA) TYPE(*DDM)
RMTDTAARA(REMOTELIB/RMTDTAARA) RMTLOCNAME(SYSTEMB)
TEXT('DDM data area to access data area on SYSTEMB')
Creating a data area
Unlike variables, data areas are objects and must be created before they can be used. A data area can be created as:
• A character string that can be as long as 2000 characters.
• A decimal value
• A logical value '0' or '1', where '0' can mean off, false, or no; and '1' can mean on, true, or yes. When you create a data area, you can also specify an initial value for the data area. If you do not specify one, the following is assumed:
• 0 for decimal.
• Blanks for character.
• '0' for logical.
To create a data area, use the Create Data Area (CRTDTAARA) command.
CRTDTAARA DTAARA(CUST) TYPE(*DEC) + LEN(5 0) TEXT('Next customer number')
Data area locking and allocation
Locking and allocating a data area helps to ensure that the data area is not accessed by more than one job at a time.
The Change Data Area (CHGDTAARA) command uses a *SHRUPD (shared for update) lock on the data area during command processing. Use the Allocate Object (ALCOBJ) command to prevent other users from accessing the data area until your operations are completed.
Displaying a data area
By using the Display Data Area (DSPDTAARA) command, you can display the attributes (name, library, type, length, data area text description) and the value of a data area.
Changing a data area
To change the value of a data area, use the Change Data Area (CHGDTAARA) command.
Retrieving a data area
You can retrieve a data area and copy it to a variable by using the Retrieve Data Area (RTVDTAARA) command.
Examples: Retrieving a data area
These examples show different ways of retrieving a data area.
Assume that you are using a data area named ORDINFO to track the status of an order file.
This data area is designed so that:
• Position 1 contains an O (open), a P (processing), or a C (complete).
• Position 2 contains an I (in-stock) or an O (out-of-stock).
• Positions 3 through 5 contain the initials of the order clerk.
You can declare these fields in your program or procedure as follows:
DCL VAR(&ORDSTAT) TYPE(*CHAR) LEN(1)
DCL VAR(&STOCKC) TYPE(*CHAR) LEN(1)
DCL VAR(&CLERK) TYPE(*CHAR) LEN(3)
To retrieve the order status into &ORDSTAT, you would enter the following:
RTVDTAARA DTAARA(ORDINFO (1 1)) RTNVAR(&ORDSTAT)
To retrieve the stock condition into &STOCK, you would enter the following:
RTVDTAARA DTAARA(ORDINFO (2 1)) RTNVAR(&STOCKC)
To retrieve the clerk's initials into &CLERK, you would enter the following:
RTVDTAARA DTAARA(ORDINFO (3 3)) RTNVAR(&CLERK)
This example:
• Creates a 5-character data area named DA1 (in library MYLIB) with the initial value of 'ABCDE'
• Declares a 3-character variable named &CLVAR1
• Copies the contents of the last three positions of DA1 into &CLVAR1
To do this, the following commands would be entered:
CRTDTAARA DTAARA(MYLIB/DA1) TYPE(*CHAR) LEN(5) VALUE(ABCDE)
.
.
.
DCL VAR(&CLVAR1) TYPE(*CHAR) LEN(3)
RTVDTAARA DTAARA(MYLIB/DA1 (3 3)) RTNVAR(&CLVAR1)
&CLVAR1 now contains 'CDE'.
Example: Retrieving data area DA2
This example shows how to retrieve a decimal data area and copy it into a decimal variable.
The following example of the Retrieve Data Area (RTVDTAARA) command places the contents of a 5-digit decimal data area into a 5-digit decimal digit variable.
This example:
• Creates a 5-digit data area named DA2 (in library MYLIB) with two decimal positions and the initial value of 12.39
• Declares a 5-digit variable named &CLVAR2 with one decimal position
• Copies the contents of DA2 into &CLVAR2
To do this, the following commands would be entered:
CRTDTAARA DTAARA(MYLIB/DA2) TYPE(*DEC) LEN(5 2) VALUE(12.39)
.
.
.
DCL VAR(&CLVAR2) TYPE(*DEC) LEN(5 1)
RTVDTAARA DTAARA(MYLIB/DA2) RTNVAR(&CLVAR2)
&CLVAR2 now contains 0012.3 (fractional truncation occurred).
Example: Changing and retrieving a data area
This example shows how to change and retrieve a data area.
The following is an example of using the Change Data Area (CHGDTAARA) and Retrieve Data Area (RTVDTAARA) commands for character substring operations.
This example:
• Creates a 10-character data area named DA1 (in library MYLIB) with initial value ABCD5678IJ
• Declares a 5-character variable named &CLVAR1
• Changes the contents of data area DA1 (starting at position 5 for length 4) to the value EFG padding after the G with 1 blank)
• Retrieves the contents of data area DA1 (starting at position 5 for length 5) into the CL variable &CLVAR1
To do this, the following commands would be entered:
DCL VAR(&CLVAR1) TYPE(*CHAR) LEN(5)
.
CRTDTAARA DTAARA(MYLIB/DA1) TYPE(*CHAR) LEN(10) +
VALUE('ABCD5678IJ')
.
.
.
CHGDTAARA DTAARA((MYLIB/DA1) (5 4)) VALUE('EFG')
RTVDTAARA DTAARA((MYLIB/DA1) (5 5)) RTNVAR(&CLVAR1)
From the command line, we can create, change, display data area. We can use RTVDTAARA from command line, it can be used only in CL Program.
No value in data area
Type TEST value in New Value.
or
CHGDTAARA DTAARA(TESTDEV1/TESTDTAARA *ALL) VALUE(TEST)
We can see the value of the data area getting changed to TEST.
Changing a part of the data area by mentioning substring starting position and length.
or CHGDTAARA DTAARA(TESTDEV1/TESTDTAARA (4 4)) VALUE(X)
Now we can see that only the 4th character of the data area has been changed.
When we type RTVDTAARA on command line and take F4, it says command is not allowing in this setting.
RTVDTAARA is allowed only in CL Program like below to retrieve values like data queue name, message queue name, libarary name.
0067.00 RTVDTAARA DTAARA(TEST04) RTNVAR(&TESTDTAQ)
0069.00 RTVDTAARA DTAARA(TESTMSGD01) RTNVAR(&MSGQ)
0070.00 RTVDTAARA DTAARA(TESTLIBD01) RTNVAR(&LIBS)
To retrieve a part of the dataarea, we do like this
0196.00 RTVDTAARA DTAARA(TEST01A (1 1)) RTNVAR(&LCKFLG)