The API Corner Understanding API Data Types

7/27/2019 The API Corner Understanding API Data Types

1/12

The API Corner: Understanding API Data Types

Contributed by Bruce ViningTuesday, 19 February 2008Last Updated Thursday, 05 June 2008

In a previous column, we discussed the basics of the API error code structure. In today's column, we'll talk about thebasic API data types found in callable APIs and exit points.

By Bruce Vining System APIs use a language-neutral convention when defining the type and size of data that is to be used as aparameter or a subfield of a data structure. A typical API parameter list would be the Retrieve Member DescriptionQUSRMBRD API shown below and documented here.

In a previous column, we discussed the basics of the API error code structure. In today's column, we'll talk about thebasic API data types found in callable APIs and exit points.

System APIs use a language-neutral convention when defining the type and size of data that is to be used as aparameter or a subfield of a data structure. A typical API parameter list would be the Retrieve Member DescriptionQUSRMBRD API shown below and documented here.

Retrieve Member Description (QUSRMBRD) API Required Parameter Group:

1 Receiver variable Output

Char(*)

MC Press Online

http://www.mcpressonline.com Powered by Joomla! Generated: 28 August, 2008, 23:42


2/12

2

Length of receiver variable Input

Binary(4) 3 Format name

Input Char(8)

4 Qualified database file name Input

MC Press Online



3/12

Char(20) 5

Database member name Input

Char(10) 6

Override processing Input Char(1)

Optional Parameter Group 1: 7

MC Press Online



4/12

Error code I/O

Char(*)

Optional Parameter Group 2:

8 Find member processing

Input Char(1)

The API documentation, in the fourth column above, is defining the attributes associated with various parameters that areto be passed to the API. Most system APIs utilize only two types of data (character and binary) and define the size, orlength, of the data in terms of bytes. So in the case of character data, the third parameter of QUSRMBRD, Format name,is defined as a Char (or character) field with a fixed length of eight bytes. Likewise, the fourth parameter, Qualifieddatabase file name, is a Char field with a fixed length of 20 bytes and the sixth parameter, Override processing, a Charfield of one byte. You'll notice that two of the parameters, Receiver variable and Error code, do not specify a fixed length.Rather, they use a length of '*'. The '*' is a special value indicating that the parameter is of variable length and that you,

MC Press Online



5/12

the caller of the API, control (within certain boundaries) the actual size of the parameter being passed. Quite oftenparameters defined as Char(*) are actually data structures and within the data structure will be fixed-size subfields. Youwill also find in the API documentation that some of the fixed-length Char parameters are also data structures. Qualifieddatabase file name, for instance, is actually a data structure with two subfields: a Char(10) file name and a Char(10)library name.

The second parameter, Length of receiver variable, is defined as a Binary field with a fixed length of four bytes. Thisdefinition for a binary, or integer, field can be a source of confusion to RPG developers and is a common pitfall when firstusing APIs. The pitfall is that the RPG developer may code the parameter/field using a number of digits specification asshown below:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords++++++++

dLenRcvVar s 4b 0

This definition "looks" right but, unfortunately, is wrong. What is being defined above is a binary field capable of holding anumeric value ranging from 1 to 4 digits in size. As a binary format can represent four digits in two bytes, RPG will onlyallocate two bytes for the field LenRcvVar (Length of receiver variable). As the API expects four bytes to be passed, thisis not going to work very well, and rather unpredictable errors can occur at run time. The correct definition of a Binary(4)can be done using any one of the below statements:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords++++++++

* Standalone fields

MC Press Online



6/12

dLenRcvVar s 9b 0

dLenRcvVar s 10i 0 (A)

* Data structure subfields

d LenRcvVar 1 4b 0

d LenRcvVar 1 4i 0 (B)

d LenRcvVar 9b 0

d LenRcvVar 10i 0 (C)

I'll point out that the use of the 'i' data type (examples A, B, and C above) is the preferred method. And if it helps any, Cdevelopers when first using system APIs also run into a common pitfall: They tend to interpret Char(*) as a pointer to acharacter string, which also "looks" right to them, but isn't.

As this binary definition confusion is a reasonably common problem for RPG developers, it has been suggested in the

MC Press Online



7/12

past that IBM change the documentation of binary fields from Binary(4) to something more RPGish. While IBM may makesuch a change in the future, my hope is that the documentation (at least in this regard) remains the same. One reasonfor this hope is that RPG continues to evolve. If back in V1R3, when system APIs were first introduced, IBM had used aconvention such as Binary(9) to represent a 4-byte binary field, then V3R2/V3R6 and ILE RPG's introduction of the 4-byte integer data type might have introduced an unnecessary dilemma: namely, should IBM change the APIdocumentation to Integer(10) to reflect the new RPG definition style? If so, wouldn't the pitfall discussed above simply bereintroduced for RPG/400 and ILE users of the binary data type? Binary(10) or Integer(10) would also certainly be moreaccurate as developers familiar with binary data would know that a 4-byte binary field can indeed represent 10 digits of

information. It's only for historical reasons that RPG (and some other parts of the system) constrains 4-byte binarydefinitions to nine digits.

Related to this, having a language-neutral specification for API documentation also avoids the false perception of theSystem i being a RPG machine: a marketing perception any fan of the System i would want to avoid in order to enhance

acceptance of the system in the marketplace. Other languages that are generally available for application developmenton i5/OS define a 4-byte integer field in various ways, none of which by the way are Binary(4)! In COBOL, you might use'PIC S9(9) BINARY', in C 'int', in CL (or at least in current releases of CL) 'Type(*Int) Len(4)', and so on. Using a neutraldefinition such as Binary(4) puts all development languages on a somewhat level field; everyone has to learn what itmeans.

To digress a little, this type of language neutrality reminds me of the "acronym" UTC for Coordinated Universal Time.UTC is not a true acronym; it's a compromise between the English Coordinated Universal Time (CUT) and FrenchTemps Universel Coordonn (TUC). And so Binary(4) is a compromise between the various programming languagesavailable today and in the future.

The good thing is that once learned, it's very easy to remember.

An API data structure is defined using a similar style. Below is the API documentation for the MBRD0100 format of theQUSRMBRD API.

MC Press Online



8/12

MBRD0100 Format

Offset Type

Field Dec

Hex 0 0

BINARY(4) Bytes returned 4

MC Press Online



9/12

4

BINARY(4) Bytes available 8

8 CHAR(10)

Database file name 18

12 CHAR(10) Database file library name 28

MC Press Online



10/12

1C

CHAR(10) Member name

38 26 CHAR(10)

File attribute 48

30 CHAR(10) Source type

MC Press Online



11/12

58 3A

CHAR(13) Creation date and time

71 47 CHAR(13)

Last source change or table refresh date and time 84

54 CHAR(50) Member text description

MC Press Online



12/12

134 86

CHAR(1) Source file

As you can hopefully see, the knowledge acquired about parameter data types is easily transferred to data structure datatypes. There are a few additional data types that you may encounter over time. These include pointers (a data type ofPTR and implicitly defined as 16-bytes); Binary(2) fields, which you should successfully interpret as 2-byte binary fieldsafter reading this column; and Packed(x,y) for packed decimal fields with x digits, y digits of which are to the right of thedecimal point. These additional types do not however come up very often.

With this introduction to API data types, you should be well on your way toward successfully understanding how to utilizei5/OS system API documentation.

Meanwhile, if you have other API questions, send them to Bruce at [email protected]'ll see what he can doabout answering your burning questions in future columns.

MC Press Online


Documents

The API Corner Understanding API Data Types