Re: which api's are in which service programs? -- COBOL400-L


On 13/10/2006, at 4:48 AM, Adrienne McConnon wrote:

Now for another question, I now see that my assumption that QWCLOBJL
listed as an API is what initally threw me off.  I assumed I would find
it in a service program.  Is there a command that will help me avoid
this confusion in the future? Is there a WHATISTHISOBJ command or
something like it?  Of course once I realized it was a program - the
WRKOBJ command showed that - I suppose that will be my starting point
next time I need to determine what type an object is.

It's commonly known as documentation. If it doesn't say anythingspecial then it is probably a *PGM object. In general, APIs with8-character (or less) upper-case names are *PGM objects. APIs withlonger names or lower-case characters are bindable. Documentation forbindable APIs also includes the service program name or bindingdirectory name. For almost all IBM bindable APIs you don't need to doanything except spell them correctly and call them correctly by usingCALL PROGRAM or CALL PROCEDURE as appropriate. The compilersautomatically use a system binding directory that allows them to findthe bulk of the APIs. One of the few exceptions is when callingC-runtime functions. These are not found automatically and you'll needto specify the QC2LE binding directory. Other exceptions can includeAPIs for a specific program product.


For example:

Release Profile Handle (QSYRLSPH, QsyReleaseProfileHandle) API

Required Parameter Group for QSYRLSPH:
1       Profile handle  Input   Char(12)

Optional Parameter for QSYRLSPH:
2       Error code              I/O             Char(*)

Default Public Authority: *USE
Threadsafe: Yes


Syntax for QsyReleaseProfileHandle:
#include <qsyphandle.h>

void QsyReleaseProfileHandle
            (unsigned char * Profile_handle,
             void          * Error_code);

Service Program: QSYPHANDLE
Default Public Authority: *USE
Threadsafe: Yes

The title tells you there are two interfaces: QSYRLSPH andQsyReleaseProfileHandle. Given teh guidelines above you can guess whichis which.

There are two interface descriptions: The first shows the parametersfor QSYRLSPH, and the second shows QsyReleaseProfileHandle but theyboth result in the same underlying code being run.

The interface description for QsyReleaseProfileHandle also names theservice program containing the API. If that's not enough to make adistinction then the first sentence in the documentation explains itfurther.

"The Release Profile Handle (OPM, QSYRLSPH; ILE,QsyReleaseProfileHandle) API validates a given profile handle and thenreleases it."

Notice the use of the terms OPM and ILE? In this case OPM=*PGM andILE=bindable function.


The only remaining confusion is:

1) The presumption that bindable APIs will only ever be called from C(hence the #include rubbish, and void * etc. definitions) requiringCOBOL and RPG IV programmers to translate C data types into COBOL orRPG IV equivalents.2) The presumption that ILE languages will only ever use the bindableinterface (hence the misuse of OPM and ILE). For ILE COBOL and RPG IVthe OPM interface is often easier to use because the bindableinterfaces frequently make the short-sighted assumption that they willonly be invoked from C and use parameters that are easy to use in C(because of direct language support) but a bit harder in COBOL and RPGIV.


Practice and familiarity will make this easier.

Regards,
Simon Coulter.
--------------------------------------------------------------------
   FlyByNight Software         iSeries Technical Specialists

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