LITERAL-ENDLITERAL

Define a literal

WSupported on Windows

USupported on Unix

VSupported on OpenVMS

NSupported in Synergy .NET

[form] LITERAL [name][,X]
  member_def
  .
  .
  .
[ENDLITERAL]

Arguments

form

(optional) Defines the literal as one of the following forms:

[INTERNAL] GLOBAL

Causes the statement to allocate data space in a shared data area. If INTERNAL is specified (Synergy .NET only), access is limited to the current assembly.

EXTERNAL

Causes the statement to reference data space that was previously allocated by a GLOBAL LITERAL statement.

LOCAL

Causes the statement to allocate space in local literal space. (default)

name

(optional) The name of the literal to define.

,X

(optional) Indicates that you’re defining an overlay for the most recently defined nonoverlay literal.

member_def

Either the definition of a field or a group declaration. Each field definition has the syntax that’s described in Defining a field. Each group declaration has the syntax described in GROUP-ENDGROUP. You can specify as many member definitions as you want.

Discussion

The LITERAL statement defines a local read-only data structure that cannot be modified during program execution. The ENDLITERAL statement indicates the end of a literal declaration.

A literal can be declared within a routine. A literal can either be GLOBAL, which allocates the data space, or EXTERNAL, which references it. Fields in an EXTERNAL LITERAL reference the data in the GLOBAL LITERAL by matching the field name. If you don’t specify GLOBAL or EXTERNAL, the literals are placed into local literal space.

If you specify name, the literal is accessed as data type alpha. If you don’t specify name, the literal is unnamed. Each literal name must be unique within the routine in which it is declared.

In an unnamed literal, data space associated with a given field is not created until it is first referenced. If a literal is named, all of the literal’s contents are created unconditionally. If you define a group within an unnamed literal, the group’s contents are created unconditionally regardless of whether they are referenced.

If the size of an integer global literal is not specified, Synergy DBL defaults the size to i4. For example, in the following definition, lit is created as an i4 literal:

global literal
    lit         ,i,             2

You cannot specify automatic size (*) for an external literal.

You can only specify a field position indicator for a literal field if the literal record is named or the field exists in a GROUP-ENDGROUP block. For example, the following is invalid:

literal                         ;Invalid literal declaration
    lit1        ,i4
    lit2        ,i4  @lit1

A literal record can overlay another literal record if the record being overlaid is named.

You cannot specify a packed data field within the scope of a literal field.

Examples

The example below defines a literal named headers.

literal headers
    title       ,2a16,          "Monthly Income", "Monthly Expenses"
    comp        ,a*,            "XYZ Corporation"
    pg          ,a*,            "Page "
endliteral

The example below defines a literal named lits that’s available globally across the current assembly.

internal global literal lits
    lit1        ,a5,            "hello"
endliteral