DEV Community

Peter + AI
Peter + AI

Posted on

🚀 Mastering Uniface putlistitems: Your Guide to Efficient Data List Management

#uniface #procscript #datalists #programming

Hey developers! 👋 Today I'm diving deep into one of Uniface's most powerful data manipulation commands: putlistitems. This comprehensive guide is based on the official Uniface Documentation 10.4, and I had some AI assistance to make this as clear and practical as possible.

🎯 What is putlistitems?

The putlistitems statement is your go-to tool for copying data from fields, variables, or entities into lists. Whether you're working with indexed lists (simple value sequences) or associative lists (ID=value pairs), this command has you covered!

📝 Basic Syntax

Here are the main syntax variations:

putlistitems IndexedList, Source
putlistitems/id AssociativeList {, Source}
putlistitems/id {/field | /component | /global} AssociativeList
putlistitems/occ {/modonly} AssociativeList, Entity
Enter fullscreen mode Exit fullscreen mode

🔧 Key Qualifiers Explained

/id - Building Associative Lists

Perfect for creating ID=value pair lists from your data sources.

/field, /component, /global

These qualifiers let you specify exactly what type of source you're working with - field data, component variables, or global variables.

/occ - Entity Field Mapping

Copies all fields from a specified entity into an associative list automatically.

/modonly - Modified Fields Only

Super efficient! Only processes fields that have been modified.

💡 Practical Examples

🗓️ Building an Indexed List 

; Extract days from CALENDAR entity
setocc "CALENDAR", 1
putlistitems vItem, DAY.CALENDAR
; Result: "Monday;Tuesday;Wednesday"
Enter fullscreen mode Exit fullscreen mode

🏷️ Creating Associative Lists 

; Build ID=value pairs from two fields
setocc "ENT", 1
putlistitems/id vList, FLD1, FLD2
; Result: "day1=Mon;day2=Tue;day3=Wed"
Enter fullscreen mode Exit fullscreen mode

⚡ Dynamic Value Updates 

NAME = "Frodo"
$CPT_TOT$ = 14
$$GLOB_TOT = 329

vList = "NAME;$CPT_TOT$;$$GLOB_TOT"
putlistitems/id vList 
; Result: "NAME=Frodo;$CPT_TOT$=14;$$GLOB_TOT=329"
Enter fullscreen mode Exit fullscreen mode

📊 Entity Field Mapping 

; Copy all fields from WEEK entity
putlistitems/occ vList, "WEEK"
; Result: "day1=Mon;day2=Tue;day3=Wed"
Enter fullscreen mode Exit fullscreen mode

🎨 Advanced Use Cases

📋 Record Copying

Here's a neat trick for duplicating entity occurrences:

; Copy fields from first occurrence to new one
setocc "MYENT", 1
putlistitems/occ vList, "MYENT"
creocc "MYENT", -1
getlistitems/occ vList, "MYENT"
Enter fullscreen mode Exit fullscreen mode

🔍 Source Type Flexibility

You can mix and match different source types in your lists:

; Mix fields and variables
day1 = "Mon"
$day2$ = "Fri" 
$$day3 = "Wed"

vList = "day1;$day2$;$$day3"
putlistitems/id vList
; Result: "day1=Mon;$day2$=Fri;$$day3=Wed"
Enter fullscreen mode Exit fullscreen mode

⚠️ Important Notes

  • Runtime Validation: Field and variable existence can't be verified at compile time
  • Field Lists: Ensure all referenced fields are in your entity's field list
  • Component Restrictions: putlistitems/id/global isn't allowed in self-contained Service and Report components
  • Occurrence Management: Make the first occurrence current to ensure complete data processing

📊 Return Values

The $status variable tells you what happened:

  • 0: No data was copied
  • >0: Number of items successfully copied

🎯 Best Practices

  1. Always set the current occurrence before processing multiple entity occurrences
  2. Use appropriate qualifiers to make your intent clear (/field, /component, /global)
  3. Include dollar signs in variable names within list IDs for clarity
  4. Validate your field lists to ensure all referenced fields exist

🚀 Conclusion

The putlistitems command is incredibly versatile and essential for efficient data manipulation in Uniface. Whether you're building simple indexed lists or complex associative structures, mastering these techniques will significantly streamline your ProcScript development!

Happy coding! 💻✨

Top comments (0)