Docs/chandra explain1

[Chandra-IBM1]

No description provided.

[UtkarshIBM1]

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 ?

[edmundreinhardt]

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

[anandsha20]

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

[bmorris1]

@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]

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

[bmorris1]

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

[edmundreinhardt]

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

[bmorris1]

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]

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

[edmundreinhardt]

• Data area or DATARA

[bmorris1]

Data area or DTAARA

[bmorris1]

I think "Data area" is better

[bmorris1]

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

[bmorris1]

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

[bmorris1]

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

It should say

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

[bmorris1]

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]

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]

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]

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]

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

[bmorris1]

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]

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;

[bmorris1]

This comment was not addressed yet.

[bmorris1]

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 

[bmorris1]

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]

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]

Change the last one to just "etc"

[bmorris1]

This should be two separate points

[bmorris1]

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]

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

[bmorris1]

input and output parameters and any return value

[bmorris1]

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

[bmorris1]

Remove the CALLP. Just do the procedure call.

       CalculateOrderTotal(customerId : orderTotal : statusCode);

[bmorris1]

All the free-form snippets must be indented by at least 7 spaces before the code.

This should be an IMPORTANT guideline at the beginning of each of the "explain_*" documents.

(And also fix up all the snippets in these documents. :-)

If you look at the rendered markdown you can see that it doesn't understand the code properly. Here is what yours currently looks like with fewer than 7 spaces. It thinks column 5 is the fixed-form specification type.

    /COPY QRPGLESRC,MYPROTOTYPE
    DCL-S customerId   CHAR(10)   INZ('CUST001');
    DCL-S orderTotal   PACKED(9:2);
    DCL-S statusCode   CHAR(2);
    CALLP CalculateOrderTotal(customerId : orderTotal : statusCode);      

    // After call, orderTotal and statusCode will have updated values

Here it is with 7 spaces:

       /COPY QRPGLESRC,MYPROTOTYPE
       DCL-S customerId   CHAR(10)   INZ('CUST001');
       DCL-S orderTotal   PACKED(9:2);
       DCL-S statusCode   CHAR(2);
       CALLP CalculateOrderTotal(customerId : orderTotal : statusCode);      

       // After call, orderTotal and statusCode will have updated values

[bmorris1]

Add an IMPORTANT guideline at the top of every explain_x file:

IMPORTANT

• All the free-form snippets must be indented by at least 7 spaces before the code.
• All fixed-form snippets must have exactly 5 spaces before the specification type.
• If the rpgle to start the snippet is indented, the 5 or 7 spaces must start at the same indentation as the rpgle line.

[bmorris1]

Add another example with "Input/Update" in the "Used" column. For RPG programmers, "output" only means the equivalent of the SQL "INSERT" statement.

| ORDERS | Data | Input/Update| Updates an order|

[bmorris1]

For the example, put the name of the data structure before the list of subfields.

[bmorris1]

... and anything else that is interesting about the data structure such as whether it is qualified or whether it is an array.

[bmorris1]

I think there should be a standard way of documenting the data types, in a separate file that is linked from anywhere that it mentions types.

And then all the examples in these documents should follow that standard.

I think an extra meeting is needed, with all the participants.

But for now, I think the first thing mentioned should be the type, then any other information

• Character, length 10
• Packed numeric, length 7, with 2 decimals
• Date, *ISO format

[bmorris1]

Data type is also needed for arrays.

These tables would be the same as the variables and data structure tables above with an extra column for the dimension.

But I think it would be better to document arrays with the other variables and data structures. If it's an array, that could just be mentioned as part of the description.

Also, since subfields can be arrays, it would be very complex to list array subfields somehow separate from the data structure.

So for example, in the Variables table above, you could have an example like this:

| MeetingDates | Date, *ISO format | Array with dimension 10, the available dates for meetings |

[bmorris1]

I have only reviewed explain_module.md so far since the meeting on May 26/May 27.

[bmorris1]

It is not necessary to have the /COPY for a scope=proc usage example. For this scope, the assumption is that the call will be in the same module, so the prototype for the call isn't even necessary.

[bmorris1]

I like this way of showing the data type much better than "length 10 character" and also better than "character, length 10".

[Chandra-IBM1]

If any variable is declared using the LIKE keyword to refer to a field from a file, and that file's DDS (Data Description Specifications) is not present in the repository. That what we should mention as data type for that?

[Chandra-IBM1]

Can we follow this way for other type of variable?

Parameter Name	Data Type	Usage	Description
customerId	char(10)	Input/Output	The unique identifier for the customer
orderTotal	packed(9:2)	Input/Output	The total amount of the order calculated
currencyCode	char(3) CONST	Input only	The currency in which the order is placed
taxRate	packed(5:2) VALUE	Input only	The applicable tax rate for the order
orderDate	date(*ISO)	Input/Output	The date the order was placed

or should we follow this way

Name	Type	Usage	Description
customerId	Character, length 10	Input/Output	The unique identifier for the customer
orderTotal	Packed numeric, length 9, with 2 decimals	Input/Output	The total amount of the order calculated
currencyCode	Character, length 3 (CONST)	Input only	The currency in which the order is placed
taxRate	Packed numeric, length 5, with 2 decimals (VALUE)	Input only	The applicable tax rate for the order
orderDate	Date, *ISO format	Input/Output	The date the order was placed

[bmorris1]

I like the first way better.

If it is defined with LIKE, put both pieces of information.

LIKE(somefield), date(*ISO)

[edmundreinhardt]

OK how about
LIKE(somefield) = DATE(*ISO)

But Chandra is asking about whether we give a natural language description
I suspect that this will become very repetitive if we always do it. The end user only needs to learn once what PACKED means.

[bmorris1]

If any variable is declared using the LIKE keyword to refer to a field from a file, and that file's DDS (Data Description Specifications) is not present in the repository. That what we should mention as data type for that?

If the meaning of the LIKE keyword is not known, then just put "LIKE(name)" for the type. And then if there is some indication of the type, such as an assignment, put something in the description such as "Likely a numeric type"

[bmorris1]

I agree that a natural language description is not necessary for data types.

[bmorris1]

Many of the comments I made for explain_module also apply to this document.

[bmorris1]

Change this:

2. The program call.

• If there is an RPG prototype for the program, use an rpgle snippet with the /COPY for the prototype, and any definitions needed for parameters. Do not use the CALL or CALLP opcode.

       /copy qrpglesrc,prototype
              
       mypgm (parameters);

• Otherwise, use a clle snippet to represent a call from the command line.

call mypgm parm(parameters)

[bmorris1]

change "program" to "subroutine" in several places in this file.

[bmorris1]

Is this section really needed for a subroutine?

[Chandra-IBM1]

Yes, I believe it's important to document any external programs, APIs, data areas, or data queues that the program interacts with

[bmorris1]

Don't mention indicators here. There is already too much focus on indicators.

Instead, say this:

This section lists the global elements used by the subroutine, such as variables and files.

[bmorris1]

This is a general comment for all the explain files. Also show an example table for an indds. I think the good layout for an indds table has already been established but I don't know where it is. But I think the following would be a good way to show an INDDS.

• Indicator data structure myIndds for display file MYDSPF

  Subfield name	Indicator number	Description
  exit	03	Indicates that the user pressed F3
  sfl_clear	55	Used to clear the subfile
  error	99	Used to show error messages

[bmorris1]

Many of my comments apply to all the explain files.

I have not looked at the sample files yet. I will review those after changes are made according to the explain documents.

[bmorris1]

Don't define any variables for calling a subroutine.

Before the EXSR, set the values for any input variables.

After the EXSR, show how to use the output variables.

       InputVar = 'abc';
       EXSR MySubroutine;       
       If OutputVar > 5;
        ...

[bmorris1]

Define data structures using LIKEDS with the name of the data structure defined in the /COPY file.

[bmorris1]

The 7 spaces before the code must start in the same column as the ```rpgle

With only 5 extra spaces

     /COPY QRPGLESRC,MYPROTOTYPE

     DCL-S customerId   CHAR(10)   INZ('CUST001');
     DCL-S orderTotal   PACKED(9:2);
     DCL-S statusCode   CHAR(2);

With 7 extra spaces
example:

       /COPY QRPGLESRC,MYPROTOTYPE

       DCL-S customerId   CHAR(10)   INZ('CUST001');
       DCL-S orderTotal   PACKED(9:2);
       DCL-S statusCode   CHAR(2);

[bmorris1]

This is rendered as part of the example. I think it is because it is indented too much.

[bmorris1]

I don't think it is good to have arrays documented separately from other variables. My earlier suggestion was to avoid having an extra section for arrays, and just put dimension information as part of the description.

But if arrays will be separate, then data structure arrays should be included in the "arrays" section. Or there should be a separate "Data structure arrays" section.

[bmorris1]

I added a few more comments to the explain documents.