A data area is an OS/400 object used to communicate data such as variable values between programs within a job and between jobs. A data area can be created and declared to a program before it is used in that program or job. For information on how to create and declare a data area, see the CL Programming manual.
The local data area can be used to pass any desired information between programs in a job. This information may be free-form data, such as informal messages, or may consist of a fully structured or formatted set of fields.
Internal and external floating-point data items can be passed using the local data area. Internal floating-point numbers written to the local data area using a DISPLAY statement are converted to external floating-point numbers.
The system automatically creates a local data area for each job. The local data area is defined outside the ILE COBOL program as an area of 1024 bytes.
When a job is submitted, the submitting job's local data area is copied into the submitted job's local data area. If there is no submitting job, the local data area is initialized to blanks.
An ILE COBOL program can access the local data area for its job with the ACCEPT and DISPLAY statements, using a mnemonic name associated with the environment-name LOCAL-DATA.
There is only one local data area associated with each job. Even if several work stations are acquired by a single job, only one local data area exists for that job. There is not a local data area for each workstation.
You can pass data between programs using data areas that you create. This information may be free-form data, such as informal messages, or may consist of a fully structured or formatted set of fields. You specify the library and the name of the data area when you create it.
Using the Data Area formats (as opposed to the Local Data Area formats) of the ACCEPT and DISPLAY statements, you can access these data areas. The FOR phrase allows you to specify the name of the data area. Optionally, you can specify an IN LIBRARY phrase to indicate the OS/400 library where the data area exists. If the IN LIBRARY phrase is not specified, the library defaults to *LIBL.
When you use the DISPLAY statement to write data to a data area you have created, it is locked by the system with a LEAR (Lock Exclusive Allow Read) lock before any data is written to the data area. If any other lock exists on the data area, the LEAR lock is not applied, and the data area is not written. By specifying the WITH LOCK phrase, you can keep the data area locked after the Display operation has completed.
When you use the ACCEPT statement to retrieve data from a data area you have created, the system applies an LSRD (Lock Shared for Read) lock to prevent the data area from being changed while it is read. After the read is complete, the LSRD lock is removed, and a LEAR lock is placed on the data area if a WITH LOCK phrase was specified.
For both the ACCEPT and DISPLAY statements, if a WITH LOCK phrase was not specified, any LEAR lock held prior to the statement will be removed.
In ILE COBOL only one LEAR lock will be placed on a data area while the COBOL Run unit (activation group) is active. If any data areas remain locked when an activation group ends, the locks are removed.
An ON EXCEPTION condition can exist for several reasons:
Internal and external floating-point data items can be passed using a data area. Internal floating-point numbers written to the data area using a DISPLAY statement are converted to external floating-point numbers.
ILE COBOL supports decimal (*DEC), character (*CHAR), logical (*LGL), and DDM (*DDM) data areas. Regardless of the type of data area, information is moved to and from a data area left-justified. When referencing a decimal data area, or a logical data area, the AT position, if specified, must be 1.
Data is moved in packed format to and from a decimal data area. A decimal data area is created with a specified number of total digits and decimal digits. This same number of digits must be declared in an ILE COBOL program accessing the decimal data area. For example:
CRTDTAARA DTAARA(QGPL/DECDATA) TYPE(*DEC) LEN(5 2)
WORKING-STORAGE SECTION. 01 data-value. 05 returned-packed1 pic s9(3)v9(2) packed-decimal. PROCEDURE DIVISION. move 345.67 to returned-packed1. DISPLAY data-value UPON data-area FOR "DECDATA" LIBRARY "QGPL". ACCEPT data-value FROM data-area FOR "DECDATA" LIBRARY "QGPL".
The PIP data area is used by a prestart job. Generally, a prestart job is a job from a remote system under ICF that you start and keep ready to run until you call it.
If you use a prestart job, you do not have to wait for a program that you call to go through job initiation processing. Job initiation is performed before a program can actually start. Because job initiation has already taken place, a prestart job allows your program to start more quickly after the program start request is received.
An ILE COBOL program can access the PIP data area for its job with the ACCEPT statement, using a mnemonic name associated with the function-name PIP-DATA.
The PIP data area is a 2 000-byte alphanumeric item and contains parameters received from a calling program. It provides the program initialization parameters that, in non-prestart jobs, is provided through Standard COBOL parameters.
You use a Format 5 ACCEPT statement to access the PIP data area, similar to the way in which you use a Format 4 ACCEPT statement to read from the local data area. Note that you cannot update the PIP data area using ILE COBOL. See the WebSphere Development Studio: ILE COBOL Reference for detailed syntax information.
For more information regarding prestart jobs and the PIP data area, refer to the CL Programming manual.
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.