Progress/400
Product Guide


Data Area Support

Progress/400 DataServer allows you to perform operations on data areas from within a Progress client session. You can perform two types of operations:

Using these APIs insulates your code from possible changes to the underlying method of changing and retrieving data from data areas and provides a standard interface that does not change. You use them in the same way regardless of whether your code is being run from the remote client or from the native clients.

Progress/400 supports the change and retrieve operations by providing the QDTAARA table definition in the Progress/400 schema. This table is similar to the QCMD table in that it controls the function of Progress/400, but different in that data can be sent to and received from data areas. More than one job can place data onto or receive data from a particular data area.

NOTE: Do not use the QDTAARA name as a physical filename: the SYNC function updates the file on the client, making the data area APIs unusable.

Before you can place information into a data area, you must create the data area using the OS/400 Create Data Area (CRTDTAARA) command. To display the data area, use the OS/400 Display Data Area (DSPDTAARA) command. For detailed information about OS/400 data area access routines, see the IBM OS/400 Control Language Programmer’s Guide .

Progress displays error messages to the remote client session, with more detailed error information available in the OS/400 job log (assuming that the server is started with logging), or in the native client’s job log, as appropriate.

NOTE: Progress/400 does not support accessing the following two types of data areas: *GDA (Group Data Area), *PDA (Pre-start Data Area).

CHANGE DATA AREA (chgdara.p) API

Table 11–9 describes the parameters that you must pass to the CHANGE DATA AREA API. You can use the same variable names or names of your own choice. Note that you must pass all of these parameters to the API, and they must be in the same order as in Table 11–9.

Table 11–9: CHANGE DATA AREA (chgdara.p) Parameters 
Parameter Name
Parameter Type and Data Type

Value
db-name
INPUT
CHARACTER
The name of a connected DB2/400 database that contains the QDTAARA table. The database must be connected before the call to the API because an alias will be defined for the database that allows any DB2/400 database to use the API.
area-name1
INPUT
CHARACTER
The name of the data area on the AS/400. This data area must have been created before using the API.
library-name
INPUT
CHARACTER
The library name where the data area resides.
start-position
INPUT
INTEGER
The starting position of the data to be changed in the data area. The starting position is 1 based, so the first position in the data area is 1.
data-length
INPUT
INTEGER
The length of the data to be changed in the data area.
data-value
INPUT/OUTPUT
CHARACTER
The data to be placed into the data area. A data area can support a character string as long as 2000 characters, 1024 for *LDA.
status
OUTPUT
INTEGER
A return parameter that indicates whether the entry has been changed.
  1. You can use *LDA for area-name. When you use *LDA, you must blank out library-name. The *LDA value specifies that the contents of the local data area are changed. The local data area is automatically associated with your job on the AS/400 by the operating system (OS/400) and is 1024 characters long. For more detailed information on the use of *LDA, see the “Local Data Area” section in the CL Programmer’s Guide of the IBM documentation.

The following example illustrates calling the CHANGE DATA AREA API from your code:

RUN as4dict/chgdara.p (INPUT db-name, INPUT area-name,
                       INPUT library-name, INPUT start-pos,
                       INPUT data-length, INPUT/OUTPUT data-value,
                       OUTPUT status), 

To verify that an entry has been changed, check the value of the OUTPUT parameter. Table 11–10 lists possible return values.

Table 11–10: CHANGE DATA AREA (chgdara.p) Return Values 
Status
Reason
Client
0
The entry has been placed in the data area.
Remote and native
-1
Either the DB2/400 database name is incorrect or the database is not connected.
Remote only
-2
The named DB2/400 database does not contain the QDTAARA table.
Remote only
-3
The start position must be greater than zero.
Remote and native
-4
The data length must be less than 2000.
Remote and native
-5
The start position plus the data length minus 1 must be less than or equal to 2000.
Remote and native
-6
A general error occurred.
Native only

RETRIEVE DATA AREA (rtvdara.p) API

Table 11–11 describes the parameters that you must pass to the RETRIEVE DATA AREA API. You can use the same variable names or names of your own choice. Note that you must pass all of these parameters to the API, and they must be in the same order as in Table 11–11.

Table 11–11: RETRIEVE DATA AREA (rtvdara.p) Parameters 
Parameter Name
Parameter Type and Data Type

Value
db-name
INPUT
CHARACTER
The name of a connected DB2/400 database that contains the QDTAARA table. The database must be connected before the call to the API because an alias will be defined for the database that allows any DB2/400 database to use the API.
area-name1
INPUT
CHARACTER
The name of the data area on the AS/400. This data area must have been created before using the API.
library-name
INPUT
CHARACTER
The library name where the data area resides
start-position
INPUT
INTEGER
The starting position of the data to be retrieved from the data area. The starting position is 1 based, so the first position in the data area is 1.
data-length
INPUT
INTEGER
The length of the data to be retrieved from the data area.
data-value
INPUT/OUTPUT
CHARACTER
The data to be retrieved from the data area. A data area can support a character string as long as 2000 characters, 1024 for *LDA.
status
OUTPUT
INTEGER
A return parameter that indicates whether the entry has been retrieved.
  1. You can use *LDA for area-name. When you use *LDA, you must blank out library-name. The *LDA value specifies that the contents of the local data area are changed. The local data area is automatically associated with your job on the AS/400 by the operating system (OS/400) and is 1024 characters long. For more detailed information on the use of *LDA, see the “Local Data Area” section of the CL Programmer’s Guide in the IBM documentation.

The following example illustrates calling the RETRIEVE DATA AREA API from your code:

RUN as4dict/rtvdara.p (INPUT db-name, INPUT area-name,
                       INPUT library-name, INPUT start-pos,
                       INPUT data-length, INPUT/OUTPUT data-value,
                       OUTPUT status), 

To verify that an entry has been retrieved, check the value of the OUTPUT parameter. Table 11–12 lists possible return values.

Table 11–12: RETRIEVE DATA AREA (rtvdara.p) Return Values 
Status
Reason
Client
0
The entry has been retrieved from the data area.
Remote and native
-1
Either the DB2/400 database name is incorrect or the database is not connected.
Remote only
-2
The named DB2/400 database does not contain the QDTAARA table.
Remote only
-3
The start position must be greater than zero.
Remote and native
-4
The data length must be less than 2000.
Remote and native
-5
The start position plus the data length minus 1 must be less than or equal to 2000.
Remote and native
-6
A general error occurred.
Native only

Data Area Coding Example

The following example code illustrates how to change and retrieve entries from a data area:

DEFINE VARIABLE db-name AS CHARACTER NO-UNDO.
DEFINE VARIABLE area-name AS CHARACTER NO-UNDO.
DEFINE VARIABLE lib-name AS CHARACTER NO-UNDO.
DEFINE VARIABLE data-length AS INTEGER NO-UNDO.
DEFINE VARIABLE data-value AS CHARACTER NO-UNDO.
DEFINE VARIABLE stat AS INTEGER NO-UNDO.

ASSIGN db-name = "mydb"
       area-name = "mydataarea"
       lib-name = "mydb"
       data-value = "Changing data in data area"
       data-length = LENGTH(data-value).


/* An example of sending an entry to a data area */
RUN as4dict/chgdara.p (INPUT db-name, INPUT area-name,
                       INPUT lib-name, INPUT data-length,
                       Input-Output data-value,
                       OUTPUT stat).

/* If the entry was changed in the data area,          */
/* the value of stat will equal the length of the data */
IF stat = LENGTH(data-value) THEN DO:
   ASSIGN data-value = "".

/* An example of retrieving an entry from a data area */
RUN as4dict/rtvdara.p (INPUT db-name, INPUT area-name,
                       INPUT lib-name, INPUT data-length,
                       Input-Output data-value,
                       OUTPUT stat).

IF stat > 0 THEN
   DISPLAY data-value WITH FRAME entry NO-LABELS.
ELSE
   DISPLAY stat WITH FRAME status NO-LABELS.

END 


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095