Data Areas

Data Areas

Data areas are persistent named storage outside of any single program. On IBM i they are system objects; in OpenRPG they are plain files, one per data area, in the directory $RPGC_DA_DIR names (by default ~/.rpgc/da).

Declare a Data Area Variable

Add DTAARA to a DCL-S. The data area's name is quoted, as on IBM i:

// *LDA — the Local Data Area (one per job/process)
DCL-S LdaData CHAR(256) DTAARA(*LDA);

// Named data area: a name of at most 10 characters (IBM: RNF0653)
DCL-S Config CHAR(100) DTAARA('APPCONFIG');

// Unquoted, DTAARA names a variable that holds the data area's name,
// which may include a library: 'MYLIB/APPCONFIG'
DCL-S daName CHAR(21) INZ('APPCONFIG');
DCL-S Config2 CHAR(100) DTAARA(daName);

// DTAARA alone uses the field's own name: data area SETTINGS
DCL-S Settings CHAR(100) DTAARA;

DTAARA on a data structure (DCL-DS ... DTAARA) is not supported yet.

IN — Read from Data Area

IN LdaData;
DSPLY %TRIM(LdaData);

IN *LOCK name reads and locks, as on IBM i. IN *DTAARA reads every data area the program defines.

OUT — Write to Data Area

A named data area must be locked before OUT writes it, as on IBM i: read it with IN *LOCK first. OUT releases the lock; OUT *LOCK writes and keeps it. The local data area needs no lock:

LdaData = 'SESSION_ID=ABC123';
OUT LdaData;                  // *LDA: no lock needed

IN *LOCK Config;
Config = 'VERSION=2.0';
OUT Config;                   // writes, and releases the lock

UNLOCK — Release the Lock

UNLOCK releases a lock taken by IN *LOCK (or kept by OUT *LOCK); UNLOCK *DTAARA releases every one. Unlocking a data area that is not locked is not an error. The local, group and program-initialization data areas (*LDA, *GDA, *PDA) are never locked, and IBM i rejects UNLOCK of them (RNF7091).

Errors

An error on IN, OUT or UNLOCK ends the program, as on IBM i, unless MONITOR handles it or the operation has the (E) extender, which sets %ERROR and %STATUS instead:

Status	Meaning
401	The data area does not exist
412	OUT to a data area that is not locked
413	The data area could not be written
415	The data area could not be read

IN(E) Config;
IF %ERROR;
  DSPLY ('status ' + %CHAR(%STATUS));   // 401 if Config does not exist
ENDIF;

IN *LOCK Config;
// ... use Config ...
UNLOCK Config;

Round-Trip Example

DCL-S LdaData CHAR(20) DTAARA(*LDA);

LdaData = 'HELLO DATA AREA     ';
OUT LdaData;

LdaData = '';      // clear local copy
IN LdaData;        // read back from storage

DSPLY %TRIM(LdaData);   // HELLO DATA AREA

Named Data Areas

DCL-S MyConfig CHAR(50) DTAARA('RPGCONFIG');

IN *LOCK MyConfig;
MyConfig = 'VERSION=2.0';
OUT MyConfig;

MyConfig = '';
IN MyConfig;
DSPLY %SUBST(MyConfig: 1: 11);   // VERSION=2.0

A named data area must exist before a program reads or locks it, as on IBM i, where CRTDTAARA creates it. Here, create its file in the data area directory, e.g. printf '%-50s' '' > ~/.rpgc/da/RPGCONFIG.