Special registers

Special registers are reserved words that name storage areas generated by the compiler. Their primary use is to store information produced through specific COBOL features. Each such storage area has a fixed name, and must not be defined within the program.

For programs with the RECURSIVE attribute, for programs compiled with the THREAD option, and for methods, storage for the following special registers is allocated on a per-invocation basis:

  • ADDRESS OF
  • JSON-CODE
  • Start of changeJSON-STATUSEnd of change
  • RETURN-CODE
  • SORT-CONTROL
  • SORT-CORE-SIZE
  • SORT-FILE-SIZE
  • SORT-MESSAGE
  • SORT-MODE-SIZE
  • SORT-RETURN
  • TALLY
  • XML-CODE
  • XML-EVENT
  • XML-INFORMATION
  • XML-NAMESPACE
  • XML-NAMESPACE-PREFIX
  • XML-NNAMESPACE
  • XML-NNAMESPACE-PREFIX
  • XML-NTEXT
  • XML-TEXT

For the first call to a program after a cancel of that program, or for a method invocation, the compiler initializes the special register fields to their initial values.

For the following four cases:

  • Programs that have the INITIAL clause specified
  • Programs that have the RECURSIVE clause specified
  • Programs compiled with the THREAD option
  • Methods

the following special registers are reset to their initial value on each program or method entry:

  • JSON-CODE
  • Start of changeJSON-STATUSEnd of change
  • RETURN-CODE
  • SORT-CONTROL
  • SORT-CORE-SIZE
  • SORT-FILE-SIZE
  • SORT-MESSAGE
  • SORT-MODE-SIZE
  • SORT-RETURN
  • TALLY
  • XML-CODE
  • XML-EVENT

Further, in the above four cases, values set in ADDRESS OF special registers persist only for the span of the particular program or method invocation.

In all other cases, the special registers will not be reset; they will be unchanged from the value contained on the previous CALL or INVOKE.

Unless otherwise explicitly restricted, a special register can be used wherever a data-name or identifier that has the same definition as the implicit definition of the special register can be used. Implicit definitions, if applicable, are given in the specification of each special register.

You can specify an alphanumeric special register in a function wherever an alphanumeric argument to a function is allowed, unless specifically prohibited.

If qualification is allowed, special registers can be qualified as necessary to provide uniqueness. (For more information, see Qualification.)