C.3.1 Preparing an SCA Library

SCA stores data generated by the HP C compiler in an SCA library. The data in an SCA library contains information about all symbols, modules, and files encountered during a specific compilation of the source. You must prepare this library before you enter LSE to invoke SCA. This preparation involves the following steps:

1. Create an OpenVMS directory for your SCA library. For example:

   $ CREATE/DIRECTORY PROJ:[USER.LIB1]

2. Initialize and set the library with the SCA CREATE LIBRARY command. For example:

   $ SCA CREATE LIBRARY [.LIB1]

   
   If you have an existing SCA library that has been initialized, you make its contents visible to SCA by setting it with the SCA SET LIBRARY command. For example:

   $ SCA SET LIBRARY [.EXISTING_SCA_LIBARAY]

   
   A message appears in the message buffer, at the bottom of your screen, indicating whether your SCA library selection succeeded.

3. Direct the HP C compiler to generate data analysis files by appending the /ANALYSIS_DATA qualifier to the CC command. For example:

   $ CC/ANALYSIS_DATA PG1,PG2,PG3

   
   This command line compiles the input files PG1.C, PG2.C, and PG3.C and generates corresponding output files for each input file, with the file types OBJ and ANA. HP C puts these files in your current default directory.

4. Load the information in the data analysis files into your SCA library with the SCA LOAD command. For example:

   $ SCA LOAD PG1,PG2,PG3

   
   This command loads your library with the modules contained in the data analysis files PG1.ANA, PG2.ANA, and PG3.ANA.

5. Once the SCA library has been prepared, enter LSE to begin an SCA session. Within this context, the integration of LSE and SCA provides commands that can be used only within LSE.

C.3.2 Starting and Terminating an LSE or an SCA Session

To invoke LSE, enter the following command at the DCL prompt:

$ LSEDIT USER.C

To end an LSE session, press Ctrl/Z to get the LSE> prompt. If you want to save modifications to your file, enter the EXIT command. If you do not want to save the file or any modification to the file, enter the QUIT command.

To invoke SCA from the LSE prompt, enter the SCA command that you want to execute using the following syntax:

LSE> command [parameter] [/qualifier...]

To invoke SCA from the DCL command line for the execution of a single command, use the following syntax:

$ SCA command [parameter] [/qualifier...]

If you have several SCA commands to invoke, you might want to first invoke the SCA subsystem and then enter SCA commands:

$ SCA SCA> command [parameter] [/qualifier...]

Typing EXIT (or pressing Ctrl/Z) ends an SCA subsystem session and returns you to the DCL level.

C.3.3 Programming Language Placeholders and Tokens

The LSE language-sensitive features simplify the tasks of developing and maintaining software systems. These features include language-specific placeholders and tokens, aliases, comment and indentation control, and templates for subroutine libraries.

You can use LSE as a traditional text editor. In addition, you can use the power of LSE's tokens and placeholders to step through each program construct and supply text for those constructs that need it.

Placeholders are markers in the source code that indicate where you can provide program text. These placeholders help you to supply the appropriate syntax in a given context. You do not need to type placeholders; they are inserted for you by LSE. Placeholders are surrounded by brackets or braces and at (@) signs.

Placeholders are either optional or required. Required placeholders, indicated by braces ({}), represent places in the source code where you must provide program text. Optional placeholders, indicated by brackets ([]), represent places in the source code where you can either provide additional constructs or erase the placeholder.

You can move forward or backward from placeholder to placeholder. In addition, you can delete or expand placeholders as needed.

Tokens typically represent keywords in HP C. When expanded, tokens provide additional language constructs. You can type tokens directly into the buffer. You use tokens in situations, such as modifying an existing program, where you want to add additional language constructs and there are no placeholders. For example, typing IF and entering the EXPAND command causes a template for an IF construct to appear on your screen. You can also use tokens to bypass long menus in situations where expanding a placeholder, such as {@statement@}, will result in a lengthy menu.

You can use tokens to insert text when editing an existing file by typing the name for a function or keyword and entering the EXPAND command.

LSE provides commands for manipulating tokens and placeholders. Table C-1 shows these commands and their default key bindings.

Table C-1 Commands to Manipulate Tokens and Placeholders

Command	Key Binding	Function
EXPAND	Ctrl/E	Expands a placeholder.
UNEXPAND	PF1-Ctrl/E	Reverses the effect of the most recent placeholder expansion.
GOTO PLACEHOLDER/FORWARD	Ctrl/N	Moves the cursor forward to the next placeholder.
GOTO PLACEHOLDER/REVERSE	Ctrl/P	Moves the cursor backward to the next placeholder.
ERASE PLACEHOLDER/FORWARD	Ctrl/K	Erases a placeholder.
UNERASE PLACEHOLDER	PF1-Ctrl/K	Restores the most recently erased placeholder.
Down arrow	Down-arrow key	Moves the indicator downward through a screen menu.
Up arrow	Up-arrow key	Moves the indicator upward through a screen menu.
[Enter] [Return]	ENTER RETURN	Selects a menu option.

To display a list of all the defined tokens provided by HP C, enter the following LSE command:

LSE> SHOW TOKEN

To display a list of all the defined placeholders provided by HP C, enter the following LSE command:

LSE> SHOW PLACEHOLDER

To put either list into a separate file, first enter the appropriate SHOW command to put the list into the $SHOW buffer. Then enter the following commands:

LSE> GOTO BUFFER $SHOW LSE> WRITE filename

To obtain a hard copy of the list, use the PRINT command at DCL level to print the file you created.

To obtain information about a particular token or placeholder, specify a token name or placeholder name after the SHOW TOKEN or SHOW PLACEHOLDER command.

C.3.4 Compiling Source Code

To compile your source code and to review compilation errors without leaving the editing session, use the LSE commands COMPILE and REVIEW. The COMPILE command issues a DCL command in a subprocess to invoke the HP C compiler. The compiler then generates a file of compile-time diagnostic information that LSE uses to review compilation errors. The diagnostic information is generated with the /DIAGNOSTICS qualifier that LSE appends to the compilation command.

For example, if you enter the COMPILE command while in the buffer USER.C, the following DCL command is executed:

$ CC USER.C/DIAGNOSTICS=USER.DIA

LSE supports all the HP C compiler's command qualifiers as well as user-supplied command procedures.

The REVIEW command displays any diagnostic messages that result from a compilation. LSE displays the compilation errors in one window and the corresponding source code in a second window. This multiwindow capability allows you to review your errors while examining the associated source code.

To compile a HP C program that contains placeholders and design comments, include the following qualifiers to the COMPILE command:

LSE> COMPILE $/ANALYSIS_DATA/DESIGN

The /ANALYSIS_DATA qualifier generates a data analysis file containing source code analysis information. This information is provided to the SCA library.

The /DESIGN qualifier instructs the compiler to recognize placeholders and design comments as valid program elements. If the /ANALYSIS_DATA qualifier is also specified, the compiler includes information on placeholders and design comments in the data analysis file.

C.3.5 LSE Examples

The following examples show the expansions of HP C tokens and placeholders. The intent is to show the formats and guidelines that LSE provides, not to fully expand all tokens and placeholders. An arrow (->) indicates where in the example an action occurred.

To invoke LSE and the HP C language, use the following syntax:

LSEDIT [/qualifier...] filename.C

C.3.5.1 Compilation Unit

When you use the editor to create a new HP C program, the initial string {@compilation unit@} appears at the top of the screen:

-> {@compilation unit@} [End of file]

Use Ctrl/E to expand this initial string. The following is displayed:

-> [@#module@] [@module level comments@] [@include files@] [@macro definitions@] [@preprocessor directive@]... [@data type or declaration@]...; [@function definition@]...;

C.3.5.2 Preprocessor Lines

Erase the [@#module@] , [@module level comments@] , [@include files@] , and [@macro definitions@] . The cursor is then positioned on [@preprocessor directive@] . Expand [@preprocessor directive@] to duplicate it and display a menu. Then select the #include option:

1. Use the up and down arrows on the keypad to position the displayed selection arrow next to #include .
2. Press Return.

The following display results:

-> #include [@preprocessor directive@]... [@data type or declaration@]...; [@function definition@]...;

After selecting the #include option, another menu appears that lists the types of #include statements. Select the option #include {@module name@} . Your display now looks like this:

-> #include {@module name@} [@preprocessor directive@]... [@data type or declaration@]...; [@function definition@]...;

Type the value stdio over the placeholder {@module name@} .

Experiment with the LSE editor to expand other placeholders, such as [@data type or declaration@] , [@function definition@] , and so on.

C.4 CDD/Repository

CDD/Repository is an optional OpenVMS software product available under a separate license. The CDD/Repository product allows you to maintain shareable data definitions (language-independent structure declarations) that are defined by a data or repository administrator.

C.4.1 Using CDD/Repository

CDD/Repository data definitions are organized hierarchically in the same way files are organized in directories and subdirectories. For example, a repository for defining personnel data might have separate directories for each employee type.

Descriptions of data definitions are entered into the dictionary in a special-purpose language called CDO (Common Dictionary Operator, which replaces the older interface called CDDL, Common Data Dictionary Language). CDD/Repository converts the data descriptions to an internal form---making them independent of the language used to access them---and inserts them into the repository.

To extract data definitions from CDD/Repository, include the #pragma dictionary preprocessor directive in your HP C source program. If the data attributes of the data definitions are consistent with HP C requirements, the data definitions are included in the HP C program during compilation. See Section 5.4.3 for information about using #pragma dictionary .

CDD/Repository data definitions, in the form of HP C source code, appear in source program listings if you specify the /SHOW=DICTIONARY qualifier on the CC command line.

The advantage in using CDD/Repository instead of HP C source for structure declarations is that CDD/Repository record declarations are language-independent and can be used with several supported OpenVMS languages.

C.4.2 Accessing CDD/Repository from HP C Programs

A repository or data administrator uses CDO to create repositories, define directory structures, and insert record and field definitions into the repository. Many repositories can be linked together to form one logical repository. If the paths are set up correctly, users can access definitions as if they were in a single repository regardless of physical location.

CDO also creates the record paths. Once established, records can be extracted from the repository by means of the #pragma dictionary preprocessor directive in HP C programs. At compile time, the record definition and its attributes are extracted from the designated repository. Then the compiler converts the extracted record definition into a HP C structure declaration and includes it in the object module.

The #pragma dictionary preprocessor directive incorporates CDD/Repository data definitions into the HP C source file during compilation. The #pragma dictionary directive can be embedded in a HP C structure declaration. See Section 5.4.3 for sample usage of #pragma dictionary .

C.4.3 Support for CDD/Repository Data Types

CDD/Repository supports all OpenVMS data types. HP C can translate all the OpenVMS data types when they are declared in CDD/Repository records. Data types that do not occur naturally in the HP C language are handled in the following way:

• HP C never attempts to approximate a data type that is not supported by the C language.
• Instead of approximating a data type, HP C uses its own structure data type to represent all types (except for excessively long bit strings) not supported by the C language; specifically, HP C creates structures of arrays of type char that are large enough to represent the data structure.
• Bit strings (aligned or unaligned) can be up to 32 bits long, as defined by the HP C language. Bit strings longer than 32 bits are broken into increments of 32-bit strings or smaller so that the structure is correct with respect to size. However, the long bit string cannot be accessed as one unit.
• All row-major arrays are represented as zero-origin arrays of the appropriate size. An informational message is issued if the record description specifies nonzero-origin dimension bounds. The compiler adjusts the upper bound appropriately to maintain the correct number of elements relative to a lower bound of zero. Column-major arrays are converted to one-dimensional arrays containing the same total number of elements.

The compiler applies various consistency checks to the record attributes extracted from CDD/Repository, particularly the field data-type attributes. An error message is issued when a record description does not pass the consistency checks. An informational message is issued when HP C is confronted with facility-independent attributes that are not supported. An error message is issued when an attribute that is required by HP C is not present, even if the attribute is optional in CDD/Repository record protocol.

The compiler synthesizes names for unnamed and filler fields. If CDD/Repository does not specify a name and a name is required by the syntax of the HP C language, the compiler synthesizes the name cc_cdd$_unnamed_nnnnn. When CDD/Repository specifies a filler or a name that HP C does not support, the compiler synthesizes the name cc_cdd$_filler_#nnnnn, which includes the pound sign character (#). The string nnnnn represents a unique integer. The # is not a valid character in an identifier, so you cannot reference these fields.

Unsupported data types are mapped into HP C as structures of character arrays of the appropriate size. The declaration of these data types uses the following format:

struct { char Cname [s]; } CDDname;

The CDDname is the name of the member in the CDD/Repository record. Cname is an identifier of the form cc_cdd_$_unsupported_#nnnnn, where nnnnn is a unique integer, and s is the size of the data item, in bytes.

HP C generates variant_struct or variant_union declarations for unnamed CDD/Repository structures and unions, so you do not have to specify these references.

Table C-2 summarizes the mapping between CDD/Repository data types and HP C data types.

Table C-2 Mapping Between CDD/Repository and HP C Data Types

CDD/Repository Data Type	C Data Type
Unspecified Unsigned byte Unsigned word Unsigned longword Unsigned quadword Unsigned octaword	Unsupported unsigned char unsigned short unsigned int Unsupported Unsupported
Signed byte Signed word Signed longword Signed quadword Signed octaword	char short int Unsupported Unsupported
F_floating D_floating G_floating H_floating	float 1 double 1 double 1 Unsupported
F_floating complex D_floating complex G_floating complex H_floating complex	Unsupported Unsupported Unsupported Unsupported
Text Varying text 2	char [ n] Unsupported
Numeric string: Unsigned Left separate Left overpunch Right separate Right overpunch Zoned sign	Unsupported Unsupported Unsupported Unsupported Unsupported Unsupported
Packed decimal string	Unsupported
Bit Bit unaligned	Bit field 3 Bit field 3
Date and time	Unsupported
Date Virtual field Varying string 2	Unsupported Ignored Unsupported