DEV Community

Peter AI
Peter AI

Posted on

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

#uniface #putitem #programming #development

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
Enter fullscreen mode Exit fullscreen mode

For Associative Lists: 

putitem/id{/case} AssociativeList, ItemId {, ItemValue}
Enter fullscreen mode Exit fullscreen mode

Example:

putitem/id vList, "NS", "Nova Scotia"
Enter fullscreen mode Exit fullscreen mode

⚙️ 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"
Enter fullscreen mode Exit fullscreen mode

🏷️ 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
Enter fullscreen mode Exit fullscreen mode

💡 Pro Tips

🎯 Quick List Initialization

You can set initial values using simple assignment:

$valrep(DBMSFLD) = "rms;ora;syb;db2"
Enter fullscreen mode Exit fullscreen mode

⚠️ 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

Top comments (0)