Docs/chandra explain1 by Chandra-IBM1 · Pull Request #8 · IBM/rpg-genai-data

Chandra-IBM1 · 2025-05-15T08:51:19Z

No description provided.

UtkarshIBM1 · 2025-05-16T08:40:56Z

docs/pages/task/explain_module.md

    -  Required preconditions
    -  Unsupported input types

-  -  `Outcomes`


Since we have removed Output sections, I feel that outcomes will be a valuable section to keep as this will provide the user an overall view of what result will be produce after code execution. @bmorris1 @edmundreinhardt . Could you please suggest on this point ?

Side Effects and Return Values and Output Parameters should be sufficent to document that.

anandsha20 · 2025-05-16T09:09:59Z

docs/pages/task/explain_module.md


-  -  `Outcomes`
+  -  `Usage Example`
    Define the expected outcomes of the procedure’s execution.


Usage Example: This should provide an example on how we can utilize or call the procedure instead of defining the expected outcomes. fyi @bmorris1, @edmundreinhardt, @Chandra-IBM1

@anandsha20 I agree that it should show how to call the procedure.

It should show an example of all aspects of calling the procedure

The /copy statement with the prototype

any setup needed for parameters

the call to the procedure

if it returns a value or modifies a parameter, it should either show or describe how the caller would use those values.

But for cases where the caller would not do any further coding related to that call, I don't think anything is needed in the Usage section. For example, if the procedure did something related to files, that's not really part of the Usage, it's a Side Effect.

anandsha20 · 2025-05-16T09:16:05Z

docs/pages/task/explain_program.md

  - Example: The load all subfile can load only up to 9999 records.

-6. `Outcomes`: List possible major outcomes or scenarios resulting from the code execution. This section can include an optional `usage example` to illustrate the expected outcome.
+6. `Usage Example`: Define the expected outcomes of the program execution.


Usage Example: This should provide an example on how we can utilize the program instead of defining the expected outcomes. Please check for other scopes as well. fyi @bmorris1, @edmundreinhardt, @Chandra-IBM1

I agree. It should be similar to the Usage section for a procedure in a module, although depending on the nature of the program it might be better to show a ```clle call which could also represent a call from the command line.

But if there is a /copy file with an RPG prototype for the program, the Usage should be similar to the Usage for a procedure

The /copy statement

Any setup for parameters

The call

Code or discussion saying what to do with any output variables

I agree that this should be an example of calling the program. The outcomes should have been discussed in side effects .
In fact for programs, I think we should rename Side Effects to Outcomes
What do you think @bmorris1 @anandsha20 @Chandra-IBM1

I'm not sure.

Any procedure or program could have both outcomes and side effects, although I'm not always sure which is which.

How about having a more general name for both outcomes and side effects such as "Outside effects", although I don't really like that name. For procedures and subroutines, it could have a subsection about "Global variables".

bmorris1 · 2025-05-16T11:50:44Z

docs/pages/task/explain_module.md

    -  Global variables
    -  Shared resources
-    -  Logs or external states
+    -  Dataaera updates 


It should not discuss Global variables unless they are defined with the IMPORT or EXPORT keyword.

Data area or DATARA

Data area or DTAARA

I think "Data area" is better

bmorris1 · 2025-05-16T11:53:21Z

docs/pages/task/explain_module.md


-  - `Initialization`: Describe the initial setup required for the procedure. Include all local variables and parameters.
+  - `Definitions`: This section covers all declarations and setup required before the main logic of the procedure begins. It includes the definition of local variables, data structures, and any constants or initial values needed to support the procedure’s execution
  - `Main Logic`: Explain the core logic of the procedure, detailing the steps taken to achieve the procedure's purpose.


It should list any subroutines within the procedure with a brief description of each subroutine.

bmorris1 · 2025-05-16T11:54:23Z

docs/pages/task/explain_module.md

+3. `Global Components`: The Global Variables section includes all variables, prototypes for external program calls, data structures, arrays, constants, and keywords used in the variable declarations (example`LIKE`, `INZ`, `N` data type)

-  Provide a step-by-step description of the logic for each procedure.
+4. `Procedures` : Provide a step-by-step description of the logic for each procedure.


For each procedure, state whether it is exported or internal to the module.

bmorris1 · 2025-05-16T12:01:59Z

docs/pages/task/explain_source_references.md


 3. `Return Values` : List the return value accepted by the procedure, specifying whether it is an output

-4. `Dependencies`: This section outlines all components that the procedure or subroutine depends on in order to run successfully. Dependencies include physical and logical files used for data access, external procedures for business logic, and display files for user interface interactions.


Git would not let me put this comment on the "Return values" line.

It should say

Return value: List the value returned by the procedure. Specify the data type and the meaning of the return value.

bmorris1 · 2025-05-16T12:03:20Z

docs/pages/task/explain_source_references.md

  - Example: The caller cannot update records it is only input. This means the procedure or subroutine is designed to read data but not modify it.

-7. `Outcomes`: List possible major outcomes or scenarios resulting from the code execution. This section can include an optional usage example to illustrate the expected outcome.
+7. `Usage Example`: List possible major outcomes or scenarios resulting from the code execution. This section can include an optional usage example to illustrate the expected outcome.


This should show a call to the procedure, with any setup required for parameters, and either an example or a description of what the caller would do with the return value or any output parameters.

bmorris1 · 2025-05-16T12:04:35Z

docs/pages/task/explain_source_references.md

+
 2. `Field Mapping`: If the procedure or subroutine relates to any display file or printer file, create a clear table or list to show how physical/logical file fields are mapped to display fields or printer file. This includes field names and display fields.

 3. `Indicators`: If the procedure or subroutine uses indicators, explain their purpose and how they are set or cleared during execution in table format.


Clarify that this is only the *IN indicators or any indicators in an INDDS data structure.

It should not be about any ordinary variables that happen to have the indicator data type.

bmorris1 · 2025-05-16T12:08:31Z

docs/pages/task/sample_module.md

@@ -94,27 +94,16 @@ The `GetActInf` module provides reusable subprocedures to retrieve account-relat
 #### Return Value
 | -Return Value- | Output    | `char(10)` | The account number associated with the given ID |


For the Return Value, The first two columns are not needed.

Data Type Description

char(10) The account number associated with the given ID

If it is a data structure, list the subfields.

bmorris1 · 2025-05-16T12:27:57Z

docs/pages/task/sample_module.md

-    - The returned value will be blank.
-    - Calling code must ensure the returned value is not reused inappropriately in future calls.
-
 #### Usage Example


For small snippets, I don't think it would be good to put **free at the top. But without **free, free-form code has to start in column 8. So, I think any little snippet like this should have 7 blanks before the code.

This version has the code starting in column 1. The formatter thinks the 'd' in userid is the D of a fixed-form D spec and it doesn't "see" the "dcl-s" part of the declarations so it doesn't colour them red.

dcl-s userid char(10); dcl-s account_number char(10); /copy getactinfcpy; userid = 'TEST01'; account_number = GetAccNo(userid);

This version has 7 blanks preceding each line of code.

dcl-s userid char(10); dcl-s account_number char(10); /copy getactinfcpy; userid = 'TEST01'; account_number = GetAccNo(userid);

bmorris1 · 2025-05-16T12:31:32Z

docs/pages/task/sample_module.md

@@ -141,28 +130,17 @@ account_number = GetAccNo(userid);
 | `P_UserId`     | Input     | `char(10)` | Customer ID to search for in the `AccPf` file              |
 | -Return Value- | Output    | `char(50)` | The account description associated with the input `CustId` |


Fix this information about the return value to be in the same format as for GetAccNo above.

bmorris1 · 2025-05-16T12:35:21Z

docs/pages/task/sample_module.md

 - If no match is found:
  `account_desc` will be blank. The calling logic should handle such cases to avoid misinterpretation.

-


Git would not let me add a comment on the line about the purpose.

It currently says

The RPGLE program provides reusable subprocedures to retrieve account-related information from the AccPf physical file based on a given customer ID (CustId). Specifically, it allows external programs to obtain:

It should say

The RPGLE module provides reusable subprocedures to retrieve account-related information from the AccPf physical file based on a given customer ID (CustId). Specifically, it contains exported procedures to obtain:

bmorris1 · 2025-05-16T12:42:38Z

docs/pages/task/sample_program.md


 The RPGLE program is designed to retrieve the account number (`AccNo`) for a given user ID (`P_UserId`) from the `AccPf` file. It reads through the records in the `AccPf` file and searches for a match with the provided user ID. Once a match is found, it sets the corresponding account number in the output parameter `P_AccNo`.

-### Parameters


Git would not let me add a comment at the beginning of this file. The code sample for the program must have the **free right at the beginning of the line.

This is what the code looks like with the **free starting in column 5. It thinks the code is column-limited, so it interprets column 6 as being the spec type.

**free ctl-opt dftactgrp(*no) actgrp(*new); dcl-f AccPf if e k disk;

This is what it looks like with the **free in column 1:

**free ctl-opt dftactgrp(*no) actgrp(*new); dcl-f AccPf if e k disk;

This comment was not addressed yet.

bmorris1 · 2025-05-16T12:54:21Z

docs/pages/task/sample_program.md

-  - If the same program runs again without resetting `P_AccNo`, it retains the previous value, leading to incorrect or unintended output.
-
-#### Usage Example
+### 6. Usage Example


Git would not let me add a comment in the File Specifications section.

It has this bit of sample code for a fixed-form statement. This would not be helpful for someone who does not know RPG.

FAccPf IF E K Disk

Please correct all such samples of fixed-form statements in all these documents to show the actual statement, surrounded by the two lines rpgle and and with 5 leading blanks.

FAccPf IF E K Disk

I think it would be good to have a page about how to format code snippets, and link to the page from each document.

For small free-form snippets, don't put **free, but instead have 7 leading spaces

For large free-form snippets, make sure the **free is in column 1.

For fixed-form snippets, always have the correct fixed-format of the lines

bmorris1

Some of my comments apply to all the documents, such as my comments about formatting code snippets.

Also, some of my comments are not positioned against the line they apply to, because Git would not let me make a comment for some lines in large unchanged sections. I hope I made it clear what I was actually referring to ... :-)

bmorris1 · 2025-05-27T19:12:51Z

docs/pages/task/explain_module.md

+  Example:
+  | Parameter Name | Data Type | Description |
+  |----------------|------|--------|
+  | `pOrderId`     | `char(10)` | The unique identifier for the order being processed |


Add a column after the Data Type column for whether it is input or output.

If CONST or VALUE is specified, it is input-only

If CONST or VALUE is not specified, it is input and output

bmorris1 · 2025-05-27T19:15:07Z

docs/pages/task/explain_module.md

+  - APIs or external libraries
+  - Data areas
+  - Data queues
+  - Any other external modules or systems


Change the last one to just "etc"

bmorris1 · 2025-05-27T19:15:34Z

docs/pages/task/explain_module.md

+  List all external components the program relies on to function correctly. This includes:
+  - Called programs
+  - Service programs (SRVPGMs)
+  - APIs or external libraries


This should be two separate points

bmorris1 · 2025-05-27T19:17:17Z

docs/pages/task/explain_module.md

+  | Component Name  | Type     | Description |
+  |-----------------|----------|-------------|
+  | `CALC_SERVICE`   | Service  | Performs complex calculations for order processing |
+  | `DATA_AREA_1`    | Data Area| Stores configuration settings for the program |


Make this example library qualified since the library should be listed if it is known

| LIB1/DATA_AREA_1 | Data Area| Stores configuration settings for the program |

bmorris1 · 2025-05-27T19:19:12Z

docs/pages/task/explain_module.md

+  This section should illustrate all relevant aspects of calling the procedure, including:
+
+  1. The `/COPY` Statement
+      - Show how the caller includes the prototype using a `/COPY` directive (if applicable).


It is always applicable for an rpgle example for scope=module, since the caller is expected to be in a different module.

Add this:

When there is no /COPY file with the prototypes, it is a problem in the application, especially if the other programs in the application define their own prototypes so they can call the procedures.

In that case, the issue with the missing /COPY with the prototypes should be mentioned in the "Problems" section.

@edmundreinhardt @Chandra-IBM1 @jiatianzhong How should usage samples be handled when the module doesn't have a copy file with the prototypes for its procedures?

Should the sample just make up the name of a /COPY file?

Should the sample actually code the prototype (which would add to the problem of the prototype being coded in multiple modules)

I started a Slack thread about this in the #wca4i-tcs-datagen channel: https://my.slack.com/archives/C08FGHCDT26/p1750425339221139

I am unable to follow that slack link but my opinion is that if no copybook is present/known, the prototype should be in the usage example. The developer can then copy it into a copybook
@bmorris1 @Chandra-IBM1 @jiatianzhong

bmorris1 · 2025-05-27T19:20:19Z

docs/pages/task/explain_module.md

+      - Show how the caller includes the prototype using a `/COPY` directive (if applicable).
+
+  2. Parameter Setup
+    - Define and initialize all input and output parameters required for the call.


input and output parameters and any return value

bmorris1 · 2025-05-27T19:21:04Z

docs/pages/task/explain_module.md

+
+  3. The Procedure Call
+    - Demonstrate the call using:
+      - `CALLP` if using a procedure with a prototype.


The CALLP opcode is not necessary. It is very rare that CALLP is used for a prototyped call in free form.

bmorris1 · 2025-05-27T19:23:10Z

docs/pages/task/explain_module.md

+      DCL-S orderTotal   PACKED(9:2);
+      DCL-S statusCode   CHAR(2);
+
+      CALLP CalculateOrderTotal(customerId : orderTotal : statusCode);


Remove the CALLP. Just do the procedure call.

CalculateOrderTotal(customerId : orderTotal : statusCode);

Removed extra sections for different types of data structures. Will later move the examples to a separate file

Examples of data structure explanations

Most of the information was moved into other files.

Minor change

Minor changes

The main change is to remove the Side Effects section since that should be covered by the global variables, file I/O, and dependencies.

Minor change

Minor changes

Minor change

Fix formatting

Some formatting changes.

Code-formatting corrections, some content corrections. More changes are needed for it to conform to the required output format.

Code formatting changes, some general output-format changes, more needed.

Add the parameter-number column to the parm tables

bmorris1 · 2025-06-04T23:48:44Z

docs/pages/task/explain_program.md

+  - Otherwise, use a clle snippet to represent a call from the command line.
+```clle 
+        call mypgm parm(parameters)
+```


Question (@edmundreinhardt @Chandra-IBM1 @jiatianzhong )

If it is a fixed-form program with no prototype for the call, and the parameters in the *ENTRY PLIST form, would it be better to show a fixed form RPGLE CALL rather than showing a clle-style call from the command line?

C call 'MYPGM' C parm parameter

Yes, use the fixed-form RPGLE CALL with PARM to match the style and parameter-passing method of the program. It is clearer and more accurate for understanding how the program expects to be called.

Ok, thanks. I changed it to have 3 possibilities:

free-form call if there is a prototype

else fixed-form CALL+PARM if there is a *ENTRY PLIST

otherwise clle call

Fixed the algorithm for determining the number of bytes in packed fields with an even number of digits

Suggest to use a fixed-form CALL if the parameters are in *ENTRY PLIST format

bmorris1 · 2025-06-20T17:03:37Z

docs/pages/task/explain_module.md

-    -  External APIs or modules
+  2. Parameter Setup
+    - Define and initialize all input, output parameters and any return values required for the call.
+    - Include declarations for any necessary constants, variables, or data structures.


There should be sections with "Possible Problems with this Code" and "Possible Improvements to this Code"

bmorris1 · 2025-06-20T17:19:45Z

docs/pages/task/explain_parameters.md

+The parameters are described in a table with columns for the parameter number, `Data Type`, `Usage`, `Description`, and possibly `Attributes`.
+
+The column for the parameter number does not have a heading.
+


Add this:

If it is an unnamed parameter in a prototype, put not named in the name column. Also, add a point in the "Possible Improvements to this Code" that it's a good idea to give names to the parameters in a prototype

bmorris1 · 2025-06-20T17:52:02Z

docs/pages/task/explain_definitions.md

+| * | PROCPTR | pointer(*proc) |
+| O | CLASS(*java ...) | object(*java ... ) |
+| D | DATFMT(fmt) | date(fmt) |
+| T | TIMFMT(fmt) | time(fmt) |


Add some information about data structure subfields that don't have any data type. See this Slack thread in #wca4i-tcs-datagen: https://my.slack.com/archives/C08FGHCDT26/p1750425339221139

Sorry. The correct link for the Slack thread about subfields with no data type is https://my.slack.com/archives/C08FGHCDT26/p1750441642809399

bmorris1 · 2025-06-20T19:38:39Z

docs/pages/task/explain_module.md


- 2. `Exported Procedures`
-
+2. #### Exported Procedures


I think the general part of api_output before the procedures should have the global dependencies (files and other objects)

bmorris1

I made several new comments but I haven't finished my review yet.

bmorris1 · 2025-06-23T13:11:42Z

docs/pages/task/explain_global_definitions.md

+
+##### Variables 
+This section documents all variables used in the program, module, or procedure. It should be described in tabular format with columns for Name, Data Type, Description, and Attributes.
+Only include the Attributes column if necessary.


Add the following information about how to describe externally-described fields that are implicitly defined by the compiler:

If it is a field that was defined by the compiler from an externally described file, mention that in the description. For example if you have this file:

A R ORDERFMT A ORDERID 6A A QUANTITY 5P 0 A PRICE 9P 2 A K ORDERID

and this rpgle code

dcl-f orders; dcl-s total int(10); begsr add_to_total; total += quantity * price; endsr;

Put this for the description when describing the global variables used by the subroutine:

Name Data Type Description

Price packed(9:2), (5 bytes) Externally-described field from file 'ORDERS', likely set by a READ operation from the file

Matta Chandrashekar added 2 commits May 15, 2025 13:18

Document update

403d16d

New changes

51d1176

Chandra-IBM1 requested review from bmorris1 and edmundreinhardt May 15, 2025 10:19

UtkarshIBM1 reviewed May 16, 2025

View reviewed changes

anandsha20 reviewed May 16, 2025

View reviewed changes

bmorris1 reviewed May 16, 2025

View reviewed changes

bmorris1 requested changes May 16, 2025

View reviewed changes

Matta Chandrashekar added 2 commits May 27, 2025 23:48

Modified as per latest call

2cf79db

Modified as per latest call

8faf5a8

bmorris1 reviewed May 27, 2025

View reviewed changes

bmorris1 added 20 commits June 3, 2025 14:53

Update explain_global_definitions.md

ddd130e

Removed extra sections for different types of data structures. Will later move the examples to a separate file

Create explain_data_structure.md

38652bf

Examples of data structure explanations

Update explain_global_definitions.md

572b1b9

Most of the information was moved into other files.

Create explain_parameters.md

83c8644

Update explain_global_definitions.md

d206ce1

Update explain_parameters.md

d8533da

Update explain.md

84871ae

Minor change

Update explain_module.md

71fdb5f

Minor changes

Update explain_procedure.md

07a7646

The main change is to remove the Side Effects section since that should be covered by the global variables, file I/O, and dependencies.

Update explain_lines.md

ed3d7a2

Minor change

Update explain_program.md

c0dd736

Minor changes

Update explain_subroutine.md

0b19508

Minor changes

Update explain_copybook.md

73801e7

Minor change

Update sample_copybook.md

543b7ff

Update sample_lines.md

6f82a5f

Fix formatting

Update explain.md

bacda52

Update sample_module.md

8290a78

Some formatting changes.

Update sample_program.md

aada23a

Code-formatting corrections, some content corrections. More changes are needed for it to conform to the required output format.

Update sample_source_references.md

3cd1173

Code formatting changes, some general output-format changes, more needed.

Update sample_module.md

08e5397

Add the parameter-number column to the parm tables

bmorris1 reviewed Jun 4, 2025

View reviewed changes

bmorris1 added 2 commits June 7, 2025 05:43

Update explain_definitions.md

c54e1aa

Fixed the algorithm for determining the number of bytes in packed fields with an even number of digits

Update explain_program.md

c95b78c

Suggest to use a fixed-form CALL if the parameters are in *ENTRY PLIST format

bmorris1 reviewed Jun 20, 2025

View reviewed changes

bmorris1 reviewed Jun 23, 2025

View reviewed changes

Changes as per new format

201c456


		3. `Return Values` : List the return value accepted by the procedure, specifying whether it is an output

		4. `Dependencies`: This section outlines all components that the procedure or subroutine depends on in order to run successfully. Dependencies include physical and logical files used for data access, external procedures for business logic, and display files for user interface interactions.


		2. `Field Mapping`: If the procedure or subroutine relates to any display file or printer file, create a clear table or list to show how physical/logical file fields are mapped to display fields or printer file. This includes field names and display fields.

		3. `Indicators`: If the procedure or subroutine uses indicators, explain their purpose and how they are set or cleared during execution in table format.

		@@ -94,27 +94,16 @@ The `GetActInf` module provides reusable subprocedures to retrieve account-relat
		#### Return Value
		\| -Return Value- \| Output \| `char(10)` \| The account number associated with the given ID \|

		@@ -141,28 +130,17 @@ account_number = GetAccNo(userid);
		\| `P_UserId` \| Input \| `char(10)` \| Customer ID to search for in the `AccPf` file \|
		\| -Return Value- \| Output \| `char(50)` \| The account description associated with the input `CustId` \|

		- If no match is found:
		`account_desc` will be blank. The calling logic should handle such cases to avoid misinterpretation.


		The RPGLE program is designed to retrieve the account number (`AccNo`) for a given user ID (`P_UserId`) from the `AccPf` file. It reads through the records in the `AccPf` file and searches for a match with the provided user ID. Once a match is found, it sets the corresponding account number in the output parameter `P_AccNo`.

		### Parameters

		The parameters are described in a table with columns for the parameter number, `Data Type`, `Usage`, `Description`, and possibly `Attributes`.

		The column for the parameter number does not have a heading.

Conversation

Chandra-IBM1 commented May 15, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anandsha20 May 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bmorris1 May 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bmorris1 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bmorris1 May 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bmorris1 May 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anandsha20 May 16, 2025 •

edited

Loading

bmorris1 May 16, 2025 •

edited

Loading

bmorris1 May 27, 2025 •

edited

Loading

bmorris1 May 27, 2025 •

edited

Loading