AZK RPG - Calling Programs

• - list of active programs in a job
• - no "recursive call"

• - in calling program
• - prototype definition to define list of parameter's attributes to be sent to called program
• - it passes parm arguments by passing the address of the storage location represented by parm
• - Compiler does not define variables in parm-list and treats the parm-name as a comment

• Dcl-pr Updcust Extpgm('AR002');
•    Company  Char(5);
•    Customer Zoned(7:0);
• End-pr;

• Dcl-pr AR002 Extpgm;
•    Company  Char(5);
•    Customer Zoned(7:0);
• End-pr;

• Dcl-pr AR002 Extpgm;
•    Dcl-parm Return  Char(5);
•    Customer Zoned(7:0);
• End-pr;

• - Compiler does not define variables in parm-list and treats the parm-name (Company, Customer) as a comment
• - that's why we can use unnamed parameters

• Dcl-pr AR002 Extpgm;
•    *N  Char(5);
•    *N Zoned(7:0);
• End-pr;

UpdCust(Company:CustNbr);

• - in the called program
• - procedure interface definition to access storage location passed by calling program
• - pi defines variable names to hold the parms
• - program uses those names to refer the parms

• Dcl-pi AR002;
•    Company Char(5);
•    Customer Zoned(7:0);
• End-pi;

• Dcl-pr
•    - prototype definition to describe list of parms that will pass to the called program
•    - it passes parm arguments by passing the address of the storage location represented by parm
•    - prototypes in calling and called programs must match:
•     1) same # of parameters
•     2) corresponding parms must have the same data attributes

• Dcl-pr Updcust Extpgm('AR002');      // calling program Pr
•    *N Char(5);
•    *N Zoned(7:0);
• End-pr;
•    . . .
• UpdCust(Company:CustNbr);

• Dcl-pr
• - prototype definition to describe the corresponding list of parms that it is to receive from the caller

• Dcl-pi
• - procedure interface definition to access storage location passed by calling program

• Dcl-pr AR002 Extpgm;        // called program Pr
•    *N Char(9)
•    *N Zoned(7:0);
• End-pr;

• Dcl-pi AR002;              // called program Pi
•    Company Char(5);
•    Customer Zoned(7:0);
• End-pi;

• - it's good in called program to give main procedure interface consistent name 'Main'
• - in this case Extpgm must refer to the actual program name

• Dcl-pr Main Extpgm('AR002');    // Main Prototype
•    *N Char(9);
•    *N Zoned(7:0);
• End-pr;

• Dcl-pi Main;            // Main Interface
•    Company Char(5);
•    Customer Zoned(7:0);
• End-pi;

• - if program is called from program other than ILE RPG, prototype is optional, but still recommended
• - in the case if we omit the prototype, we need NOT name the procedure interface

• Dcl-pi Extpgm('AR002');
•    Company Char(5);
•    Customer Zoned(7:0);
• End-pi;

• - by default
• - calling program passing parameters by passing the address of the
• memory storage location represented by variable
• - called program then uses that storage address to retrieve parm value

• - parm need NOT be represented by variable
• - parm data type need NOT precisely match the prototype
• - parm can be represented by literal ('BBY') or expression (Lastcust + 1)
• - parm can NOT be changed by called program

• Dcl-pr Updcust Extpgm('AR002');      // calling program Pr
•    *N Char(5)    Const;
•    *N Zoned(7:0) Const;
• End-pr;
•    . . .
• UpdCust('BBY' : Lastcust + 1);

• - if called program is written in another language that does not support prototyping, such as CL, it may be allowed to change the parm values
• - But we shoult avoid so.

- returns control to the calling program

- system releases any resources in called program

- called program remains activated (all variables and ind's keep values, all files remain opened)

- system objects we use to share data b/w programs w/i a job or b/w jobs

• - Local Data Area
• - system automatically creates LDA for each job in the system
• - 1,024 position long - Character
• - program w/i a job can share information in LDA
• - when job ends, its LDA ceases to exist (destroyed)

• CRTDTAARA - Create Data Area
•    - created in this way DA remains an object on the system until we explicitly remove it
• RTVDTAARA - Retrieve Data Area
• CHGDTAARA - Change Data Area
• DSPDTAARA - Display Data Area
• DLTDTAARA - Delete Data Area

- makes DA accessible to a program

• - Dtaara(*Auto)
•    - identifies Data-Area Data Structure
• - unnamed DA (*N) represents LDA

- unnamed DA (*N) represents LDA

• Dcl-ds *N Dtaara(*Auto);
•    Returncode Ind;
•    Company    Char(5);
•    Nextresnbr Zoned(7:0);
• End-ds;

• - for permanent DA name of the Ext DA must be provided
• - usually name matches the Ext name
• - PGM uses *LIBL/RESCOUNTER to populate the DS

• Dcl-ds Rescounter Dtaara(*Auto);
•    Returncode Ind;
•    Company    Char(5);
•    Nextresnbr Zoned(7:0);
• End-ds;

• Dcl-ds Nextres Dtaara(*Auto:'MYLIB/RESCOUNTER');
•    Returncode Ind;
•    Company    Char(5);
•    Nextresnbr Zoned(7:0);
• End-ds;

• Dcl-ds Nextres Dtaara(*Auto:'MYLIB/RESCOUNTER);
•    Returncode Ind;
•    Company    Char(5);
•    Nextresnbr Zoned(7:0);
• End-ds;

• - In     - Retrieve a DA
• - Out    - Write a DA
• - Unlock - Unlock a DA so another pgms can read and update it

- *Usrctl option - to use 'In', 'Out' and 'Uncock' with DA

• Dcl-ds Nextres Dtaara(*Auto:*Usrctl:'MYLIB/RESCOUNTER);
•    Returncode Ind;
•    Company    Char(5);
•    Nextresnbr Zoned(7:0);
• End-ds;
•    . . .
•       // - unlock DA, so another pgm can read and update it
• Unlock Nextres;
•    . . .
• In *Lock Nextres;    // - to retrieve DA and lock it
• Nextresnbr += 1;
•    . . .
• Out Nextres;        // - DA automatically unlocked
• Out *Lock Nextres;    // - remains DA locked
•    . . .
• Unlock *Dtaara        // - unlocks all DA's locked by program