🚀 Mastering Uniface `putitem`: Your Complete Guide to List Management

With AI assistance, this comprehensive guide is based on the official Uniface 10.4 documentation

📋 What is putitem?

The putitem statement is a powerful Uniface command that allows you to add or replace items in both indexed lists and associative lists. Whether you're working with simple value lists or complex key-value pairs, putitem is your go-to tool for dynamic list manipulation.

🎯 Syntax Overview

Uniface offers two primary syntax formats for putitem:

For Indexed Lists:

putitem IndexedList, Index, ItemValue

For Associative Lists:

putitem/id{/case} AssociativeList, ItemId {, ItemValue}

Example:

putitem/id vList, "NS", "Nova Scotia"

⚙️ Qualifiers Explained

Qualifier	Description
/id	Add or replace the list item identified by ItemId in an associative list
/case	Ensure that ItemId matches the case of the item id in the associative list

📊 Parameters Breakdown

Parameter	Data Type	Description
IndexedList/AssociativeList	String	Variable or field containing the Uniface list to be modified
Index	Number	Sequence number (-1 for append, >0 for specific position)
ItemId	String	Id part of the list item to be updated
ItemValue	String	Value part of the list item to be updated

🔄 Return Values

The putitem statement returns status information in $status:

• 0: No item was replaced or added (specified source is empty)
• >0: Sequence number of the list item that was replaced or added

📝 Working with Indexed Lists

For indexed lists, use putitem without qualifiers. Key behaviors include:

• -1: Appends item to the end of the list
• 0 or <-1: Item is not added
• >list length: Creates empty items until the specified position

🛠️ Example: Building an Indexed List

; Initialize list:
$valrep(DBMSFLD) = "mss"

; Append list items:
putitem $valrep(DBMSFLD), -1, "ora"
; Result: ValRep is "mss;ora"

putitem $valrep(DBMSFLD), -1, "syb"
; Result: ValRep is "mss;ora;syb"

putitem $valrep(DBMSFLD), -1, "db2"
; Result: ValRep is "mss;ora;syb;db2"

getitem vItem, $valrep(DBMSFLD), 3
; Result: vItem is "syb"

🏷️ Working with Associative Lists

For associative lists, use the /id qualifier to work with key-value pairs:

Case Sensitivity:

• Default: Case-insensitive matching
• With /case: Case-sensitive matching

🔧 Example: Building an Associative List

; Initialize the list and append items:
$valrep(DATEFLD) = "mon=monday"
putitem/id $valrep(DATEFLD), "tue", "tuesday"
putitem/id $valrep(DATEFLD), "wed", "wednesday"
putitem/id $valrep(DATEFLD), "weekend", "sat;sun"
; Result: ValRep is "mon=monday;tue=tuesday;wed=wednesday;weekend=sat!;sun"

; Copy "tuesday" to $1
getitem/id $1, $valrep(DATEFLD), "tue"

; Copy "sat;sun" to $2
getitem/id $2, $valrep(DATEFLD), "weekend"

; Copy "sat" to $3
getitem $3, $2, $1

💡 Pro Tips

🎯 Quick List Initialization

You can set initial values using simple assignment:

$valrep(DBMSFLD) = "rms;ora;syb;db2"

⚠️ Empty List Behavior

Remember that an empty list cannot be distinguished from a list containing a single empty item. Empty items added to empty lists keep the list empty, while empty items added to non-empty lists create actual empty entries.

🎉 Conclusion

The putitem statement is an essential tool in the Uniface developer's toolkit. Whether you're managing database field representations, building dynamic user interface elements, or handling complex data structures, mastering putitem will significantly enhance your Uniface development efficiency.

Remember to choose the appropriate syntax based on your list type, and don't forget about the powerful qualifier options for fine-tuned control over your list operations! 🚀

📚 Based on official Uniface 10.4 documentation