Re: API parm confusion

["Simon Coulter" <shc@xxxxxxxxxxxxxxxxx>]

Hello Tom,

I see Bruce has provided a COBOL example for this API so I shan't do that
but I will try to clarify some things for you.

You wrote:
>First, the full description of buf includes "The buffer must be large
>enough to contain the full path name including the terminating NULL
>character." Since I don't know what the path name is until after the API
>returns, how can I know how large buf should be?

I believe a path name can be 16MB architecturally but there appears to be
a practical limit of 1024 characters.  Therefore you could always use a
variable of 1025 bytes (1 extra for the terminating NULL) or allocate that
much storage dynamically.  However, if the space you provide is too small
(determined because you specify how much space you have in the second
parameter of Qp0lGetPathFromFileID) the API will set errno to ERANGE.  The
documentation is quite specifc about this behaviour.  You would allocate
more space and try again.

>Second, buf is described as being both 'output' and 'pointer'. What does
>that mean? If I pass a pointer, is the API going to change it ('output')?

It just means the contents of the buffer is output (i.e, what the pointer
addresses, not the pointer itself)

>If so, how do I associate it with the "buf" that I've somehow managed to
>make "...large enough to contain the full path name including the
>terminating NULL character"? The only thing that makes minimal sense is a
>LINKAGE item that I've set ADDRESS OF to null.

Just pass the address of the buffer.  Remember C expects parameter types
other than arrays to be passed by value.  The prototype for
Qp0lGetPathFromFileID is

        char *Qp0lGetPathFromFileID(char *, size_t, Qp0lFID_t);

That means the first parameter is a pointer by value, the second is an
unsigned integer by value (we know it is an unsigned integer because we
can locate its definition in half a dozen C headers), and the third is an
array by reference (we know it is an array because it is defined as [16]
characters and we know it is passed by reference because that's how C
handles arrays).

Remember also that passing a pointer by value is EXACTLY the same as
passing a variable by reference.  Since COBOL has good support for
variables it is more obvious to use the variable directly rather than the
address of the variable.

>Is there sense to be made of this in COBOL?

Yes, using the above information we get:

        USING     BY REFERENCE for parameter 1
                  BY VALUE     for parameter 2
                  BY REFERENCE for parameter 3

Since the API returns a pointer to the first parameter (i.e., the returned
pointer will have the same value as the address of parameter 1) you can
use this to check if the API was successful.  If the returned pointer is
NULL then the API failed and you should check the errno global variable to
determine the problem.  Here is an example of accessing errno:

       PROCESS NOMONOPRC.
       IDENTIFICATION DIVISION.
       PROGRAM-ID. ERRNO_CBL.
       ENVIRONMENT DIVISION.
       CONFIGURATION SECTION.
         SOURCE-COMPUTER. IBM-AS400.
         OBJECT-COMPUTER. IBM-AS400.
       SPECIAL-NAMES.
       LINKAGE TYPE PROCEDURE FOR "__errno".
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  ERRNO-POINTER       POINTER.
       LINKAGE SECTION.
       01  ERRNO                PIC S9(9) BINARY.
       PROCEDURE DIVISION.
       MAIN-LINE.
           CALL "__errno" GIVING ERRNO-POINTER.
           SET ADDRESS OF ERRNO TO ERRNO-POINTER.
           DISPLAY "errno: " ERRNO.
           STOP RUN.

Note that this is a trivial example and errno will always be zero in this
case.

Regards,
Simon Coulter.
--------------------------------------------------------------------
   FlyByNight Software         AS/400 Technical Specialists
   http://www.flybynight.com.au/

   Phone: +61 3 9419 0175   Mobile: +61 0411 091 400        /"\
   Fax:   +61 3 9419 0175   mailto: shc@flybynight.com.au   \ /
                                                             X
                 ASCII Ribbon campaign against HTML E-Mail  / \
--------------------------------------------------------------------