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:
- Change data in a data area using the Progress/400 CHANGE DATA AREA (
chgdara.p
) API. Note that you can send only character data to a data area.- Retrieve information from a data area using the Progress/400 RETRIEVE DATA AREA (
rtvdara.p
) API. Note that you can retrieve only character data from a data area.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 INPUTCHARACTER 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 INPUTCHARACTER The name of the data area on the AS/400. This data area must have been created before using the API. library-name INPUTCHARACTER The library name where the data area resides. start-position INPUTINTEGER 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 INPUTINTEGER The length of the data to be changed in the data area. data-value INPUT/OUTPUTCHARACTER 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 OUTPUTINTEGER A return parameter that indicates whether the entry has been changed.
- 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:
To verify that an entry has been changed, check the value of the OUTPUT parameter. Table 11–10 lists possible return values.
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 INPUTCHARACTER 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 INPUTCHARACTER The name of the data area on the AS/400. This data area must have been created before using the API. library-name INPUTCHARACTER The library name where the data area resides start-position INPUTINTEGER 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 INPUTINTEGER The length of the data to be retrieved from the data area. data-value INPUT/OUTPUTCHARACTER 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 OUTPUTINTEGER A return parameter that indicates whether the entry has been retrieved.
- 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:
To verify that an entry has been retrieved, check the value of the OUTPUT parameter. Table 11–12 lists possible return values.
Data Area Coding Example
The following example code illustrates how to change and retrieve entries from a data area:
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |