Re: Prototypes for System APIs

[Brian Parkins <goodprophet.bp@xxxxxxxxx>]

Frank, just to clarify. An API parameter defined as OUTPUT CHAR(*) is 
NOT a Pointer variable. More accurately, it is a fixed length character 
variable whose length is determined by the caller.

Take the example of the QUSRTVUS (Retrieve User Space) API:

Required Parameter Group:
1     Qualified user space name     Input     Char(20)
2     Starting position     Input     Binary(4)
3     Length of data     Input     Binary(4)
4     Receiver variable     Output     Char(*)
Optional Parameter Group:
5     Error code     I/O     Char(*)

Parameters 4 and 5 are NOT Pointer variables; the prototype would look 
something like:
  // Prototype for QUSRTVUS - Retrieve User Space
Dcl-Pr RtvUsrSpc   ExtPgm('QUSRTVUS');
  QualSpaceName     Char(20) Const;
  StartPosition     Int(10) Const;
  LengthOfData      Int(10) Const;
  Receivervariable  Char(250) Options(*Varsize); // 250 char allocated 
- could be less
  ErrorCode         Char(100) Options(*Varsize:*NoPass); // 100 char 
allocated - could be less
End-Pr;

However, for the QUSPTRUS (Retrieve Pointer to User Space):

Required Parameter Group:
1     Qualified user space name     Input     Char(20)
2     Return pointer     Output     PTR(SPP)
  Optional Parameter:
3     Error code     I/O     Char(*)

The paramter 2 IS a Pointer variable; the prototype would look something 
like:
  // Prototype for QUSPTRUS - Retrieve Pointer to User Space
Dcl-Pr RtvUsrSpPtr ExtPgm('QUSPTRUS');
  QualSpaceName     Char(20) Const;
  SpacePointer      Pointer;
  ErrorCode         Char(100) Options(*Varsize:*Nopass); // 100 char 
allocated - could be less
End-Pr;

Having said all that, of course we are passing ALL parameters by 
reference, (address). So, strictly speaking, all the above could be 
described as pointers!

HTH,
Brian.

On 01/12/2018 08:30, Frank Kolmann wrote:
> The pointer variables such as 1 Receiver variable Output Char(*) below 
> for QDFRTVFD can be a mystery.