Store pointers in a job's Local Data Area.

The Local Data Area (LDA) is a user-domain, permanent space object (with MI object type code/subtype code hex 19CE) that is allocated to each IBM i job by the system when the job becomes active. The 1024-byte storage of an LDA can be accessed through CL commands (DSPDTAARA, RTVDTAARA, CHGDTAARA, and CHGVAR), APIs (QXXRTVDA and QXXCHGDA), or built-in support of high-level languages (the IN and OUT opcodes of RPG, and the ACCEPT and DISPLAY statements of COBOL).

You can use the LDA to do a variety of things:

• Exchange information between all programs being called within the same job. It's important that the LDA can be used to store data that is expected to have the same lifetime as the job. Activation group-based storage (static storage and heap storage) will be reclaimed when the corresponding activation group is reclaimed by the RCLACTGRP command or the RCLRSC command or when a new routing step is started for the job as a result of using a RRTJOB, TFRJOB, or TFRBCHJOB command. By contrast, the LDA contents exist across routing steps and will be kept even when the job is in the *OUTQ status.
• Pass information to a submitted job by loading your information into the LDA of your current job and submitting the job. Then, you can access the data from within your submitted job since the content of the current job's LDA is copied to the submitted job's LDA.
• Store information without the overhead of creating and deleting a data area or a user space yourself. (LDAs are created as permanent objects and are managed by the system. When a job ends, the LDA allocated to it will be returned to the system for reuse.)

Unfortunately, there is a limit on the usage of the LDA: none of all existing programming interfaces that access LDAs supports storing MI pointers in an LDA, or in other words, an MI pointer being stored in an LDA via any existing programming interface will become invalid and cannot be used anymore. So what if MI pointers can be stored in the LDA?

• A space pointer stored in the LDA can allow programs that exchange data via the LDA to overcome the 1024 bytes size limit.
• Storing a resolved system pointer in an MI object instead of storing symbolic ID of it in the LDA can save the expense of resolving a system pointer to the MI object each time it's referred to.
• Storing other types of MI pointers in the LDA may also make sense in different scenarios. For example, procedure pointers can be stored in the LDA and shared by programs within a same job to achieve dynamic procedure calls.

And here comes the next question. Given the fact that no existing programming interface can be used to store valid MI pointers in the LDA, is it possible for a user program to achieve this goal? Theoretically, the answer is yes. First, since the LDA is in the user domain, once you obtain a system pointer to an LDA with proper authorities set, you can access it in a user-state program; second, since the LDA contents are stored in a piece of storage in its associated space, once the LDA format is available, you can write MI pointers into the LDA and read them out of it later.

Where Can We Locate the LDA of the Current Job?

When an IBM i job becomes active, system pointers to the job's LDA can be found in the following two places:

• The Work Control Block Table, or WCBT, entry of the job (space objects are called QWCBT## in the QSYS library—for example, QSYS/QWCBT01)
• The job's temporary Work Control Block (WCB) aka the Process Communication Object (PCO)

The WCBT is in the system domain and cannot be accessed from a user-state program at security level 40 or above, so for a user-state program, to locate the LDA, you should turn to the PCO. A system pointer to the LDA of a job can be found at offset hex 0230 in its PCO. The following pieces of code examples locate the LDA pointer in the PCO in OPM MI and ILE RPG, respectively. Note that to retrieve a space pointer to the PCO in ILE high-level languages, you need to turn to the system built-in _PCOPTR2, which returns a space pointer addressing the current job's PCO.

MI example of locating the LDA pointer in the PCO:

ILE RPG example of locating the LDA pointer in the PCO:

The LDA Format

Like common data area (DTAARA) objects, the data contents of the LDA are stored in its associated space. The format of a common DTAARA is quite straightforward, from the beginning of a common DTAARA's associated space there are the following fields:

• CHAR(1) data area type. The value of this field is hex 03 for a *DEC data area, hex 04 for a *CHAR data area, and hex 84 for a *LGL data area.
• BIN(2) data length.
• Data contents of length indicated by the data length field.
• In comparison with common data areas, the format of the LDA is a bit more complicated. At offset hex 08 of the LDA's associated space, there is a BIN(2) field that indicates the start position of the actual data area portion in the LDA's associated space. Beginning from the start position of the actual data area portion, there are fields that are similar to those of a common data area: CHAR(1) data area type(the value of this field for the LDA is always hex 04); BIN(2) data length (the value of this field for the LDA is always hex 0400, 1024 bytes); 1024-byte data contents.

By now, steps to access the contents of the LDA are very clear:

1. Locate the system pointer addressing the LDA in the PCO at offset hex 0230.
2. Retrieve a space pointer addressing the start of the associated space of the LDA via the Set Space Pointer from Pointer (SETSPPFP) MI instruction.
3. In the associated space of the LDA, offset to the actual data area portion of the LDA by using the BIN(2) start position field at offset hex 08.
4. Write scalar or pointer data items to or read scalar or pointer data items from the 1024-byte data contents of the LDA.

The following tiny MI program, lda01.emi, demonstrates the above steps by copying a system pointer to the QTEMP library of the current job to the data contents of the LDA.

Code notes:

[1] A system pointer to the QTEMP library of the current job can be found in the PCO at offset hex 40.

[2] A system pointer to the LDA of the current job can be found in the PCO at offset hex 0230.

[3] A BIN(2) field in the associated space of the LDA at offset hex 08 indicates the start position of the actual data area portion of the LDA in its associated space.

[4] Invoking the SETSPPFP instruction on the system pointer to the LDA returns a space pointer addressing the start of the LDA's associated space.

[5] Offset to the actual data area portion within the associated space of the LDA.

[6] Copy the system pointer to the QTEMP library to the data contents of the LDA.

A Real Example of Exchanging MI Pointers Between Programs via the LDA

To demonstrate further usage of storing MI pointers in the LDA, especially in ILE RPG, I'd like to introduce another (and maybe more practical) example: implementing dynamic procedure calls by storing procedure pointers in the LDA.

Imagine that you have a bundle of procedures implementing the same functionality in subtly different manners, and one of them should be called to achieve the target functionality has to be determined at run time. The ability of issuing dynamic procedure calls is necessary, and the LDA might be one of the places where you store procedure pointers to the selected procedures. The following are two example RPG programs: lda03.rpgle and lda04.rpgle. LDA03 is responsible for selecting a procedure pointer to a procedure within itself at run time and placing it in the LDA. And LDA04 is expected to run in the same job with LDA03 and call the procedure selected by LDA03 via the procedure pointer. Obviously, when LDA04 is called, LDA03 must have already been activated into one of the activation groups of the current job.

LDA03

LDA04

Note that the prototypes of the _PCOPTR2, _SETSPPFP, and _CPYBWP system built-ins that are used in the above examples can be found in mih-prcthd.rpgleinc and mih-ptr.rpgleinc, which are provided by the open-source project i5toolkit.

Call LDA03 and LDA04 as follows and enjoy the tiny dynamic procedure call utility you've implemented via the LDA:

Cautions of Using the LDA

Now you've seen that the LDA is very powerful, especially when being used to store data that is expected to have the same lifetime as the job. Additionally, the ability of storing valid MI pointers in the LDA extended the abilities of the LDA dramatically. However, remember that sharp tools can be dangerous when being misused. Here are a couple of additional considerations about using the LDA to exchange information between programs within a job:

• In a job in which programs belonging to different users could be run, storing security-sensitive data that should be accessible by only one or some of the users can be dangerous because the LDA contents are available to all programs (and their owners) within the job.
• Attention should be paid to the validity of the storage addressed by pointers being stored in the LDA and the validity of the pointers themselves. For example, automatic storage is invocation-dependent, static storage and heap storage are activation group-dependent, and the validity of a procedure pointer is dependent on the activation status of its containing program.

Junlei Li is a programmer from Tianjin, China, with 10 years of experience in software design and programming. Junlei Li began programming under i5/OS (formerly known as AS/400, iSeries) in late 2005. He is familiar with most programming languages available on i5/OS—from special-purpose languages such as OPM/ILE RPG to CL to general-purpose languages such as C, C++, Java; from strong-typed languages to script languages such as QShell and REXX. One of his favorite programming languages on i5/OS is machine interface (MI) instructions, through which one can discover some of the internal behaviors of i5/OS and some of the highlights of i5/OS in terms of operating system design.

 

Junlei Li's Web site is http://i5toolkit.sourceforge.net/, where his open-source project i5/OS Programmer's Toolkit (https://sourceforge.net/projects/i5toolkit/) is documented.