AS/400-iSeries Starter Kit

I'd like to have a dollar for every time I've put something in a special place only to forget where I put it. Someone living in my old house in Florida will someday find that special outlet adaptor I never used. He will probably also find the casters I removed from the baby bed, a stash of new golf balls, and several little metal doohickeys I removed from the back of my PS/2 when I installed feature cards. I hope he gets some use out of them!

This tendency to misplace things also finds its way into the world of computer automation; but fortunately for those of us who need a place to keep some essential chunk of information, OS/400 provides a simple solution. If you ever write applications that use data such as the next available order number, the current job step in progress for a long-running job, a software version identification number, or a serial number, you should know about OS/400 data areas.

A data area is an AS/400 object you can create to store information of a limited size. A data area exists independently of programs and files and therefore can be created and deleted independently of any other objects on the system. Data areas typically are used to store some incremental number. For instance, a payroll application might use a data area to store the next available check number. Each time the application writes or records a check, it can get the next check number from the data area and then update the data area to reflect the use of that check number.

Another use for data areas is to emulate the S/36's IF-ACTIVE feature, which lets you check a program's execution status. You can create and name a data area for each program whose status you need to know. For example, if PRP101 is a program to be checked, you can create a data area named PRP101 in a user library. Then you can modify program PRP101 to acquire a shared update (*SHRUPD) lock on the data area using the ALCOBJ (Allocate Object) command. An application needing to check the execution status of program PRP101 can simply try to acquire an exclusive (*EXCL) lock on the data area. If the allocation attempt fails, it means the data area object is currently allocated by program PRP101, indicating that the program is active.

Creating a Data Area

The best way to acquaint you with data areas is to walk you through the process of creating one. To create a data area object named MYDTAARA in library QGPL and initialize it with the value 'ABCDEFGHI'', you would type the following command:

CRTDTAARA DTAARA(QGPL/MYDTAARA) TYPE(*CHAR)  LEN(10)  +
          VALUE('ABCDEFGHIJ') TEXT('Data Area to +
          store ABCDEFGHIJ')

This data area object can contain 10 characters of data and can be referenced by any user or program authorized to use library QGPL. Notice that you can specifically identify the data area with the TEXT parameter on the CRTDTAARA (Create Data Area) command. Just as you may forget where you've placed a special object in your home, you can easily forget what you've created a data area for. Wise use of the TEXT parameter can help you effectively document data area objects.

Besides CRTDTAARA, other OS/400 commands associated with data areas are the DSPDTAARA (Display Data Area), CHGDTAARA (Change Data Area), RTVDTAARA (Retrieve Data Area), and DLTDTAARA (Delete Data Area) commands. Suppose you wanted to display the data area we just created. You would execute the following command:

DSPDTAARA QGPL/MYDTAARA

The system would then display the description and contents of the data area on your workstation.

You can use the CHGDTAARA command interactively or from within a program. The DTAARA parameter on this command lets you either replace the contents of a data area or change only a portion (substring) of the data area. For example, the command

CHGDTAARA DTAARA(QGPL/MYDTAARA) VALUE('123')

would replace the entire contents of the data area. If the value being placed into the return variable is shorter than the return variable, the value is padded to the right with blanks. Therefore, the new value of the data area would be '123 '. However, the command

CHGDTAARA DTAARA(QGPL/MYDTAARA (1 3)) VALUE('123')

replaces only the first three positions of the data area with the value '123'. Thus, the original value of MYDTAARA would be modified to '123DEFGHIJ'.

The RTVDTAARA command provides a simple way for CL programs to retrieve the data area value. Because the command provides return variables, it can be executed only from within a CL program. Here again, the DTAARA parameter lets you reference all or only a portion of the data area. The CL program statement

RTVDTAARA DTAARA(QGPL/MYDTAARA) RTNVAR(&ALL)

would retrieve the entire contents of MYDTAARA ('ABCDEFGHIJ') into return variable &ALL, starting in the left-most position of the return variable. Now consider the following CL program statement:

RTVDTAARA DTAARA(QGPL/MYDTAARA (4 2)) RTNVAR(&JUST2)

This RTVDTAARA command retrieves from MYDTAARA a substring of two characters, starting with position 4. The variable &JUST2 would return the value 'DE'.

One performance tip to remember when using the RTVDTAARA command is that it is more efficient to retrieve the entire data area into a single CL variable and use several CHGVAR (Change Variable) commands to pull substrings from that variable than it is to execute several RTVDTAARA commands to retrieve multiple substrings. Every RTVDTAARA command must access the data area -- a time-consuming operation.

To delete this data area from your system, type the command

DLTDTAARA QGPL/MYDTAARA

You can also use high-level language programs to retrieve and modify data area values. Figure 33.1 provides sample RPG/400 code to retrieve information from a data area named INPUT. In this example, the program implicitly reads and locks the data area when the program is initialized and then implicitly writes and unlocks it when the program ends. During program execution, the INPUT data area data structure defines fields internally to the program. RPG's DEFN, IN, and OUT opcodes provide a method for explicitly retrieving and updating a data area and for explicitly controlling the lock status of a data area object. For more information about how to use these opcodes with data areas, see IBM's AS/400 Languages: RPG/400 Reference (SC09-1349) and AS/400 Languages: RPG/400 User's Guide (SC09-1348).

Local Data Areas

A local data area (LDA) is a special kind of data area automatically created for each job on the system. The LDA is a character-type data area 1,024 characters long and initialized with blanks. As long as the job is running, the LDA is associated with that job. When one job submits another job, the system creates an LDA for the submitted job and copies the contents of the submitting job's LDA into it. Thus, you can pass a data string from a given job to every job it submits.

Unlike the data area object discussed earlier, the LDA is dependent on a particular job; it cannot be displayed or modified by any other job on the system. You cannot manually create or delete an LDA, nor does it have an associated library (not even QTEMP). The LDA is simply maintained as part of the job's process access group (a group of internal objects that is associated with a job and that holds essential information about that job).

The RTVDTAARA statements in Figure 33.2 retrieve two substrings from the LDA, putting the first into variable &FIELD1 and the second into &FIELD2. The CHGDTAARA command replaces positions 101 through 150 of the LDA with the value of variable &NEWVAL. You can perform any number of retrievals and changes on the LDA; however, keep in mind that only one copy of the LDA exists for each job.

The LDA is often used to store static information that must be available to many different programs executed within a job. For example, when an employee signs on to a workstation, an initial program might retrieve information relating to that employee (e.g., branch number or employee number) and put it into the LDA. Any subsequent programs the job invokes that require this information can simply retrieve it from the LDA rather than performing additional file I/O.

Group Data Areas

If an interactive job becomes a group job (via the CHGGRPA (Change Group Attributes) command), the system creates an additional data area called the group data area (GDA). Similar to the LDA, the GDA is a blank-initialized character-type data area, but it is only 512 characters long. The GDA is accessible from any job in the group and is deleted when the last job in the group has ended or when the job is no longer part of a group job.

You cannot create or delete a GDA (although you can modify it), and it has no associated library. Another unique limitation is that you cannot use it in a substring function on a parameter. However, you can retrieve the entire GDA and then use the CHGVAR command to reference particular portions of the data. For jobs that run as group jobs, the GDA simply provides additional temporary storage (beyond the LDA that exists for each job).

These are the basics you need to begin exploring OS/400 data areas. As you begin to think of reasons to use data areas on your system, you may want to look at data areas that already exist there. Check your libraries to see whether your software provider has supplied any data areas. If so, how are they used? You may discover that you have used OS/400 data areas all along.