Version 6.3.8 for Windows
 —  Dialog Component Reference  —

SET-CLIENT-VALUE Action

This document covers the following topics:


Description

Sets or deletes user-defined ("client") information for a (dialog or) dialog element. Multiple items of information may be stored under different retrieval keys, although each call to this action can only create, update or delete a single value. The information is logically stored in the form of key/value pairs. If a value is deleted, the accompanying key is also removed. I f the dialog element is deleted, all associated client information (if any) is automatically deleted along with it.

The value is stored in the supplied format, without conversion. However, trailing blanks belonging to non-dynamic alphanumeric values are not stored, in order to save space.

Note that this is an alternative to setting the client information via the use of the CLIENT-KEY and CLIENT-VALUE attributes. Both mechanisms manipulate the same information internally, and their use may be intermixed. For example, information set by this action may be retrieved either via the GET-CLIENT-VALUE action or (in general) via the CLIENT-VALUE attribute. However, there are significant benefits to using this action in preference to the attribute-based approach. For more information, please refer to the article Storing and Retrieving Client Data for a Dialog Element.

Top of page

Parameters

Name/Data Type Explanation
HANDLE OF GUI Input

Handle of dialog or dialog element for which the client information is to be set or deleted.

Client value

(any data type)

Input (optional parameter)

If specified, this is the value to be set. If omitted, any existing value is deleted.

Client key (A253) Input (optional parameter)

If specified, this is the key, under which the specified value is to be stored. Any value currently stored under that key for the specified dialog or dialog element is replaced.If this parameter is omitted, the key (if any) specified by the CLIENT-KEY attribute of the specified dialog or dialog element is implicitly used.If the key is empty (i.e., all blank), the request is ignored.

Response (I4) Output

Natural error (if applicable).

Example:

 
/* Set value for (explicit) 'TIME' key for dialog to current time
PROCESS GUI ACTION SET-CLIENT-VALUE WITH #DLG$WINDOW *TIMX 'TIME'  
  GIVING *ERROR 
   
/* Set value for (implicit) 'DATE' key for dialog to current date
#DLG$WINDOW.CLIENT-KEY := 'DATE'
PROCESS GUI ACTION SET-CLIENT-VALUE WITH #DLG$WINDOW *DATX  
  GIVING *ERROR
  
/* Delete value for (implicit) 'TIME' key for dialog
#DLG$WINDOW.CLIENT-KEY := 'TIME'
PROCESS GUI ACTION SET-CLIENT-VALUE WITH #DLG$WINDOW
  GIVING *ERROR


/* Delete value for (explicit) 'DATE' key for dialog
PROCESS GUI ACTION SET-CLIENT-VALUE WITH #DLG$WINDOW 1X 'DATE'  
  GIVING *ERROR 

Top of page