19.1.4 Example - Define a Built-In Function as a 3GL Program

This section goes through the steps involved in creating a Built-In Function as a program. The example shown is very simple, but should give an insight to how a Built-In Function is plugged into a LANSA system.

SCENARIO: This is a User Defined Built-In Function. The Built-In Function is used to retrieve system values.

A simple CL program. The program will be passed the system value name and will return the system value.

The name will be UD_GET_SYSTEM_VALUE.

The next available identifier at this site is 411.

BIF Definition  (as per DC@F47 file)

BIF Name:

UD_GET_SYSTEM_VALUE

Unique Identifier:

411

Description:

Retrieve a system value

Call or Execute:

C     (C or E)

Program Name:

UD@P411

Terminates between calls:

N     (Y or N)

Number of arguments:

1

Number of return values:

1

 

 

BIF Arguments  (as per DC@F48 file)

BIF Name:

UD_GET_SYSTEM_VALUE

Parameter Type

ARG

Parameter Sequence:

1

Parameter Number:

1

Parameter Identifier:

A

Description:

Name of system value

Required / Optional:

R    (R or O)

Parameter Type:

A    (A, N or L)

Minimum Length:

1

Maximum Length:

10

Minimum Decimal:

 

Maximum Decimal:

 

Pass Length:

10

Pass Decimal:

 

Default:

 

 

 

BIF Return Values  (as per DC@F48 file)

BIF Name:

UD_GET_SYSTEM_VALUE

Parameter Type

RET

Parameter Sequence:

1

Parameter Number:

2

Parameter Identifier:

B

Description:

Value of system value

Required / Optional:

R     (R or O)

Parameter Type:

A     (A, N or L)

Minimum Length:

1

Maximum Length:

256

Minimum Decimal:

 

Maximum Decimal:

 

Pass Length:

256

Pass Decimal:

 

 

 

Enter the data into the Built-In Function definition files:


/* Program      : UD@P411                                          */
/* -------                                                         */
/* Builtin name : Get a system value                               */
/* ------------                                                    */
/* Date written : 03/10/91                                         */
/* ------------                                                    */
/* Author       : Johnny Programmer                                */
/* ------                                                          */
/* Description  : A program to return a system value               */
/* -----------                                                     */
/*                                                                 */
/*=================================================================*/
/* Parameter list specifications                                   */
/*=================================================================*/
/*                                                                 */
/*  Entry parameter list                                           */
/*  --------------------                                           */
/*                                                                 */
/*  Fixed parameters (all built-in functions)                      */
/*  -----------------------------------------                      */
/*                                                                 */
/*      DC@IDS : Standard Information data structure               */
/*      DC@EDS : Standard exchange data structure                  */
/*      PR@IDS : Standard process information data structure       */
/*                                                                 */
/*  Variable arguments and return values as per DC@F48 definition  */
/*  -------------------------------------------------------------  */
/*                                                                 */
/*      B$411A : Built-in function argument descriptor number A.   */
/*      B@411A : System value to get                               */
/*      B$411B : Built-in function return value descriptor no.     */
/*      B@411B : Value of system value                             */
/*=================================================================*/
 UD@P411: PGM PARM(&DC@IDS &DC@EDS &PR@IDS &B$411A &B@411A &B$411B +
                   &B@411B)
/*=================================================================*/
/*  Variable declarations                                          */
/*=================================================================*/
      DCL &DC@IDS *CHAR  1024
      DCL &DC@EDS *CHAR  1024
      DCL &PR@IDS *CHAR  1024

      DCL &B$411A *CHAR     4
      DCL &B@411A *CHAR    10
      DCL &B$411B *CHAR     4
      DCL &B@411B *CHAR   256

      DCL &$PGMNM *CHAR    10
      DCL &PR@PGM *CHAR    10
      DCL &PR@B@N *CHAR     3
      DCL &PR@B@A *CHAR     1
      DCL &DC@RET *CHAR     1
      DCL &DC@MID *CHAR     7
      DCL &DC@MVR *CHAR   132
/*=================================================================*/
/*  Global error handler                                           */
/*=================================================================*/

       MONMSG MSGID(CPF0000 MCH0000) EXEC(GOTO ARGERR)

/*=================================================================*/
/*  Program mainline                                               */
/*=================================================================*/

/* Set up some fields and map some from the data structures ....   */

            CHGVAR     &$PGMNM   'UD@P411'
            CHGVAR     &PR@PGM   %SST(&PR@IDS 424 10)
            CHGVAR     &PR@B@N   %SST(&PR@IDS 157  3)
            CHGVAR     &PR@B@A   %SST(&PR@IDS 160  1)

/* Initially assume that a "good" return will be the result ....   */

            CHGVAR     &DC@RET 'Y'

/* Perform the required evaluation / action .......                */

/* Retrieve the system value                                       */

       RTVSYSVAL SYSVAL(&B@411A) RTNVAR(&B@411B)
        MONMSG  (CPF0000 MCH0000)
  /* End of program processing logic                               */

ENDPGM:      CHGVAR %SST(&DC@EDS 38   1) &DC@RET
             CHGVAR %SST(&DC@EDS 39   7) &DC@MID
             CHGVAR %SST(&DC@EDS 46 132) &DC@MVR
             RETURN

/*==================================================================*/
/* ARGERR :Handle a detected error in argument(s) passed to program */
/*        Caller should set DC@MID and DC@MVR to reflect the        */
/*        cause of the error before executing this logic. Note that */
/*        the entire program terminates when this logic is invoked. */
/*        It will cause the calling RDML program to fail and issue  */
/*        the message details returned to it in DC@MID/DC@MVR       */
/*==================================================================*/
ARGERR:

/* Route messages any additional messages back to the caller .....  */

             CALL       PGM(DC@P9007) PARM(&$PGMNM &PR@PGM)
             MONMSG     (CPF0000 MCH0000)

/* Set up a "bad" return code ....                                  */

             CHGVAR &DC@RET 'N'
             MONMSG     (CPF0000 MCH0000)

/* Return control to the calling program ....                       */

             GOTO ENDPGM

/*==================================================================*/
             ENDPGM
/*==================================================================*/