TypeCobolFunctionsSyntax

**NOTE: this page is a work in progress. The content can still change entirely at any time **

Detailled rules of procedures and functions syntax

Table of Contents

• How to call a function or procedure
• How to declare a function or procedure
• Code generation

#How to call a function or procedure

Procedure

CALL procedure-name INPUT      inputParam1, ... inputParamN
                    INOUT      inoutParam1, ... inoutParamN
                    OUTPUT     outParam1,   ... outParamN
end-call
if procedure-name::error-code = '0000'
   ... return OK
else 
   ... return KO, handle error
end-if

Functions

FUNCTION function-name (param1, param2, param3, ... paramN)

This syntax is the same as the syntax for COBOL intrinsic functions and can be used in the same contexts. In particular:

• TCRFUN_TCFUNC_WHERE_COBOL85FUNC_ a custom function can be called as part of any statement where an COBOL 85 intrinsic function call would be acceptable. TODO: see if we can allow intrinsic functions in more contexts than COBOL 85.
• TCRFUN_OPTIONAL_FUNCTION the FUNCTION keyword is optional However, if there is any ambiguity about function-name, the function call must be qualified as described in Namespaces & imports.

Alternate call for function

TCRFUN_FUNC_ALLOW_CALL Functions can also be called like a procedure. This syntax make it easier to test the error-code.

CALL function-name INPUT      inputParam1, ... inputParamN
                   RETURNING  returningParameter 
end-call
if function-name::error-code = '0000'
   ... return OK
else 
   ... return KO, handle error
end-if

##Common rules for functions and procedures calls

• TCRFUN_FUNC_COMMA_SEPARATOR You need to separate parameters with a comma (,).

• TCRFUN_INPUT_ALL_BY input parameters can be passed 'BY VALUE', 'BY CONTENT' or 'BY REFERENCE'

• TCRFUN_INOUT_OUT_ONLY_BY_REFERENCE inout and output parameters can only be passed by reference.

• Neither BY REFERENCE, nor BY VALUE, nor BY CONTENT can be specified: BY REFERENCE is implied in all cases.

• TCRFUN_PARAMETER_MATCHING The caller must provide the exact number of parameters and each parameter must match the type of function/procedure prototype. Rules for type matching are:

• The type must be equal (Literal, Number, ...)

• The logical size (without any concern about comp-*) must identical

• For input and inout parameters, the physical compression must be equals too (same comp-* between caller and callee)

#How to declare a function or procedure

##Procedure declaration

DECLARE PROCEDURE procedure-name PRIVATE|PUBLIC
  INPUT       <parameter descriptions>
  INOUT       <parameter descriptions>
  OUTPUT      <parameter descriptions>
  ERROR-CODE  <error-code values description>.

DATA DIVISION.
    WORKING-STORAGE SECTION.
        <data declaration(s)>
PROCEDURE DIVISION.
        <COBOL and/or TypeCobol statement(s)>
END-DECLARE.

##Function declaration

DECLARE FUNCTION function-name PRIVATE|PUBLIC
  INPUT       <parameter descriptions>
  RETURNING   <parameter-name>
  ERROR-CODE  <error-code values description>.

DATA DIVISION.
    WORKING-STORAGE SECTION.
        <data declaration(s)>
PROCEDURE DIVISION.
        <COBOL and/or TypeCobol statement(s)>
END-DECLARE.

Common rules for procedure and function declaration

The declaration of a procedure or a function in TypeCobol follows the same rules as the declaration of a nested program in COBOL 85, with the following differences:

• TCRFUN_FIXED_FORMAT In fixed column format, all keywords related to function or procedure, can start at any column between columns 8 and 72 included.

• TCRFUN_NO_DEFAULT_ACCESS_MODIFIER There must be exactly one of the PRIVATE or PUBLIC phrases. There is no « default » access modifier.

  • The PUBLIC phrases gives a public visibility to the procedure or function.
    • TCRFUN_NO_SECTION_OR_PARAGRAPH_IN_LIBRARY If you declare a PUBLIC procedure or function, then you cannot write any section or paragraph inside the same PROCEDURE DIVISION. Instead, all the code inside this PROCEDURE DIVISION must be put inside procedures or functions declaration. This ensures the only way to use your code is through a PUBLIC procedure or function. TODO Explain why/document it, make a link to the page that explains why
  • The PRIVATE phrases gives a private visibility to the procedure or function. Only the enclosing program or others procedures and functions inside the same program can call it.

• TCRFUN_DOTS A . is mandatory only after the parameters and return-code declaration. Character . can still be put after each parameter description. TODO: need to check if we need . everywhere because of COBOL 85 grammar

• TCRFUN_NO_DOT_AFTER_VISIBILITY There is no dot after function or procedure visibility.

• TCRFUN_NO_CALL_TO_ENCLOSING_PROGRAM A function or procedure cannot call a paragraph or section of the enclosing program.

Parameters description (input, inout, output and returning):

TCRFUN_PARAMETER_DECLARATION_ORDER Parameters are always declared in this order: input, inout, output, returning.

TCRFUN_PARAMETER_DESCRIPTION A parameter description must contains the following:

• a parameter name (ex: dateToConvert)

• either one PICTURE clause or one TYPE clause

• Restrictions:

  • No level descriptor, except for level 88. Level 01 is implied in all cases when 88 is not present.
  • No REDEFINES
  • No RENAMES
  • Neither FILLER nor unnamed variables
  • Neither GLOBAL nor EXTERNAL
  • Neither BY REFERENCE, nor BY VALUE, nor BY CONTENT can be specified: BY REFERENCE is implied in all cases.

• TCRFUN_0_TO_N_PARAMETERS Lists of INPUT, INOUT and OUTPUT parameters can contains 0 to N parameters.

  • The list of input parameters can be empty. In this case, the function/procedure takes no input parameters and the INPUT keyword can be omitted.
  • The list of inout parameters can be empty. In this case, the procedure takes no inout parameters and INOUT keyword can be omitted.
  • The list of output parameters can be empty. In this case, the procedure takes no output parameters and OUTPUT keyword can be omitted.

• TCRFUN_NO_INOUT_OR_INPUT_FOR_FUNCTIONS A function cannot have inout or output parameters.

• TCRFUN_NO_RETURNING_FOR_PROCEDURES A procedure cannot have a returning parameter.

• TCRFUN_0_TO_1_RETURNING_PARAMETER A function has exactly one returning parameter. The declaration of returning parameter is mandatory, but it can be omitted (RETURNING OMITTED).

• TCRFUN_NO_COPY_IN_PARAMETERS The COPY keyword is forbidden inside parameters declaration.

Level 88 parameter description

TCRFUN_LEVEL_88_PARAMETERS Level 88 parameters are declared like a standard COBOL 85 parameters: **TODO: see if we can provide enum grammar, instead of levels 88 **

DECLARE FUNCTION function-name PRIVATE
  input     typeOfTransportpic X
              88 typeOfTransport-Car  value 'C'
              88 typeOfTransport-Bike value 'B'.

Error-code values

• TCRFUN_ERROR_CODE_DECLARATION_ORDER error-code values are always declared after input, inout, output and returning parameters.
• TCRFUN_ERROR_CODE_OPTIONAL Error-code declaration is optional for procedure and function.

TODO: clarify how return codes works.

Other Rules:

__TCRFUN_DECLARATION_AS_NESTED_PROGRAM__ A procedure or a function is declared like a nested program. The declaration is inside the procedure division and outside of any section or paragraph.

Compared to a nested program declaration, a procedure or function declaration has the following exceptions:

• TCRFUN_DECLARATION_NO_IDENTIFICATION_DIVISION There is no IDENTIFICATION DIVISION
• TCRFUN_DECLARATION_NO_ENVIRONMENT_DIVISION There is no ENVIRONMENT DIVISION
• Inside the DATA DIVISION:
  • TCRFUN_DECLARATION_NO_FILE_SECTION There is no FILE SECTION
  • Restricted data declaration inside WORKING-STORAGE, LOCAL-STORAGE and LINKAGE
    • TCRFUN_DECLARATION_NO_GLOBAL GLOBAL are not allowed
    • TCRFUN_DECLARATION_NO_EXTERNAL EXTERNAL are not allowed
    • TCRFUN_DECLARATION_NO_DUPLICATE_NAME No LINKAGE SECTION item can have the same name as a parameter declared as INPUT, OUTPUT, INOUT or RETURNING.
• PROCEDURE DIVISION is equivalent to COBOL 85 program, with the following exceptions:
  • TCRFUN_DECLARATION_NO_USING The USING phrase is not allowed.
  • TCRFUN_DECLARATION_NO_DECLARATIVES DECLARATIVES are not allowed.
• TCRFUN_MANDATORY_END_DECLARE The END-DECLARE. phrase is mandatory.

##Where to put this declaration? It depends on the procedure visibility: private or public

Private procedure

Private procedure declaration must be put outside paragraph and section declaration.

IDENTIFICATION DIVISION.
PROGRAM-ID. TypeCobol.
data division.
working-storage section.
01 a pic 9(04).
01 b pic 9(04).
01 c pic 9(04).
PROCEDURE DIVISION.
   move 1 to a
   move 2 to b
   perform MyParagraph
.
MyParagraph.
   CALL MyProcedure input(a, b)
                    output(c)
.
declare procedure MyProcedure private
  input  param1 pic 9(04)
         param2 pic 9(04)
  output outParam1 pic 9(04).
procedure division.
   compute outParam1 = param1 + param2 
   .
end-declare.
.
 END PROGRAM.

Public procedure

If you want to declare at least one public procedure, then you can't write section or paragraph inside procedure division. All code inside procedure division must be put inside functions or procedures declaration. The only way to call your program is through a public function or procedure.

Technically all functions and procedure will be generated into a sub-programs and your procedure division will contains code to call theses sub-programs.

IDENTIFICATION DIVISION.
PROGRAM-ID. TypeCobol.
PROCEDURE DIVISION.
declare procedure MyProcedure private
 input  param1    pic 9(04)
 output outParam1 pic 9(04).
procedure division.
   ...
   .
end-declare.
declare function MyPublic public
 input     param1 9(04)
 returning result type bool.
 procedure division.
   ...
   .
end-declare.
.
END PROGRAM.

#Code generation Each TypeCobol function or procedure translate in COBOL 85 into a program. This program is nested in the same `PROCEDURE DIVISION` as the original function or procedure.

Example

DECLARE FUNCTION MyProcedure PRIVATE
  INPUT  param1    PIC 9(04)
  OUTPUT outParam1 PIC 9(04).
  PROCEDURE DIVISION.
   ...
   .
END-DECLARE.
DECLARE FUNCTION MyPublic PUBLIC
  INPUT param1 PIC 9(04)
  RETURNING result TYPE bool.
  PROCEDURE DIVISION.
   ...
   .
end-declare.

is translated into this COBOL 85 code:

PROGRAM-ID. MyProcedure.
  DATA DIVISION.
  LINKAGE SECTION.
    01 param1    PIC 9(04).
    01 outParam1 PIC 9(04).
  PROCEDURE DIVISION
    USING BY REFERENCE param1 outParam1
  .
   ...
END PROGRAM.
PROGRAM-ID. function-name.
  DATA DIVISION.
  LINKAGE SECTION.
    01 param1 PIC 9(04).
    01 result-value PIC X VALUE LOW-VALUE.
      88 result       VALUE 'T'.
      88 result-false VALUE 'F'.
  PROCEDURE DIVISION
    USING param1
    RETURNING BY REFERENCE result-value
  .
    ...
END PROGRAM.

• TCRFUN_CODEGEN_AS_NESTED_PROGRAM The procedure or function declaration header becomes a program identification header with neither INITIAL, RECURSIVE or COMMON phrase, nor authoring properties. The information regarding the procedure or function access modifier is not translatable and is therefore lost.
• TCRFUN_CODEGEN_NO_ADDITIONAL_DATA_SECTION Each section of the DATA DIVISION will only be present in the generated code if it was present in the original code.
• TCRFUN_CODEGEN_PARAMETERS_IN_LINKAGE_SECTION Each INPUT, OUTPUT, INOUT or RETURNING parameter is generated as an entry of the LINKAGE SECTION of the generated nested program, if a data description entry with the same name is not already present.
• TCRFUN_CODEGEN_DATA_SECTION_AS_IS Each entry in a section of the DATA DIVISION already present in the TypeCobol source code is translated with no additional consideration than what is described in TypeCobol Types codegen.
• TCRFUN_CODEGEN_PARAMETERS_ORDER All input, inoutand output parameters are translated using the USING phrase, in the following order: USING input-parameter* inout-parameters* output-parameter* return-code
• TCRFUN_CODEGEN_RETURNING_PARAMETER The returning parameter is translated using the RETURNING phrase.