06
Fri, Dec
6 New Articles

Maximize the Abilities of the LDA

RPG
Typography
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

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:

  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.

 

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.

 

Junlei Li

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.

BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

Support MC Press Online

$

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More 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.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY 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.

  • SB HelpSystems ROBOT GenericForms 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.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA 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:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA 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.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra 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: