Search code examples
ibm-midrange

Is there a method to set the value for the Return code (RTNCDE) parameter of the Retrieve Job Attributes (RTVJOBA) command


The following documents that the Return Code (RTNCDE) value available from the Retrieve Job Attribute (RTVJOBA) command is returned as DECIMAL(5, 0) and later clarifies in the thread-safety information\table that the value is actually called [more accurately to be referred to as] the Program Return Code and that the value is not thread-safe, from which we can conclude safely that there is no thread-specific support for setting this value:
http://www.ibm.com/support/knowledgecenter/ssw_ibm_i_71/cl/rtvjoba.htm#RTVJOBA.RTNCDE

Retrieve Job Attributes (RTVJOBA)
CL var for RTNCDE (5 0) (RTNCDE)
Specifies the name of the CL variable that receives the 5-digit decimal return code of an RPG, COBOL, DFU, or sort utility program. The return code is set by these programs before they return to the programs that call them. The return code indicates the completion status of the last program (of these types) that has completed processing within the job, as follows:
...

Attribute Scope and Thread Safety Table: Attribute Scope Threadsafe
Program return code (RTNCDE) Job No

Visiting the [unlikely drill-down\navigation of Programming->Control language->CL programming->Compiling CL source program->Return code summary] can be found some documentation for the use of that retrieved value; an unlikely place, because the CL compilers apparently do not set the value, nor do CL procedures or programs:
http://www.ibm.com/support/knowledgecenter/ssw_ibm_i_71/rbam6/retcs.htm

Return code summary

A return code can be returned using the Return code (RTNCDE) parameter on the Retrieve Job Attributes (RTVJOBA) command.

The return code is a 5-digit decimal value with no decimal positions (12345. for example). The decimal value indicates the status of called programs. CL programs do not set the return code. However, you can retrieve the current value of the return code as set by another program in a CL program. You can do this by using the RTNCDE parameter of the Retrieve Job Attributes (RTVJOBA) command.

The following list summarizes the return codes used by languages supported on the IBM® i operating system:
...

In the above list [omitted from the quoted docs] are the RPG compilers and program, COBOL compilers and programs, and C programs. Missing from the above list is CL compilers or CL; as well, any mention of DFU programs and the Sort Utility feature, which are both mentioned in the prior included doc reference. The only mention of CL is the prior mention of but you can use RTVJOBA to read the value... OK, but only as returned by other programs and compilers, not what was the effective return code of the CL procedure or program I just called!

So... And what I want to know, is despite that CL does not set the value [good because I want to have my CL program set the value], can a CL program be used to set the value because the CL program does not do so implicitly; conspicuously, per the compiled run-time object does not [¿and does not intend to?] include any code to set a return code?

If nothing else [likely, as the most probable response will be the undesirable recommendation to "Write a program with system-state to modify the value...", then please only if also accompanied by documentation [by your own research; I realize there is unlikely to be any public documentation] of the location of the value [for posterity as I am unlikely to actually code anything], presumably as a value stored in the Process Control Space (PCS); see: DMPSYSOBJ *PCS


The following, as the most likely method capable, documents nothing about the ability to change the Return Code:
http://www.ibm.com/support/knowledgecenter/ssw_ibm_i_71/apis/qwtchgjb.htm

Change Job (QWTCHGJB) API

P.S. if someone knows of and could provide a link to the documentation alluded for the Product Return Code in the following link, specifically for the ILE CL Compiler, so I might learn more about that value; another return-code, but somewhat off-topic to my question:
http://www.ibm.com/support/knowledgecenter/ssw_ibm_i_71/apis/WMAttrDesc.htm

Product return code. The return code set by the compiler for Integrated Language Environment® (ILE) languages. Refer to the appropriate ILE-conforming language manual for possible values. This field is scoped to the job and represents the most recent return code set by any thread within the job.
...


Solution

  • Edit: I forgot that you wanted a program to set it. The one I posted first just retrieves it.

    This program will set the "Language/Utility return code" from the "LU Work Area" which is the one that is set by OPM and ILE RPG. It's the same return code that shows on page 1 of DSPJOB.

    I think OPM COBOL sets this return code, but if I recall correctly, ILE COBOL sets one of the other return codes in the LU work area. ILE C also sets one of the other return codes.

    pgm
        /*------------------------------------------------------------*/
        /* From QSYSINC/H MILIB:                                      */
        /*                                                            */
        /* typedef volatile struct _LU_Work_Area_T {                  */
        /*   short LU_RC;             -- Language/Utility return code */
        /*   ...                                                      */
        /* } _LU_Work_Area_T;                                         */
        /* ...                                                        */
        /* _SPCPTR  _LUWRKA    ( void );                              */
        /*------------------------------------------------------------*/
        dcl &luwrka_p type(*ptr)
        dcl &luwrka   type(*char) stg(*based) basptr(&luwrka_p)
          dcl &lu_rc  type(*int) len(2) +
                      stg(*defined) defvar(&luwrka 1)
    
        callprc '_LUWRKA' rtnval(&luwrka_p)
        chgvar &lu_rc 5
    
    endpgm