Q: I'm having trouble passing a parameter between ILE CL and RPG IV. The RPG IV procedure being called accepts a variable-length field (the VARYING keyword is "use"). When I call the procedure as follows, I get an error that says the length of the field is incorrect. What am I doing wrong?
DCL VAR(&NAME) TYPE(*CHAR) LEN(20)
CHGVAR VAR(&NAME) VALUE('Stephen C.')
CALLPRC PRC(MAKELOWER) PARM(&NAME)
/* More stuff goes here... */
ENDPGM
A: The problem you are having is that CL--unlike RPG IV--does not support variable-length fields. So when you pass a fixed-length character field, like the &NAME variable in your example, to an RPG IV procedure that expects a variable-length field, the field's length attribute is not included. So the RPG IV program thinks (and rightly so) that the data is corrupted.
In your example, a procedure call (the CALLPRC command) attempts to call an RPG IV procedure whose procedure interface is as follows:
D MakeLower PI Export
D szText 256A Varying
This procedure accepts a parameter that is defined as a variable-length field. When the CALLPRC command is run, the procedure MakeLower is called and immediately fails, generating an "invalid field length" message. To explain why this is happening, let me first review variable-length fields.
Variable-Length Fields
When an RPG procedure accepts a variable-length field, it assumes the field will be formatted properly. Calling the procedure from RPG IV is easy, since you have to have a prototype and the compiler ensures that the data is formatted properly. But when you call a procedure (RPG or otherwise) from CL, no prototype is involved, and you have to ensure that the variable passed as a parameter is properly formatted.
Variable-length fields are unique in that their storage is prefixed with two extra bytes. This means that the field's internal storage size is two bytes longer than the field's declared length. So a 20-position field ends up using 22 bytes of storage. Those extra bytes are a two-byte binary value, or 5i0 in RPG IV syntax, that prefixes the data in the field and contains the current length of the field's contents. The two-byte prefix is automatically inserted and maintained by the RPG compiler. For example, if the field contained 'Bob Cozzi', its current length would be nine, and the two-byte prefix would contain X'0009'. The following figure illustrates the positions, character values, and hexadecimal symbols for a 20-position, variable-length field containing the value 'Bob Cozzi'.
|
prefix
|
1
|
2
|
3
|
4
|
5
|
6
|
7
|
8
|
9
|
10
|
11
|
12
|
13
|
14
|
15
|
16
|
17
|
18
|
19
|
20
|
|
|
B
|
o
|
b
|
|
C
|
o
|
z
|
z
|
i
|
|
|
|
|
|
|
|
|
|
|
|
||
|
0
|
0
|
C
|
9
|
8
|
4
|
C
|
9
|
A
|
A
|
8
|
4
|
4
|
4
|
4
|
4
|
4
|
4
|
4
|
4
|
4
|
4
|
|
0
|
9
|
2
|
6
|
2
|
0
|
3
|
6
|
9
|
9
|
9
|
0
|
0
|
0
|
0
|
0
|
0
|
0
|
0
|
0
|
0
|
0
|
Figure 1: Hex dump of a variable-length field
The field's length attribute is hidden by RPG IV because of RPG's integrated support for variable-length fields. The field length is stored internally as a two-byte binary prefix. All RPG IV operation codes have been enhanced to accommodate variable-length fields. RPG opcodes automatically adjust the length prefix as appropriate.
The length of a variable-length field is, of course, identified when the field is declared. A field whose length is 20A, for example, is a simple 20-position character field. If you add the VARYING keyword, the field becomes a variable-length field with a length potential of 0 to 20. For example:
D Name S 20A Varying
The current length of a variable-length field may be set implicitly or explicitly. The current length is different from the declared length in that it is variable--from 0 up to the declared length. To set the current length of a variable-length field implicitly, copy a value to the field, as follows:
C eval name = 'Bob Cozzi'
In this example, the string 'Bob Cozzi' is copied to the NAME field. The length of the NAME field is automatically adjusted to the length of the string copied to it by the EVAL opcode. This is an implicit field-length assignment. The EVAL opcode does not automatically trim off trailing blanks. If a fixed-length field is moved into a variable-length field, the variable-length field's current length is the same as the declared length of the fixed-length field. For example:
D First S 10A Inz('Bob')
D Last S 10A Inz('Cozzi')
D Name S 20A Varying
.....C..n01..............OpCode(ex)Extended-factor2++++++++++
C eval name = First + Last
In this example, the variable-length field NAME is assigned the concatenated value of the FIRST and LAST fields. Since FIRST and LAST fields are fixed-length, the value of NAME is as follows:
'Bob Cozzi '
Since trailing blanks are not automatically truncated, the current length of NAME ends up being set to 20. To get a more appropriate result, use the %TRIMR built-in function when assigning values to variable length fields, as follows:
D First S 10A Inz('Bob')
D Last S 10A Inz('Cozzi')
D Name S 20A Varying
.....C..n01..............OpCode(ex)Extended-factor2+++++++++++++
C eval name = %TrimR(First + Last)
The NAME field's current length is set to 15. Of course, you'll still have an issue of too many blanks between the first and last names, but that's another issue entirely.
To set a variable-length field's current length explicitly, use the %LEN built-in function, as follows:
C eval %Len(name) = 3
In this example, the length of the variable-length field is adjusted to 3. A subsequent MOVE or EVAL of the NAME field's data to another field would return just the first three characters of the field. In this example, 'Bob' would be all that is returned.
To retrieve the current length of a variable-length field, use the %LEN built-in function on the right side of the operator. For example:
C eval nLen = %Len(name)
This can be particularly useful in a DOx or FOR loop. The %LEN built-in function is very efficient because all it does is return the value stored in the two-byte binary prefix of the variable length field.
CL Support for Variable Length Fields
CL does not have integrated support for variable-length fields. In fact, it has no built-in support for this type of field at all. In order to properly pass a variable-length field from CL to RPG IV, the two-byte binary prefix must be managed by the CL module. This is accomplished by storing the length of the field's data in the first two positions in the field. Consequently, it's a good idea to increase the field length by two bytes.
In the example that follows, the field named &NAME was a 20-position character variable in this CL module. In order to accommodate the variable-length field parameter required by the MAKELOWER routine, I've added two bytes to the field's length. The field's length is now 22 (line 2 in Figure 2).
|
Figure 2: CL module correctly calling an RPG IV procedure
In order to embed a two-byte, binary-length prefix into the &NAME variable, the %BIN CL built-in function is used (see line 3 in Figure 2). The syntax of %BIN is similar to %SST in that it accepts a field name, a starting position, and a length. The length indicates the number of characters that will be modified or extracted as a binary (i.e., integer) value. Once the length (9 in this example) is embedded in the two-byte prefix, you can copy the data into the field. But you cannot copy it into position 1 and 2 of the field because that would overwrite the field's length. By using the %SST (substring) built-in function (line 4 in Figure 2), you bypass the two-byte, binary-length prefix and copy the data into the field starting in position 3.
When the MAKELOWER procedure is called (line 5 in Figure 2), the variable &NAME becomes a properly formatted variable-length field and should pass through properly.
The source code for the MAKELOWER procedure in RPG IV is listed in Figure 3.
|
Figure 3: RPG IV source for the MAKELOWER procedure
Upon return from the call to MAKELOWER, the CL program should inspect the two-byte binary prefix and figure out how long the data is in the field. Figure 4 illustrates this technique. Lines 8 and 9 extract the current length of the variable-length field and then use that length with the %SST built-in function to extract the modified data from the &NAME field.
|
Figure 4: Modified CL source to extract a variable-length field's current length
Bob Cozzi is a programmer/consultant, writer/author, and software developer. His popular RPG xTools add-on subprocedure library for RPG IV is fast becoming a standard with RPG developers. His book The Modern RPG Language has been the most widely used RPG programming book for more than a decade. He, along with others, speaks at and produces the highly popular RPG World conference for RPG programmers.
MC Press books written by Robert Cozzi available now on the MC Press Bookstore.
 |
||
 |
|
RPG TnT Get this jam-packed resource of quick, easy-to-implement RPG tips! List Price $65.00 Now On Sale
|
|
||
 |
|
The Modern RPG IV Language Cozzi on everything RPG! What more could you want? List Price $99.95
Now On Sale
|
More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.
TRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now! Request Now.
Forms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.
Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:
Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.
IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn:
LATEST COMMENTS
MC Press Online