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:
|
dcl spc pco baspco ; dcl sysptr lda dir pos(h"231") ; |
ILE RPG example of locating the LDA pointer in the PCO:
|
d pcoptr2 pr * extproc('_PCOPTR2')
d @pco s * d pco ds qualified d based(@pco) d * dim(35) d lda * /free @pco = pcoptr2(); // Now the system pointer <var>lda</var> becomes valid. /end-free |
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:
- Locate the system pointer addressing the LDA in the PCO at offset hex 0230.
- Retrieve a space pointer addressing the start of the associated space of the LDA via the Set Space Pointer from Pointer (SETSPPFP) MI instruction.
- 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.
- 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.
|
dcl spc pco baspco ; dcl sysptr qtemp dir pos(h"41") ; /* [1] */ dcl sysptr lda dir pos(h"231") ; /* [2] */
dcl spcptr lda-spc-ptr auto ; dcl spc lda-spc bas(lda-spc-ptr) ; dcl dd lda-start bin(2) dir pos(9) ; /* [3] */
dcl spcptr lda-area-ptr auto ; dcl spc lda-area bas(lda-area-ptr) ; dcl dd lda-type char(1) dir ; dcl dd lda-dta-len bin(2) dir ; dcl dd lda-dta-buf char(1024) dir ;
setsppfp lda-spc-ptr, lda ; /* [4] */ addspp lda-area-ptr, lda-spc-ptr, lda-start ; /* [5] */ cpybwp lda-dta-buf, qtemp ; /* [6] */ brk "END" ; rtx * ; pend ; |
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
|
h dftactgrp(*no)
/copy mih-prcthd /copy mih-ptr d i_main pr extpgm('LDA03') d flag 1a
d @pco s * d pco ds qualified d based(@pco) d * dim(35) d lda * d ldaproc * overlay(lda) d procptr d ldaspcptr * d ldaspc ds qualified d based(ldaspcptr) d 8a d start 5u 0 d ldaaraptr s * d ldaara ds qualified d based(ldaaraptr) d ldatype 1a d ldalen 5u 0 d dta 1024a d funcptr s * procptr
d addi pr 10i 0 d addent1 10i 0 value d addent2 10i 0 value * round the sum to ten d addih pr 10i 0 d addent1 10i 0 value d addent2 10i 0 value
d i_main pi d flag 1a
/free // Locate the LDA pointer in the PCO @pco = pcoptr2(); // Address the associated space of the LDA ldaspcptr = setsppfp(pco.ldaproc); // Offset to the actual data area portion ldaaraptr = ldaspcptr + ldaspc.start;
// Store selected procedure pointer in the LDA if %parms() > 0 and flag = 'H'; funcptr = %paddr(addih); else; funcptr = %paddr(addi); endif; cpybwp( %addr(ldaara.dta) : %addr(funcptr) : 16 );
*inlr = *on; /end-free
p addi b d addi pi 10i 0 d addent1 10i 0 value d addent2 10i 0 value /free return (addent1 + addent2); /end-free p e
p addih b d addih pi 10i 0 d addent1 10i 0 value d addent2 10i 0 value d r s 10i 0 d addih pr 10i 0 /free r = (addent1 + addent2) / 10; return (r * 10); /end-free p e |
LDA04
|
h dftactgrp(*no)
/copy mih-prcthd /copy mih-ptr d @pco s * d pco ds qualified d based(@pco) d * dim(35) d lda * d ldaproc * overlay(lda) d procptr d ldaspcptr * d ldaspc ds qualified d based(ldaspcptr) d 8a d start 5u 0 d ldaaraptr s * d ldaara ds qualified d based(ldaaraptr) d ldatype 1a d ldalen 5u 0 d dta 1024a d funcptr s * procptr d i s 10i 0
d func pr 10i 0 extproc(funcptr) d parm1 10i 0 value d parm2 10i 0 value
/free // Locate the LDA pointer in the PCO @pco = pcoptr2(); // Address the associated space of the LDA ldaspcptr = setsppfp(pco.ldaproc); // Offset to the actual data area portion ldaaraptr = ldaspcptr + ldaspc.start;
// Load PROCPTR funcptr from the LDA cpybwp( %addr(funcptr) : %addr(ldaara.dta) : 16 ); // Call target procedure via PROCPTR funcptr i = func(955 : 6); dsply 'i' '' i;
*inlr = *on; /end-free |
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:
|
4 > call lda03 4 > call lda04 DSPLY i 961 4 > call lda03 h 4 > call lda04 DSPLY i 960 |
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.
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