Progress/400
Product Guide


User Space Support

A user space is a permanent object that consists of a collection of bytes used for storing user-defined information. Progress/400 uses user spaces to store large amounts of data and pass this data from job to job or from system to system. Progress/400 allows you to perform operations on user spaces 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 user spaces and provides a standard interface that does not change. You use them in the same way regardless of whether the code is being run from the remote client or from the native clients.

Progress/400 supports the change and retrieve operations by providing the QUSRSPC table definition in the Progress/400 schema. This table is similar to the QCMD table in that it controls the function of the Progress/400 DataServer, but different in that information can be changed in and retrieved from QUSRSPC.

NOTE: Do not use the QUSRSPC name as a physical file name: the SYNC function updates the file on the client, making the user space APIs unusable.

Note that if you retrieve numeric data or pointers stored in the user space, you must use the SUBSTRING function on the contents of the returned buffer in order to display the data. This is because if Progress encounters a null within the returned numeric or pointer data, it interprets this as the end of the buffer and no further information is displayed. For additional information on using the SUBSTRING function, see the "Using the LOOKUP and SUBSTRING Functions with Send Data" section.

Before you can place information into a user space, you must create the user space using the OS/400 Create User Space (QUSCRTUS) command. For detailed information about OS/400 user space access routines, see the IBM OS/400 System API Reference .

Progress displays error messages in the Progress client session, and more detailed information might be available in the OS/400 job log.

CHANGE USER SPACE (chguspc.p) API

Table 11–13 describes the parameters that you must pass to the CHANGE USER SPACE 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–13.

Table 11–13: CHANGE USER SPACE (chguspc.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 QUSRSPC 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.
uspc-name
INPUT
CHARACTER
The name of the user space on the AS/400. This user space must have been created before using the API.
library-name
INPUT
CHARACTER
The library name where the user space resides.
start-position
INPUT
INTEGER
The starting position of the data to be changed in the user space. The starting position is 1 based, so the first position in the user space is 1.
data-length
INPUT
INTEGER
The length of the data to be changed in the user space.
data-value
INPUT/OUTPUT
CHARACTER
The data to be placed into the user space. A user space can support up to 16 megabytes of information; however, this utility allows you to access only 2048 bytes at one time.
status
OUTPUT
INTEGER
A return parameter that indicates whether the entry has been changed.

The following example illustrates calling the CHANGE USER SPACE API from your code:

RUN as4dict/chguspc.p (INPUT db-name, INPUT uspc-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–14 lists possible return values.

Table 11–14: CHANGE USER SPACE (chguspc.p) Return Values 
Status
Reason
Client
#
The length of the data entry. This number is either 0, which means the entry was not changed, or the length of the data.
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 QUSRSPC table.
Remote only
-3
The start position must be greater than zero.
Remote and native
-4
The data length must be less than 2048.
Remote and native

RETRIEVE USER SPACE (rtvuspc.p) API

Table 11–15 describes the parameters that you must pass to the RETRIEVE USER SPACE 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–15.

Table 11–15: RETRIEVE USER SPACE (rtvuspc.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 QUSRSPC 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.
uspc-name
INPUT
CHARACTER
The name of the user space on the AS/400. This user space must have been created before using the API.
library-name
INPUT
CHARACTER
The library name where the user space resides.
start-position
INPUT
INTEGER
The starting position of the data to be retrieved from the user space. 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 user space.
data-value
INPUT/OUTPUT
CHARACTER
The data to be retrieved from the user space. A user space can support up to 16 megabytes of information; however, this utility allows you to access only 2048 bytes at one time.
status
OUTPUT
INTEGER
A return parameter that indicates whether the entry has been retrieved.

The following example illustrates calling the RETRIEVE USER SPACE API from your code:

RUN as4dict/rtvuspc.p (INPUT db-name, INPUT uspc-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–16 lists possible return values.

Table 11–16: RETRIEVE USER SPACE (rtvuspc.p) Return Values 
Status
Reason
Client
#
The length of the data entry. This number is either 0, which means the entry was not changed, or the length of the data.
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 QUSRSPC table.
Remote only
-3
The start position must be greater than zero.
Remote and native
-4
The data length must be less than 2048.
Remote and native

User Space Coding Example

The following example code illustrates how to change and retrieve entries from a user space:

DEFINE VARIABLE db-name AS CHARACTER NO-UNDO.
DEFINE VARIABLE uspc-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"
       uspc-name = "myuserspc"
       lib-name = "mydb"
       data-value = "Changing data in user space"
       data-length = LENGTH(data-value).

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

/* If the entry was changed in the user space,         */
/* 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 user space */
RUN as4dict/rtvuspc.p (INPUT db-name, INPUT uspc-name,
                       INPUT lib-name, INPUT data-length,
                       Input-Output data-value,
                       OUTPUT stat).

IF stat = LENGTH(data-length) 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