EntireX Broker ACI for RPG

ACI stands for Advanced Communication Interface. ACI-based programming is the base technology of EntireX. It uses a traditional Application Programming Interface (API) approach for conducting client/server and peer-to-peer dialog between distributed processes.

This document describes the EntireX Broker ACI from the perspective of the programming language RPG. It covers the following topics:

See also EntireX Broker ACI Programming for an introduction to ACI programming, a description of ACI fields and functions, and information on writing ACI applications.


Call Format

Calls to EntireX Broker use the following arguments:

  1. The ACI control block is the first argument.

  2. The send buffer is the second argument.

  3. The receive buffer is the third argument.

  4. The error text buffer is the last argument. It can provide a short text of the error code, if desired. Sufficient buffer length must be supplied to allow the standard 40-byte-long message to be returned by EntireX Broker. For ACI version 9 and above, the error text buffer can be greater than 40 bytes as specified in the ACI field ERRTEXT-LENGTH.

The send buffer and the receive buffer must always be provided. If they are not required by the selected EntireX Broker function, you can define them as PIC X(1) fields.

The API is called with a statement as follows:

C...CALLB(D) 'broker'
C...PARM ETBCB
C...PARM G_SEND_BUFF
C...PARM G_RECV_BUFF
C...PARM ERROR_TEXT

Broker ACI Control Block Layout

The following table shows the Broker fields in the order of the physical layout of the Broker ACI control block and provides a brief description of each field. See the actual copybook for RPG below in Broker ACI Control Block Copybook.

See Broker ACI Fields for more information.

Broker ACI Field RPG Definition Description /
Related Information
API
Vers.
Notes
API-TYPE ETB_TYPE 1 API type. See API-TYPE and API-VERSION. 1  
API-VERSION ETB_VERSION 1 API version. 1  
FUNCTION ETB_FUNCTION 1 See Broker ACI Functions to perform Broker function. 1  
OPTION ETB_OPTION 1 See Option Descriptions. 1  
  RESERVED 16 Reserved for future use. 1 1
SEND-LENGTH ETB_SEND_LEN 10I Send length. See Using Send and Receive Buffers. 1  
RECEIVE-LENGTH ETB_RECV_LEN 10I Receive length. See Using Send and Receive Buffers. 1  
RETURN-LENGTH ETB_RETN_LEN 10I Return length. 1  
ERRTEXT-LENGTH ETB_ERRT_LEN 10I Error text length. 1  
BROKER-ID ETB_BROKER_ID 32 Broker ID. See Using the Broker ID in Applications. 1  
SERVER-CLASS
SERVER-NAME
SERVICE
ETB_SERV_CLAS 32
ETB_SERV_NAME 32
ETB_SERVICE 32
Service. See Control Block Fields and Verbs. 1 3,5
USER-ID ETB_USERID 32 User ID. See USER-ID and TOKEN. 1  
PASSWORD ETB_PASSWD 32 Password. See Authentication. 1 4,5
TOKEN ETB_TOKEN 32 Reconnection token. See USER-ID and TOKEN. 1 3,5
SECURITY-TOKEN ETB_SEC_TOKEN 32 Security token. See Role of Security Token (STOKEN) during Authentication. 1 4,5
CONV-ID ETB_CONV_ID 16 Conversation ID. See Conversational and Non-conversational Mode. 1 3,5
WAIT ETB_WAIT_TOUT 8 Wait value. See Blocked and Non-blocked Broker Calls. 1 3,5
ERROR-CODE ETB_ERR_CODE 8 Error code. See Error Handling and Error Messages and Codes. 1  
ENVIRONMENT ETB_ENVIRON 32 Pass additional information to Translation User Exit. For more information see ACI field ENVIRONMENT. 1 3,5
ADCOUNT ETB_ADCOUNT 10I Attempted delivery count. See Writing Applications: Units of Work. 2  
USER-DATA ETB_USER_DATA 16 Conversation User Data. See Managing Conversation Contexts. 2 3,5
Not used. ETB_MSG_ID 32 Message ID. 2 4,5
Not used. ETB_MSG_TYPE 16 Message type. 2 3,5
  ETB_PTIME 8 Reserved for future use. 2 1,3,5
NEWPASSWORD ETB_NEW_PWD 32 New password. See Changing your Password. 2 4,5
Not used. ETB_ADAPT_ERR 8 Adapter error. 2  
CLIENT-UID ETB_CLIENT_UID 32 Client user ID. See Client User ID. 2  
CONV-STAT ETB_CONV_STAT 1 Conversation status. See Conversational and Non-conversational Mode. 2  
STORE ETB_STORE 1 Persistence or non-persistence of a UOW. See Writing Applications: Units of Work. 2  
  ETB_STATUS 1 Reserved for future use. 2 1
UOWSTATUS ETB_UOW_STAT 1 UOW Status. See Writing Applications: Units of Work. 3 3,5
UWTIME ETB_UOW_TIME 8 UOW lifetime. 3 3,5
UOWID ETB_UOW_ID 16 UOW unique identifier. 3 3,5
USTATUS ETB_USER_STAT 32 User status. 3  
UOW-STATUS-PERSIST ETB_STAT_PERS 1 Multiplier for persistent status lifetime. 3 2
  ETB_UOWLATER 3 Reserved for future use. 3 1
LOCALE-STRING ETB_LOCALE_STR 40 Locale string. To be used to override or provide a codepage name to tell the broker the encoding of the data. For more information see ACI field LOCALE-STRING. 4  
DATA-ARCH ETB_DATA_ARCH 1
Data architecture. 4 2
FORCE-LOGON ETB_FORCE_LGON 1 Override Broker AUTOLOGON. See FORCE-LOGON. See Writing Applications using EntireX Security. 6  
  ETB_ENC_LEVEL 1 Deprecated. 6 2
KERNELSECURITY ETB_KERSEC 1 Kernel security. See Is Broker Kernel Secure?. 7  
COMMITTIME ETB_COMMTIME 17 Commit time. See Writing Applications: Units of Work. 7  
COMPRESSLEVEL ETB_COMPLVL 1 Compression level. See Data Compression. 7  
  ETB_RESVD3 2 Reserved for future use. 7 1
  ETB_RESVD4 4 Reserved for future use. 7 1
UWSTAT-LIFETIME ETB_UWSTATLIFE 8 Add value for persistent status lifetime. See UWSTAT-LIFETIME. 8  
  ETB_RESVD_V91_1 96 Reserved for future use. 8 1
  ETB_RESVD_V91_2 16 Reserved for future use. 8 1
  ETB_RESVD_V99_1 32 Reserved for future use. 8 1
  ETB_RESVD_V73_1 10I Reserved for future use. 8 1
  ETB_RESVD_V73_2 10I Reserved for future use. 8 1
  ETB_RESVD_V73_3 10I Reserved for future use. 8 1
CLIENT-ID ETB_CLIENT_ID 10I Returns to a server application the unique instance number of a client application. It is returned on receipt of a message (RECEIVE or SEND with WAIT). 9  
LOG-COMMAND ETB_LOG_COMMAND 1 Log the current command. See also Programmatically Turning on Command Logging. 9  
CREDENTIALS-TYPE ETB_CRED_TYPE 1 Indicates the credentials type to be used to authenticate a user. The default is to use user ID and password. 9  
VARLIST-OFFSET ETB_VAR_LIST_OFF 10I Internal Software AG field. 10  
LONG-BROKER-ID-LENGTH ETB_LONG_BROKER_ID_LEN 10I See LONG-BROKER-ID-LENGTH. 10  
MESSAGE-ID ETB_NEW_MSG_ID 64 See Unique Message ID under Broker ACI Functions. 11  
CORRELATION-ID ETB_COR_ID 64 CORRELATION-ID. 11  
USE-SPECIFIED-MESSAGE-ID ETB_USE_MSG_ID 1 Use supplied MESSAGE-ID for SEND. 11  
USE-SPECIFIED-CORRELATION-ID ETB_USE_COR_ID 1 Send supplied CORRELATION-ID to Broker. 11  
  ETB_RESVD6 3 Reserved for future use. 11  
  ETB_RESVD7 10I Reserved for future use. 11  
LONG-PASSWORD-LENGTH ETB_LONG_PSWD_LEN 10I Length of long password. See Authentication. 12  
LONG-NEWPASSWORD-LENGTH ETB_LONG_NEW_PSWD_LEN 10I Length of long new password. See Changing your Password. 12  

Notes:

  1. Reserved for future use.
  2. You must set this field to a low value (X'00') if you do not intend to use it.
  3. The field is transmitted up to the first blank or low value (X'00'). It is not transmitted if the first character is a blank or a low value (X'00').
  4. All trailing low values (X'00') are truncated. The field is not transmitted if the entire field is a low value (X'00').
  5. If fields are not needed for a specific command function, suppress their transmission by initializing them to blanks or low value (X'00').

Broker ACI Control Block Copybook

EntireX provides a copybook with the ACI control block definition. See ACI Examples and Copybooks for where it is provided on your platform:

      ******************************************************************
      * Product        : EntireX Broker
      * Copyright      : Copyright (c) 1997 - 2020 Software AG,
      *                  Darmstadt, Germany and/or Software AG USA,
      *                  Inc., Reston, VA, United States of America,
      *                  and/or their licensors.
      * Version        : 10.7
      * File Version   : $Revision: 1.37 $
      * File           : RPGDEF
      * Description    : RPG ACI control block definitions.
      ******************************************************************
      *
     H DECEDIT('0,') DATEDIT(*DMY.)
      *
      *--------------- TYPE CONSTATNTS -------------------------------------
     D TYPES           DS
     D TYPE_1_I                       5I 0 INZ(1)
     D TYPE_1                         1    OVERLAY(TYPE_1_I:2)
      *
      *--------------- VERSION CONSTANTS -----------------------------------
     D VERSIONS        DS
     D VERSION_1_I                    5I 0 INZ(1)
     D VERSION_1                      1    OVERLAY(VERSION_1_I:2)
     D VERSION_2_I                    5I 0 INZ(2)
     D VERSION_2                      1    OVERLAY(VERSION_2_I:2)
     D VERSION_3_I                    5I 0 INZ(3)
     D VERSION_3                      1    OVERLAY(VERSION_3_I:2)
     D VERSION_4_I                    5I 0 INZ(3)
     D VERSION_4                      1    OVERLAY(VERSION_4_I:2)
     D VERSION_5_I                    5I 0 INZ(3)
     D VERSION_5                      1    OVERLAY(VERSION_5_I:2)
     D VERSION_6_I                    5I 0 INZ(3)
     D VERSION_6                      1    OVERLAY(VERSION_6_I:2)
     D VERSION_7_I                    5I 0 INZ(3)
     D VERSION_7                      1    OVERLAY(VERSION_7_I:2)
     D VERSION_8_I                    5I 0 INZ(3)
     D VERSION_8                      1    OVERLAY(VERSION_8_I:2)
     D VERSION_9_I                    5I 0 INZ(3)
     D VERSION_9                      1    OVERLAY(VERSION_9_I:2)
     D VERSION_10_I                   5I 0 INZ(3)
     D VERSION_10                     1    OVERLAY(VERSION_10_I:2)
     D VERSION_11_I                   5I 0 INZ(3)
     D VERSION_11                     1    OVERLAY(VERSION_11_I:2)
     D VERSION_12_I                   5I 0 INZ(3)
     D VERSION_12                     1    OVERLAY(VERSION_12_I:2)
      *
      *--------------- FUNCTION CONSTANTS ----------------------------------
     D FCT             DS
     D FCT_SEND_I                     5I 0 INZ(1)
     D FCT_SEND                       1    OVERLAY(FCT_SEND_I:2)
     D FCT_RECEIVE_I                  5I 0 INZ(2)
     D FCT_RECEIVE                    1    OVERLAY(FCT_RECEIVE_I:2)
     D FCT_UNDO_I                     5I 0 INZ(4)
     D FCT_UNDO                       1    OVERLAY(FCT_UNDO_I:2)
     D FCT_EOC_I                      5I 0 INZ(5)
     D FCT_EOC                        1    OVERLAY(FCT_EOC_I:2)
     D FCT_REG_I                      5I 0 INZ(6)
     D FCT_REGISTER                   1    OVERLAY(FCT_REG_I:2)
     D FCT_DEREG_I                    5I 0 INZ(7)
     D FCT_DEREG                      1    OVERLAY(FCT_DEREG_I:2)
     D FCT_VERSION_I                  5I 0 INZ(8)
     D FCT_VERSION                    1    OVERLAY(FCT_VERSION_I:2)
     D FCT_LOGON_I                    5I 0 INZ(9)
     D FCT_LOGON                      1    OVERLAY(FCT_LOGON_I:2)
     D FCT_LOGOFF_I                   5I 0 INZ(10)
     D FCT_LOGOFF                     1    OVERLAY(FCT_LOGOFF_I:2)
     D FCT_SET_I                      5I 0 INZ(11)
     D FCT_SET                        1    OVERLAY(FCT_SET_I:2)
     D FCT_GET_I                      5I 0 INZ(12)
     D FCT_GET                        1    OVERLAY(FCT_GET_I:2)
     D FCT_SYNC_I                     5I 0 INZ(13)
     D FCT_SYNC                       1    OVERLAY(FCT_SYNC_I:2)
     D FCT_KERNEL_I                   5I 0 INZ(14)
     D FCT_KERNEL                     1    OVERLAY(FCT_KERNEL_I:2)
     D FCT_REPLYERR_I                 5I 0 INZ(22)
     D FCT_REPLYERR                   1    OVERLAY(FCT_REPLYERR_I:2)
     D FCT_GET_MSG_ID_I               5I 0 INZ(26)
     D FCT_GET_MSG_ID                 1    OVERLAY(FCT_GET_MSG_ID_I:2)
      *
      *--------------- OPTION CONSTANTS ------------------------------------
     D OPT             DS
     D OPT_MSG_I                      5I 0 INZ(1)
     D OPT_MSG                        1    OVERLAY(OPT_MSG_I:2)
     D OPT_HOLD_I                     5I 0 INZ(2)
     D OPT_HOLD                       1    OVERLAY(OPT_HOLD_I:2)
     D OPT_IMMED_I                    5I 0 INZ(3)
     D OPT_IMMED                      1    OVERLAY(OPT_IMMED_I:2)
     D OPT_QUIESCE_I                  5I 0 INZ(4)
     D OPT_QUIESCE                    1    OVERLAY(OPT_QUIESCE_I:2)
     D OPT_EOC_I                      5I 0 INZ(5)
     D OPT_EOC                        1    OVERLAY(OPT_EOC_I:2)
     D OPT_CANCEL_I                   5I 0 INZ(6)
     D OPT_CANCEL                     1    OVERLAY(OPT_CANCEL_I:2)
     D OPT_LAST_I                     5I 0 INZ(7)
     D OPT_LAST                       1    OVERLAY(OPT_LAST_I:2)
     D OPT_NEXT_I                     5I 0 INZ(8)
     D OPT_NEXT                       1    OVERLAY(OPT_NEXT_I:2)
     D OPT_PREVIEW_I                  5I 0 INZ(9)
     D OPT_PREVIEW                    1    OVERLAY(OPT_PREVIEW_I:2)
     D OPT_COMMIT_I                   5I 0 INZ(10)
     D OPT_COMMIT                     1    OVERLAY(OPT_COMMIT_I:2)
     D OPT_BACKOUT_I                  5I 0 INZ(11)
     D OPT_BACKOUT                    1    OVERLAY(OPT_BACKOUT_I:2)
     D OPT_SYNCPOI_I                  5I 0 INZ(12)
     D OPT_SYNCPOINT                  1    OVERLAY(OPT_SYNCPOI_I:2)
     D OPT_ATTACH_I                   5I 0 INZ(13)
     D OPT_ATTACH                     1    OVERLAY(OPT_ATTACH_I:2)
     D OPT_DELETE_I                   5I 0 INZ(14)
     D OPT_DELETE                     1    OVERLAY(OPT_DELETE_I:2)
     D OPT_EOCCANC_I                  5I 0 INZ(15)
     D OPT_EOCCANCEL                  1    OVERLAY(OPT_EOCCANC_I:2)
     D OPT_QUERY_I                    5I 0 INZ(16)
     D OPT_QUERY                      1    OVERLAY(OPT_QUERY_I:2)
     D OPT_SETUSTAT_I                 5I 0 INZ(17)
     D OPT_SETUSTATUS                 1    OVERLAY(OPT_SETUSTAT_I:2)
     D OPT_ANY_I                      5I 0 INZ(18)
     D OPT_ANY                        1    OVERLAY(OPT_ANY_I:2)
     D OPT_TERMINAT_I                 5I 0 INZ(19)
     D OPT_TERMINATE                  1    OVERLAY(OPT_TERMINAT_I:2)
     D OPT_CHECKSERVIC_I              5I 0 INZ(21)
     D OPT_CHECKSERVICE               1    OVERLAY(OPT_CHECKSERVIC_I:2)
      *
      *--------------- CONVERSATION STATUS CONSTANTS -----------------------
     D CONV            DS
     D CONV_NEW_I                     5I 0 INZ(1)
     D CONV_NEW                       1    OVERLAY(CONV_NONE_I:2)
     D CONV_OLD_I                     5I 0 INZ(2)
     D CONV_OLD                       1    OVERLAY(CONV_NONE_I:2)
     D CONV_NONE_I                    5I 0 INZ(3)
     D CONV_NONE                      1    OVERLAY(CONV_NONE_I:2)
      *
      *--------------- STORE CONSTANTS -------------------------------------
     D STORE           DS
     D STORE_0FF_I                    5I 0 INZ(1)
     D STORE_0FF                      1    OVERLAY(STORE_0FF_I:2)
     D STORE_BROKER_I                 5I 0 INZ(2)
     D STORE_BROKER                   1    OVERLAY(STORE_BROKER_I:2)
      *
      *--------------- STATUS CONSTANTS ------------------------------------
     D STATUS          DS
     D STA_0FF_I                      5I 0 INZ(1)
     D STA_0FF                        1    OVERLAY(STA_0FF_I:2)
     D STA_STORED_I                   5I 0 INZ(2)
     D STA_STORED                     1    OVERLAY(STA_STORED_I:2)
     D STA_DELI_ATT_I                 5I 0 INZ(3)
     D STA_DELI_ATT                   1    OVERLAY(STA_DELI_ATT_I:2)
     D STA_DELIVER_I                  5I 0 INZ(4)
     D STA_DELIVER                    1    OVERLAY(STA_DELIVER_I:2)
     D STA_PROCESS_I                  5I 0 INZ(5)
     D STA_PROCESS                    1    OVERLAY(STA_PROCESS_I:2)
     D STA_DEAD_I                     5I 0 INZ(6)
     D STA_DEAD                       1    OVERLAY(STA_DEAD_I:2)
      *
      *--------------- CONTROL BLOCK DEFINITION ----------------------------
     D ETBCB           DS
     D ETB_TYPE                       1
     D ETB_VERSION                    1
     D ETB_FUNCTION                   1
     D ETB_OPTION                     1
     D ETB_RESERVED                  16    INZ(' ')
     D ETB_SEND_LEN                  10I 0 INZ(0)
     D ETB_RECV_LEN                  10I 0 INZ(0)
     D ETB_RETN_LEN                  10I 0 INZ(0)
     D ETB_ERRT_LEN                  10I 0 INZ(0)
     D ETB_BROKER_ID                 32    INZ(' ')
     D ETB_SERV_CLAS                 32    INZ(' ')
     D ETB_SERV_NAME                 32    INZ(' ')
     D ETB_SERVICE                   32    INZ(' ')
     D ETB_USERID                    32    INZ(' ')
     D ETB_PASSWD                    32    INZ(' ')
     D ETB_TOKEN                     32    INZ(' ')
     D ETB_SEC_TOKEN                 32    INZ(' ')
     D ETB_CONV_ID                   16    INZ(' ')
     D ETB_WAIT_TOUT                  8    INZ(' ')
     D ETB_ERR_CODE                   8    INZ(' ')
     D ETB_ERR_CLASS                  4    OVERLAY(ETB_ERR_CODE:1)
     D ETB_ERR_NBR                    4    OVERLAY(ETB_ERR_CODE:5)
     D ETB_ENVIRON                   32    INZ(' ')
     D ETB_ADCOUNT                   10I 0 INZ(0)
     D ETB_USER_DATA                 16    INZ(' ')
     D ETB_MSG_ID                    32    INZ(' ')
     D ETB_MSG_TYPE                  16    INZ(' ')
     D ETB_PTIME                      8    INZ(' ')
     D ETB_NEW_PWD                   32    INZ(' ')
     D ETB_ADAPT_ERR                  8    INZ(' ')
     D ETB_CLIENT_UID                32    INZ(' ')
     D ETB_CONV_STAT                  1    INZ(' ')
     D ETB_STORE                      1    INZ(' ')
     D ETB_STATUS                     1    INZ(' ')
     D ETB_UOW_STAT                   1    INZ(' ')
     D ETB_UOW_TIME                   8    INZ(' ')
     D ETB_UOW_ID                    16    INZ(' ')
     D ETB_USER_STAT                 32    INZ(' ')
     D ETB_STAT_PERS                  1    INZ(' ')
     D ETB_UOWLATER                   3    INZ(' ')
     D ETB_LOCALE_STR                40    INZ(' ')
     D ETB_DATA_ARCH                  1    INZ(' ')
     D ETB_FORCE_LGON                 1    INZ(' ')
      * following field is deprecated:
     D ETB_ENC_LEVEL                  1    INZ(' ')
      *
     D ETB_KERSEC                     1    INZ(' ')
     D ETB_COMMTIME                  17    INZ(' ')
     D ETB_COMPLVL                    1    INZ(' ')
     D ETB_RESVD3                     2    INZ(' ')
     D ETB_RESVD4                    10I 0 INZ(0)
     D ETB_UWSTATLIFE                 8    INZ(' ')
     D ETB_RESVD_V91_1               96    INZ(' ')
     D ETB_RESVD_V91_2               16    INZ(' ')
     D ETB_RESVD_V99_1               32    INZ(' ')
     D ETB_RESVD_V73_1               10I 0 INZ(0)
     D ETB_RESVD_V73_2               10I 0 INZ(0)
     D ETB_RESVD_V73_3               10I 0 INZ(0)
     D ETB_CLIENT_ID                 10I 0 INZ(0)
     D ETB_RESVD_V73_4               32    INZ(' ')
     D ETB_LOG_COMMAND               1     INZ(' ')
     D ETB_CRED_TYPE                 1     INZ(' ')
     D ETB_RESVD_V73_5               32    INZ(' ')
     D ETB_RESVD5                    2     INZ(' ')
     D ETB_VAR_LIST_OFF              10I 0 INZ(0)
     D ETB_LONG_BID_LEN              10I 0 INZ(0)
     D ETB_NEW_MSG_ID                64    INZ(' ')
     D ETB_COR_ID                    64    INZ(' ')
     D ETB_USE_MSG_ID                1     INZ(' ')
     D ETB_USE_COR_ID                1     INZ(' ')
     D ETB_RESVD6                    2     INZ(' ')
     D ETB_RESVD7                    10I 0 INZ(0)
     D ETB_LONG_PSWD_LEN             10I 0 INZ(0)
     D ETB_LONG_NEW_PSWD_LEN         10I 0 INZ(0)
      *
      *
     D ERROR_TEXT      S             40    INZ(' ')
      *--------------- INDEPENDENT -----------------------------------------
     D I_PARM          DS
     D IN_PARAM_ID                   32
     D I_SWITCH_ID                    2    OVERLAY(IN_PARAM_ID:1)
     D I_BROKER_ID                   30    OVERLAY(IN_PARAM_ID:3)
      *
     D G_SEND_BUFF     S            256    INZ(' ')
      *
     D G_RECV_BUFF     S            256    INZ(' ')
      *
     D BIN_FIELD       DS
     D BIN_ZERO_I                     5I 0 INZ(0)
     D BIN_ZERO                       1    OVERLAY(BIN_ZERO_I:2)
      *
      *
      ****
     D E_CLASS                       10I 0 INZ(0)
     D S_LOOP                        10I 0 INZ(10)
     D E_COUNT                       10I 0 INZ(0)
      ****
     D MSGDATA         DS
     D MSG_FUNC                       6    INZ(' ')
     D MSG_ECLASS                     4    INZ(' ')
     D MSG_ENUM                       4    INZ(' ')
     D MSG_FILL                       1    INZ(' ')
     D MSG_ETEXT                     32    INZ(' ')
      **********************************************************************

ACI Examples and Copybooks

When you begin to write your first Broker ACI program in RPG, you can use these examples as a model for your own implementation:

  • client: BCOCRPG

  • server: BCOSRPG

Depending on your platform for RPG, you will find the files with the examples, copybooks, etc. at the following locations:

Platform Copybooks / Examples Location Notes
IBM i Broker ACI control block copybook. See member RPGDEF in include source file QRPGLESRC. 1
Sample procedure for compiling. See member CRT_RPGMOD in source file QRPGLESRC. 1
Sample procedure for binding. See member EXABNDPGM in source file EXASRC. 1
Client example See member BCOCRPG of type RPGLE in source file EXASRC. 1, 3
Procedure to call client example See the CL member EXABCOC in source file EXASRC. 1, 2
Procedure to call client example with security parameters See the CL member EXABCOCSEC in source file EXASRC. 1, 2
Server example See member BCOSRPG of type RPGLE in source file EXASRC. 1, 3
Procedure to call server example See the CL member EXABCOS in source file EXASRC. 1, 2
Procedure to call server example with Security parameters See the CL member EXABCOSSEC in source file EXASRC. 1, 2

Notes:

  1. See Installing EntireX under IBM i.
  2. By default, these CL procedures call the C type of the client and server programs (BCOC and BCOS). To use the relevant RPG programs BCOCRPG and BCOSRPG, you must modify the procedures accordingly. After adjusting the Broker ID, Broker version and security parameters, you must compile the sources and bind the created modules to executable *PGM programs. For compiling, use the procedure CRT_RPGMOD. For binding, use the procedure EXABNDPGM. All sample programs copy the ACI Broker control block definitions RPGDEF during compilation.
  3. See also Verifying the Installation of the Broker Stubs.

Creating an RPG User Application under IBM i

On the IBM i system, the broker stub is implemented as an object of type *SRVPGM (Service Program). This object type has the advantage that its program code can be shared by several programs. It exists as an object on its own and can therefore be easily replaced without rebinding the user's application, when a newer version becomes available.

The service program EXA supplied by Software AG contains all the functions necessary for controlling and communicating with the remote broker. To create an executable Broker application on IBM i, you need to develop, in any ILE-enabled programming language, at least one main module to which the EXA service program is bound.

  • For compilation use the IBM i command CRTRPGMOD

  • For binding use IBM i command CRTPGM with the option:

    ...BNDSRVPGM(*LIBL/EXA)...

Example:

The following steps show how to create a server application using the program BCOSRPG. See ACI Examples and Copybooks.

Step 1: Set the Environment

The library EXX must be located in the *LIBL list.

To set the library list, you can use the IBM i command:

CHGCURLIB CURLIB(EXX)

Step 2: Compile the User Program

To compile BCOSRPG, use the command CRTRPGMOD with the following options:

MODULE(BCOSRPG) SRCFILE(*CURLIB/EXASRC) OUTPUT(*PRINT)

Or, use the sample procedure CRT_RPGMOD.

If the program has been successfully compiled, the module BCOSRPG will be created.

Step 3: Bind EXA to the User Program

To produce an executable program, bind the user program BCOSRPG to the service program EXA supplied by Software AG.

CRTPGM PGM(EXX/BCOSRPG) MODULE(*PGM) ENTMOD(*PGM)
BNDSRVPGM(EXX/EXA) BNDDIR(*NONE) OPTION(*GEN *WARN *DUPVAR)
DETAIL(*EXTENDED)

Or, use the sample program EXABNDPGM.

Related Literature

Writing Applications

Reference