.csect pseudo-op

Purpose

Groups code or data into a csect (control section) and gives that csect a name, a storage-mapping class, and an alignment.

Syntax

where QualName = [Name][[StorageMappingClass]]

Note: The boldfaced brackets containing StorageMappingClass are part of the syntax and do not specify an optional parameter.

Description

The following information discusses using the .csect pseudo-op:

• A csect QualName parameter takes the form:

  
  symbol[XX]
  

  OR

  symbol{XX}

  where either the [ ] (square brackets) or { } (curly brackets) surround a two- or three-character storage-mapping class identifier. Both types of brackets produce the same results.

  The QualName parameter can be omitted. If it is omitted, the csect is unnamed and the [PR] StorageMappingClass is used. If a QualName is used, the Name parameter is optional and the StorageMappingClass is required. If no Name is specified, the csect is unnamed.

  Each csect pseudo-op has an associated storage-mapping class. The storage-mapping class determines the object section in which the csect pseudo-op is grouped. The .text section usually contains read-only data, such as instructions or constants. The .data, .bss, .tdata, and .tbss sections contain read/write data. The storage-mapping classes for .bss. and .tbss must be used with the .comm, and .lcomm pseudo-ops, not the .csect pseudo-op.

  The storage-mapping class also indicates what kind of data should be contained within the csect. Many of the storage-mapping classes listed have specific implementation and convention details. In general, instructions can be contained within csects of storage-mapping class PR. Modifiable data can be contained within csects of storage-mapping class RW.

  A csect pseudo-op is associated with one of the following storage-mapping classes. Storage-mapping class identifiers are not case-sensitive. The storage-mapping class identifiers are listed in groups for the .data, .tbss, .tdata, .text, and .tss object file sections.

  .text Section Storage-Mapping Classes
  PR	Program Code. Identifies the sections that provide executable instructions for the module.
  RO	Read-Only Data. Identifies the sections that contain constants that are not modified during execution.
  DB	Debug Table. Identifies a class of sections that have the same characteristics as read-only data.
  GL	Glue Code. Identifies a section that has the same characteristics as Program Code. This type of section has code to interface with a routine in another module. Part of the interface code requirement is to maintain TOC addressability across the call.
  XO	Extended Operation. Identifies a section of code that has no dependency on the TOC (no references through the TOC). It is intended to reside at a fixed address in memory so that it can be the target of a branch to an absolute address. Note: This storage-mapping class should not be used in assembler source programs.
  SV	Supervisor Call. Identifies a section of code that is to be treated as a supervisor call.
  TB	Traceback Table. Identifies a section that contains data associated with a traceback table.
  TI	Traceback Index. Identifies a section that contains data associated with a traceback index.

  .data Section Storage-Mapping Classes
  TC0	TOC Anchor used only by the predefined TOC symbol. Identifies the special symbol TOC. Used only for the TOC anchor.
  TC	TOC Entry. Generally indicates a csect that contains addresses of other csects or global symbols. If it contains only one address, the csect is usually four bytes long. TD TOC Entry. Identifies a csect that contains scalar data that can be directly accessed from the TOC. For frequently used global symbols, this is an alternative to indirect access through an address pointer csect within the TOC. By convention, TD sections should not be longer than four bytes. Contains initialized data that can be modified during program execution.
  UA	Unknown Type. Identifies a section that contains data of an unknown storage-mapping class.
  RW	Read/Write Data. Identifies a section that contains data that is known to require change during execution.
  DS	Descriptor. Identifies a function descriptor. This information is used to describe function pointers in languages such as C and FORTRAN.

  .bss Section Storage-Mapping Classes
  BS	BSS class. Identifies a section that contains uninitialized read/write data.
  UC	Unnamed FORTRAN Common. Identifies a section that contains read/write data. A csect is one of the following symbol types:
  ER	External Reference
  SD	CSECT Section Definition
  LD	Entry Point - Label Definition
  CM	Common (BSS)

  .tdata Section Storage-Mapping Classes
  TL	Initialized thread-local storage. Identifies a csect that is instantiated at run time for each thread in the program.

  .tbss Section Storage-Mapping Classes
  UL	Uninitialized thread-local storage. Identifies a csect that is instantiated at run time for each thread in the program.

• All of the csects with the same QualName value are grouped together, and a section can be continued with a .csect statement having the same QualName. Different csects can have the same name and different storage-mapping classes. Therefore, the storage-mapping class identifier must be used when referring to a csect name as an operand of other pseudo-ops or instructions.

  However, for a given name, only one csect can be externalized. If two or more csects with the same name are externalized, a run error may occur, since the linkage editor treats the csects as duplicate symbol definitions and selects only one of them to use.

• A csect is relocated as a body.
• csects with no specified name (Name) are identified with their storage-mapping class, and there can be an unnamed csect of each storage-mapping class. They are specified with a QualName that only has a storage-mapping class (for instance, .csect [RW] has a QualName of [RW]).
• If no .csect pseudo-op is specified before any instructions appear, then an unnamed Program Code ([PR]) csect is assumed.
• A csect with the BS or UC storage-mapping class will have a csect type of CM (Common), which reserves spaces but has no initialized data. All other csects defined with the .csect pseudo-op are of type SD (Section Definition). The .comm or .lcomm pseudo-ops can also be used to define csects of type CM. No external label can be defined in a csect of type CM.
• Do not label .csect statements. The .csect may be referred to by its QualName, and labels may be placed on individual elements of the .csect.

Parameters

Examples

The following example defines three csects:

# A csect of name proga with Program Code Storage-Mapping Class.
.csect proga[PR]
lh      30,0x64(5)
# A csect of name pdata_ with Read-Only Storage-Mapping Class.
.csect pdata_[RO]

l1:    .long  0x7782
l2:    .byte  'a,'b,'c,'d,'e
.csect  [RW],3          # An unnamed csect with Read/Write

                        # Storage-Mapping Class and doubleword
                        # alignment.

.float -5