What Is New Data Len in iSeries Systems?
If you work with IBM i environments, you’ve likely encountered unexpected behavior when processing functions. The culprit? A hidden setting called NEW_DATA_LEN. It’s part of a larger control structure known as the CCSID (Coded Character Set Identifier) conversion context. This setting quietly influences how string data is handled during external function calls, often leading to subtle bugs that are frustrating to debug. Understanding it can save you hours of troubleshooting.
New Data Len controls whether trailing blanks are preserved or stripped when data passes between RPG programs and external APIs, particularly in C-based libraries. While the concept seems technical, its impact is practical—especially when your code relies on exact string lengths for validation or formatting. Let’s break down what it does, why it matters, and how to manage it effectively.
Understanding the Basics of NEW_DATA_LEN
The NEW_DATA_LEN keyword is one of several options available within the CCSID conversion context. It specifically dictates how the length of character data is interpreted during conversion processes. By default, IBM i systems tend to strip trailing blanks from character fields unless explicitly told otherwise. This behavior can cause issues when interfacing with systems or libraries that expect fixed-length strings.
When NEW_DATA_LEN is set to *YES, the system preserves the original length of the data, including any trailing spaces. If it’s set to *NO, those spaces are removed. This distinction may seem minor, but it can significantly affect downstream processing, especially in legacy integrations or when working with third-party tools that rely on strict field specifications.
For example, imagine passing a 20-character name to an external application. If the name is only 12 characters long, the remaining eight spaces could be discarded if NEW_DATA_LEN is off. That missing padding might break a process expecting exactly 20 bytes. Knowing this, developers can preemptively adjust settings to match their needs.
Why Does NEW_DATA_LEN Exist?
The roots of this feature lie in IBM’s effort to balance flexibility and compatibility across diverse programming languages and platforms. When RPG programs call C functions or interact with APIs, there’s often a mismatch in how each language interprets string data. RPG traditionally treats character fields as fixed-length, while C tends to view them as variable-length terminated by a null byte.
To bridge this gap, IBM introduced the CCSID conversion context, which includes not just character set conversions but also length handling rules. NEW_DATA_LEN is one such rule. It ensures that data isn’t unintentionally altered during translation, giving developers control over whether padding should be kept or removed.
This level of granularity is crucial in enterprise environments where precision matters. A misplaced assumption about data length can lead to corrupted records, failed transmissions, or even security vulnerabilities. That’s why knowing how to manage these settings is so valuable.
How to Set and Adjust NEW_DATA_LEN
Setting NEW_DATA_LEN is typically done via the CCSID conversion context parameter in your program or module. You can specify it at compile time or adjust it dynamically through runtime controls. The most common approach involves using the CALLP statement with a properly structured context descriptor.
Here’s a simplified example:
- Context Descriptor Creation: Define a structure that includes the CCSID and NEW_DATA_LEN flags. Use %ADDR or %SUBSTARS to populate it correctly.
- Passing to External Functions: When calling an external API, pass the descriptor along with the data. This tells the system how to handle the string during conversion.
dcl-ds context; ccsid int(10); new_data_len char(5); end-ds; context.ccsid = *C; context.new_data_len = '*YES';// Example structure for context
You can also tweak this setting globally through system values like QCALENDARS or QCCSID, though that affects all conversions across the system—not just your application. Local adjustments offer more control but require careful coding to avoid side effects.
Common Pitfalls and Best Practices
One of the biggest challenges with NEW_DATA_LEN is forgetting that it only applies when conversions occur. If no character set translation happens, the setting has no effect. This means testing edge cases is essential—especially when moving data between different character encodings or platforms.
Another pitfall is assuming that all external systems handle padding the same way. Some expect null-terminated strings, others rely on explicit lengths, and still others interpret trailing spaces as significant. Always verify the expectations of the receiving system before configuring your end.
Best practices include:
- Test Thoroughly: Use sample inputs that include varying amounts of white space to ensure consistency.
- Document Assumptions: Clearly note in comments or specs which systems expect padded strings and which prefer trimmed ones.
- Use Dynamic Settings: Rather than hardcoding values, build logic that adapts based on runtime conditions.
By treating NEW_DATA_LEN as a configurable variable rather than a fixed rule, you gain the flexibility to meet changing requirements without rewriting core logic.
When Should You Care About It?
Not every developer will need to dive into CCSID contexts regularly. But if you’re building integrations, especially those involving old APIs or cross-platform services, understanding NEW_DATA_LEN becomes critical. It’s particularly relevant when dealing with banking systems, government databases, or any environment where legacy systems still dominate.
Even in modern applications, microservices and cloud platforms often receive data from older sources. If those files arrive with inconsistent padding, your service might misinterpret them unless you account for length variations. Proactive configuration helps prevent costly rework later.
In short, ignore it at your peril. Treat it as part of your data hygiene strategy, and you’ll avoid many headaches down the line.
FAQ
What does NEW_DATA_LEN do?
It determines whether trailing spaces are preserved when converting character data between programs. Setting it to *YES keeps the full length; *NO strips the blanks.
Is it only used in RPG?
While commonly associated with RPG, NEW_DATA_LEN applies whenever character data crosses boundaries between differently encoded systems. Any language interacting with C APIs or external services may benefit from proper handling.
Can I change it globally?
Yes, you can set it system-wide, but doing so may affect all conversions. For safety, limit changes to specific modules or contexts unless absolutely necessary.
Why does my data look wrong after conversion?
Often, it’s due to mismatched assumptions about string length. Check whether NEW_DATA_LEN is aligned with the expectations of the receiving system, and test both padded and unpadded inputs.
