The ENTRY Statement
General Formats for Format 1
General Formats for Format 2
Directives
- In addition to Compiler directives which provide flagging and modify the reserved word list, the STICKY-LINKAGE directive controls whether addressability to Linkage Section items is maintained between calls to different entry points in the same program.
Syntax Rules for All Formats
- The ENTRY statement cannot be used in a program that is nested within another program.
- Literal-1 must be non-numeric and must not be a figurative constant. In some environments, only the first 8 characters are significant.
- Mnemonic-name is necessary only if the object program that is to be invoked expects a calling convention other than that used
as the default by your COBOL system. Typically, the default COBOL calling convention is consistent with that used by a significant
implementation of a non-COBOL language for the run-time environment.
Mnemonic-name must be defined in the Special-Names paragraph. See the topic The Special-Names Paragraph for details of how to do this and your COBOL system documentation on interfacing for details of which calling conventions are supported in your run-time environment.
- When compiling to JVM COBOL, an ENTRY statement is not allowed within a nested block of statements -for example, in an unterminated IF statement.
Syntax Rules for Format 1
- Format 1 must be specified only within program definitions.
- Data-name-1 must be defined as a level 01 or a level 77 entry in the Linkage Section
, File Section or Working-Storage Section.
- Data-name-2 must be defined as a level 01 or a level 77 entry in the Linkage Section, File Section or Working-Storage Section.
For JVM and .NET COBOL, data-name-2 can be any class and must be no greater than 8 bytes. For native COBOL, data-name-2 can
be of any class except comp-1 and comp-2. The length must be no greater than 4 bytes for 32-bit compilation, and no greater
than 8 bytes for 64-bit compilation.
Syntax Rules for Format 2
- Format 2 can only be used in a program in which the EXTERNAL clause is specified in the Program-ID paragraph, that is a call
prototype.
- Data-name-1 and data-name-2 must be defined as 01 level records in the Linkage Section.
- Typedef-name-1, typedef-name-2, and typedef-name-3 must be previously defined in the same source file as a programmer-defined
usage by means of a TYPEDEF clause.
General Rules for All Formats
- The content of literal-1 gives the entry-name, a name which identifies an entry point into the program that is an alternative
to the default COBOL entry point at the start of the Procedure Division that is identified by the program-name given in the
Program-ID paragraph.
Note that program files containing executable COBOL code typically have names that are essentially the same as the program-name. When a CALL is made and the program-name or entry-name is not already loaded into memory, program files are located by filename but can appear to be located by program-name. In such circumstances, a CALL that references a program-name may succeed but a CALL that references an entry-name may fail.
The entry-name is largely equivalent to a program-name and the two are subject to common rules for formation of the name as indicated in the topic The Program-ID Paragraph. Literal-1 corresponds to literal-1 of the general format for the Program-ID paragraph.
- When the calling program invokes the called program by a CALL statement naming the entry-name given by literal-1, control is transferred to the next executable statement following the ENTRY statement.
- Data items that are declared in the Linkage Section but are not declared in the USING phrase of the ENTRY statement can only be referenced if they have been linked to a data item by executing a SET statement or if the STICKY-LINKAGE Compiler directive is used.
- Up to sixty-two data-names are permitted in the USING phrase.
- Both the BY REFERENCE and the BY VALUE phrases are transitive across the parameters that follow them until another BY REFERENCE or BY VALUE phrase is encountered. If neither the BY REFERENCE nor the BY VALUE phrase is specified prior to the first parameter, the BY REFERENCE phrase is assumed.
General Rules for Format 1
- If data-name-1 is defined as a level 01 or a level 77 entry in the File Section or Working-Storage Section then the object
program operates as if a data item had been declared in the Linkage Section with the same data declaration as data-name-1
and the contents of that data item were moved to data-name-1 prior to executing the first statement in the called program.
In an initial program, these values are overwritten by the initialization of the program's Working-Storage data and are therefore
not available to the called program.
- If the activating runtime element is COBOL the following rules apply. If the activating runtime element is not COBOL, see your COBOL system documentation on interfacing for details of when you need to use the BY REFERENCE or BY VALUE clauses.
- The USING phrase identifies the names of the formal parameters used by the program or for any arguments passed to it. The arguments passed to it are identified in the activating source element by the USING phrase of a CALL statement. The correspondence between the two lists of names is established on a positional basis.
- If the argument is passed by content, the called program operates as if the record in the Linkage Section were allocated by the calling runtime element during the process of initiating the call and as if this record does not occupy the same storage area as the argument in the calling runtime element. This allocated record is exactly the same number of alphanumeric character positions in length as the argument. That argument is moved to this allocated record without conversion. This record is then treated by the called program as if it were the argument and as if it were passed by reference.
- If the argument is passed by reference, the called program operates as if the formal parameter occupies the same storage area as the argument.
- If the argument is passed by value, the called program operates as if the record in the Linkage Section were allocated by
the calling runtime element during the process of initiating the call and as if this record does not occupy the same storage
area as the argument in the calling runtime element. This allocated record is exactly the same number of alphanumeric character
positions in length as the argument. That argument is moved to this allocated record without conversion. This record is then
treated by the called program as if it were the argument and as if it were passed by reference.
- At all times in the activated element, references to data-name-1
, data-name-2 and data-name-3
are resolved in accordance with their description in the Linkage Section. If this description defines a greater number of character positions than the corresponding data item in the activating element, unpredictable results can occur. Failure to comply with this rule or exceeding the maximum allowed size of the system area for a particular run time environment may result in the system becoming catastrophically corrupt.
- When a program is called and a BY REFERENCE operand in the USING phrase corresponds to a parameter in the calling program,
a referential connection is established and endures until control is returned to the calling program. If the program is called
a second time, without any intervening cancel of the program, and that same BY REFERENCE operand does not correspond to a
parameter in the calling program, then you must not reference that operand unless the STICKY-LINKAGE Compiler directive is
specified.
General Rules for Format 2
- When the BY REFERENCE phrase passes data-name-1 using the DELIMITED keyword, it is a copy of the original parameter, with any trailing spaces replaced with a null terminator, that is passed. No changes to this parameter are passed back to the calling program.