DATA AREAS

A data area is a persistent (permanent) location on the computer that is used to store information. A data area is separate from a program and can be used for communication between program modules.

Data areas are communicated between modules through system functions and RPG operations. Unlike parameters, the data contained in the data area is never passed between modules. Instead, a data area is retrieved from the system and a copy of its data is placed into a field or data structure within the procedure. Any manipulation of the data is performed on the program's copy of the data. The data area is updated with new information when data is written to the data area.

Data areas can be implicitly or explicitly read and written. A data area is implicitly read and written at the start and end of a program by defining a data structure as a data area data structure. The DTAARA keyword is used to associate a field, data structure, or data structure subfield with a data area. The name of the data area is specified as the parameter of the DTAARA keyword. See Figure 9.23.

Figure 9.23: Data area declarations.

Once a data area is associated with a program variable, the data area can be read and written. The RPG data area operation codes IN, OUT, and UNLOCK are used to access data areas. Factor 2 of these operations must contain the name of the program variable that is associated with the data area (not the data area name itself).

Data Area Data Structures

To define an implicit data area read/write, the data structure must be defined as a cycle-controlled data structure (see Figure 9.24). The letter U in position 23 of the data structure name definition specification identifies the data structure as a cycle-controlled data area data structure. When the letter U is specified, the RPG compiler generates code that automatically reads the data area's content into the data structure when the program is first called, and automatically writes the content of the data structure to the data area when the program ends. This code (the letter U) is a carry-over from the RPG II language.

 .....DName+++++++++++EUDS.......Length+TDc.Functions++++++++++++++++++++++++++++ 0001 D MyDataArea     UDS                  DTAARA(LastUsed) 0002 D  l_CustNo                      7S 0 0003 D  l_InvNo                       7S 0 0004 D  l_AcctNo                      7S 0 

Figure 9.24: Data area data structure specification.

When a data area data structure is defined, RPG implicitly retrieves the data area into the data structure when the program is started and writes the data structure to the data area when the program ends. If the data area doesn't exist when the program is run, it is created. On the AS/400, the data area is created in the QTEMP library with the same properties (e.g., name, length, type) as the corresponding data structure. If the DTAARA keyword is not specified, the name of the data structure is used as the name for the data area.

A data area data structure, like all data structures, can be externally described. Specify the letter E in position 22 of the data structure name definition specification. Optionally, the EXTNAME keyword can be used to name an externally described database file on which the format of the data structure is based. If the EXTNAME keyword is not specified, the name of the data structure is used as the name of the externally described database file. See Figure 9.25.

 .....DName+++++++++++EUDS.......Length+TDc.Functions++++++++++++++++++++++++++++ 0001 D MyDataArea    EUDS                  DTAARA(LastUsed) 0002 D                                     EXTNAME(LUFmt)  PREFIX(LU_ : 2) 

Figure 9.25: Externally described data area.

Figure 9.25 defines a data area data structure named MYDATAAREA. The data area is externally described. Its format is based on the record format of the LUFMT database file. The name of the data area is LASTUSED.

Note the use of the PREFIX keyword (line 2). This keyword causes the renaming of every field of the LUFMT. In this example, the first two characters of the external field name are removed, and then the leading characters 'LU_' are appended to the field name. Hence, a field named LUCUSTNO is renamed to LU_CUSTNO.

IN and OUT Operation

Data areas can be explicitly read and written with the IN and OUT operations. Four RPG operations provide complete access to data areas:

• DEFINE — Assigns a host variable that is used to transfer data between the data area and the program. This is functionally equivalent to the DTAARA keyword.

• IN — Reads the data area's data and stores it in the associated host variable. The host variable is specified in factor 2 of this operation.

• OUT — Writes the contents of the host variable to the data area. The host variable is specified in factor 2 of this operation.

• UNLOCK — Releases the data area from a locked state.

The DEFINE operation names a data area and associates a field, data structure, or data structure subfield to the data area. That field is referred to as a host variable. It is where the data area's data is stored when an IN operation is used to read the data area. It is also the source of the data written to the data area by an OUT operation.

The IN operation reads one or all data areas defined in the program into their associated host variables. Factor 2 identifies the data area(s) to be read. If factor 2 contains the name of a host variable, its associated data area is copied into the host variable. If factor 2 contains *DTAARA, all data areas defined in the program are read into their associated host variables.

Factor 1 can be used to control object locking on the data area. By specifying *LOCK in factor 1, the data area associated with the host variable specified in factor 2 is locked by the program. The data area remains locked until an OUT operation is performed. Optionally, the UNLOCK operation can be used to release the lock.

The OUT operation writes the data contained in the data area's host variable to the data area. The name of the data area's host variable is specified in factor 2. If factor 2 contains the *DTAARA option, all data areas defined in the program are written. If factor 1 is blank, any lock placed on the data area is released when the data area is written. If factor 1 contains the *LOCK option, the data area lock is not released.

Figure 9.26 shows a data area data structure. The data structure name definition (line 1) contains the DTAARA keyword and the U in position 23. The program automatically reads the COMPINFO data area when the program starts. The data area's data is copied to the HOSTDS data structure.

 .....DName+++++++++++EUDS.......Length+TDc.Functions++++++++++++++++++++++++++++ 0001 D HostDS         UDS                  DTAARA(CompInfo) 0002 D  CompName                     35A 0003 D  Rpt_Title                    50A 

Figure 9.26: Data area data structure.

Figure 9.27 illustrates an assignment of a data area to a host data structure. Position 23 of line 1 is blank. Therefore, the data area is not automatically read and written when the program starts and ends. The IN operation (line 4) reads the COMPINFO data area into the HOSTSTUC data structure.

 .....DName+++++++++++EUDS.......Length+TDc.Functions++++++++++++++++++++++++++++ 0001 D HostStruc       DS                  DTAARA(CompInfo) 0002 D  CompName                     35A 0003 D  Rpt_Title                    50A .....CSRn01Factor1+++++++OpCode(ex)Factor2+++++++Result++++++++Len++DcHiLoEq.... 0004                     IN        HostStruc 

Figure 9.27: Data structure as data area host variable.

Figure 9.28 illustrates an assignment of a data area to a host field. Line 1 contains the definition for the NEXTCUST field. It is a stand-alone field, with the DTAARA keyword identifying the data area to be assigned. The CUSTNUMBER data area is assigned (line 1) to the NEXTCUST field. The IN operation (line 2) is used to read the data area's data into the NEXTCUST field. Note that, once a data area is assigned to a host variable, only the host variable is referenced in the data area operations.

 .....DName+++++++++++EUDS.......Length+TDc.Functions++++++++++++++++++++++++++++ 0001 D NextCust        S              7S 0 Dtaara(CustNumber) .....CSRn01Factor1+++++++OpCode(ex)Factor2+++++++Result++++++++Len++DcHiLoEq.... 0002 C     *LOCK         IN        NextCust 0003 C                   Eval      NextCust = NextCust +1 0004 C     *LOCK         OUT       NextCust 

Figure 9.28: Stand-alone field as data area host variable.

On line 3, the host variable is modified. Then, on line 4, the host variable is written out to the data area. Note that the *LOCK option is specified on line 4. This maintains the lock on the data area, preventing others from modifying it while this program is running.

Figure 9.29 shows an assignment of a data area to a host data structure subfield. Line 2 contains the subfield declaration. It is a subfield of the TEXT data structure (line 1). The IN operation (line 3) is used to read the data area's data into the NEXTACCT subfield.

 .....DName+++++++++++EUDS.......Length+TDc.Functions++++++++++++++++++++++++++++ 0001 D Text            DS 0002 D   NextAcct                     7S 0 Dtaara(CustNumber) .....CSRn01Factor1+++++++OpCode(ex)Factor2+++++++Result++++++++Len++DcHiLoEq.... 0003                     IN        NextAcct 

Figure 9.29: Data structure subfield as data area host variable.

Figure 9.30 illustrates an assignment of a data area to a host field. This technique uses the DEFINE operation for this association. In Figure 9.30, line 2 is similar to line 1 in Figure 9.28. A stand-alone field is associated with the data area. However, the DEFINE operation instead of the DTAARA keyword is use to perform the association. The DEFINE operation is included in RPG IV for compatibility with prior versions of RPG. The DTAARA technique shown in Figure 9.28 is the preferred RPG IV technique.

 .....DName+++++++++++EUDS.......Length+TDc.Functions++++++++++++++++++++++++++++ 0001 D NextNum         S              7S 0 .....CSRn01Factor1+++++++OpCode(ex)Factor2+++++++Result++++++++Len++DcHiLoEq.... 0002 C     *DTAARA       Define    CustNumber    NextNum 0003 C     *LOCK         IN        NextNum 0004 C                   Eval      NextNum = NextNum +1 0005 C     *LOCK         OUT       NextNum 

Figure 9.30: The DEFINE operation used in defining data area.