The DSECT2C Utility

How to Use DSECT2C

This section explains how to use the DSECT2C utility. Included are discussions of input and output files, options, usage notes, and the operating system commands or control language required to invoke DSECT2C.

Input and Output

The input file to DSECT2C is an assembler listing file (under OS/390, this is the SYSPRINT data set; under CMS, it is the filetype LISTING file). To generate this file, create an assembler language program consisting of only the DSECT definition and an END instruction. Sample Assembler Language Input File shows a sample assembler language input file. If the DSECT is in an existing assembler language source library, it can be included with a COPY instruction, followed by an END instruction. DSECTs in macro libraries can be allowed to expand in the listing.

Sample Assembler Language Input File
SAMPLECB DSECT NAME DS CL8 ADDRESS DS A NUMBER DS F ORG ADDRESS DNUM DS D ORG , FLAGS DS XL1 ADDR3 DS AL3 END

Invoke the assembler and produce a listing file. DSECT2C expects stdin to be redirected to the listing file.

DSECT2C writes the C structure definition to stdout . This file also includes any typedefs used in the structure, a set of macro definitions for the structure members, and other output as specified by DSECT2C options.

Sample DSECT2C Output File shows the output file produced by DSECT2C for the DSECT defined in Sample Assembler Language Input File. There are four distinct parts:

C typedefs corresponding to assembler language types
a C structure corresponding to assembler language DSECT
C macros for each of the fields in the structure
optional cross-reference information.


Sample DSECT2C Output File



#if !defined(_AL3)
#define _AL3
typedef struct
   {
   char BF : 24;
   } AL3;
#endif

#if !defined(_CL8)
#define _CL8
typedef char CL8(|8|);
#endif

struct SAMPLECB
   {
   CL8 name;
   union
      {
      struct
         {
         void *address;
         int number;
         } _s0;
      double dnum;
      };
   char flags;
   AL3 addr3;
   };

#define ADDRESS                         _s0.address
#define ADDR3                           addr3
#define DNUM                            dnum
#define FLAGS                           flags
#define NAME                            name
#define NUMBER                          _s0.number

/*
SYMBOL      OFFSET    LENGTH    TYPE    C-TYPE    C-NAME
ADDRESS     000008    000004    A       void *    _s0.address
ADDR3       000011    000003    AL3     AL3       addr3
DNUM        000008    000008    D       double    dnum
FLAGS       000010    000001    XL1     char      flags
NAME        000000    000008    CL8     CL8       name
NUMBER      00000C    000004    F       int       _s0.number
SAMPLECB    000000    000000
*/

Note: DSECT2C generates identifiers for unnamed fields and inner structures when necessary. These identifiers always have the format _f or _s followed by an integer number. [cautionend]

Options

DSECT2C accepts six options, as shown in DSECT2C Options.

DSECT2C Options
Option Explanation

-c Assembler language comments in the input file are included as C comments in the output file.

-d DSECT2C generates a declaration of the structure, instead of a definition. The DSECT name in lowercase is used as the identifier. For example, without the -d option, the format of the structure generated by DSECT2C is
struct CNTLBLOK { . . . };

If the -d option is used, DSECT2C changes that to
struct CNTLBLOK { . . . } cntlblok;

-i The assembler language instruction associated with each structure member is included as a comment in the output file. The -i option automatically enables the -c option.

-n DSECT2C assigns names to any unions within the output structure. These names are of the form _un where n is an interger

-u stderr output is in uppercase.

-x DSECT2C adds cross-reference information to the output file.

-z DSECT2C subtitles LENGTH_ZERO or LENGTH_ZERO_REF macros for arrays with 0 elements and LENGTH_ZERO_2D macros for two-dimensional arrays whose first dimensions are 0.

***DSECT2C Options***
Option	Explanation
`-c`	Assembler language comments in the input file are included as C comments in the output file.
`-d`	DSECT2C generates a declaration of the structure, instead of a definition. The DSECT name in lowercase is used as the identifier. For example, without the `-d` option, the format of the structure generated by DSECT2C is struct CNTLBLOK { . . . }; If the `-d` option is used, DSECT2C changes that to struct CNTLBLOK { . . . } cntlblok;
`-i`	The assembler language instruction associated with each structure member is included as a comment in the output file. The `-i` option automatically enables the `-c` option.
`-n`	DSECT2C assigns names to any unions within the output structure. These names are of the form `_un` where n is an interger
`-u`	`stderr` output is in uppercase.
`-x`	DSECT2C adds cross-reference information to the output file.
`-z`	DSECT2C subtitles `LENGTH_ZERO` or `LENGTH_ZERO_REF` macros for arrays with 0 elements and `LENGTH_ZERO_2D` macros for two-dimensional arrays whose first dimensions are 0.

Usage Notes

DSECT2C creates structures that use anonymous unions, nonaligned structures, and noninteger bitfields. These types are nonstandard extensions to the C language and may not be supported by other compilers. C source files that include these structure definitions may need to be compiled with the bitfield option, using char as the default allocation unit.
For more information about language extensions, see Language Extensions. For more information on compiler options, see Compiler Options.
DSECT2C changes certain national characters to a digraph that is acceptable in a C identifier. The characters and their associated digraphs are as follows:
```
   @        A_
   #        P_
   $        D_
```
Note that only leading $'s are changed. Use the dollars compiler option if a structure member identifier contains embedded $'s.
DSECT2C may or may not be able to detect erroneous input. Do not use DSECT2C on a DSECT that caused the assembler to produce WARNING or ERROR messages.
DSECT2C calculates the offset and alignment required for each DSECT field. Each field in the DSECT is assumed to be properly aligned for its type. (Improperly aligned fields cause the assembler to generate a WARNING message.)
DSECT2C ignores all instructions in the input file except for those composing the DSECT itself and EQU statements that precede the DSECT.
Any instructions in the DSECT that are prevented from appearing in the assembler listing file (by the PRINT instruction, for example) will not appear in the C structure DSECT2C creates.
If the assembler used to create the input listing file has been modified to create a special listing format, DSECT2C may not be able to find the DSECT instruction or instructions in the DSECT. In this case, use an editor to remove unnecessary records in the listing before invoking DSECT2C.
DSECT2C converts assembler language constructs with a duplication factor of 0 to an array with 0 elements. For example, consider this assembler language statement:
```
BEGINBUF   DS   0C
```
By default, DSECT2C converts this to the following structure member:
```
char beginbuf(|0|);
```
The SAS/C Compiler accepts such an array declaration within a structure definition as a language extension. However, most C compilers do not allow a declaration of an array with 0 elements. If you attempt to compile a program containing a structure generated by DSECT2C that contains this kind of declaration using another compiler, that compiler will probably generate an error message and refuse to compile the program. The -z option causes DSECT2C to generate LENGTH_ZERO , LENGTH_ZERO_2D , and LENGTH_ZERO_REF macros, which can be used to overcome this problem.
The -z option causes DSECT2C to substitute a call to the LENGTH_ZERO macro instead of generating an array of 0 elements. The LENGTH_ZERO macro accepts two arguments, the type and name of the member. For example, if the
-z option is used, DSECT2C converts the assembler language statement shown above ( BEGINBUF DS 0C ) to the following statement:
```
LENGTH_ZERO(char, beginbuf);
```
You must supply a definition of the LENGTH_ZERO macro that generates a declaration for the member that is acceptable to the target compiler.

LENGTH_ZERO_2D macro

The LENGTH_ZERO_2D macro is used when the member is a two-dimensional array whose first dimension is 0. As shown here, the LENGTH_ZERO_2D macro accepts three arguments, the type of the member, its name, and the second dimension:

LENGTH_ZERO_2D(int, nfield, 2);

LENGTH_ZERO_REF macro

The LENGTH_ZERO_REF macro is generated by DSECT2C in the C macro corresponding to a structure member. By default, the macro for a zero-length array member is defined as follows:

#define BEGINBUF      beginbuf(|0|)

If the -z option is used, DSECT2C substitutes the following LENGTH_ZERO_REF macro:

#define BEGINBUF      LENGTH_ZERO_REF(beginbuf)

The LENGTH_ZERO_REF macro accepts one argument, the member name.

DSECT2C also generates default definitions of these three macros. These definitions produce the same member declaration as would be generated if the -z option were not in effect. Each definition is protected by an #if !defined preprocessor statement, so any definitions you supply override the default definitions. The default definitions generated by DSECT2C are

#if !defined(LENGTH_ZERO)
#define LENGTH_ZERO(type, name) type name(|0|)
#endif
#if !defined(LENGTH_ZERO_2D)
#define LENGTH_ZERO_2D(type, name, dim) type name(|0|)(|dim|)
#endif
#if !defined(LENGTH_ZERO_REF)
#define LENGTH_ZERO_REF(name) name(|0|)
#endif

Invoking DSECT2C

DSECT2C is a C program and can be invoked as you would any other C program. In general, you must specify the name of the DSECT to be converted and any options, redirect stdin to the assembler listing file, and redirect stdout to the desired output file.

In TSO

In TSO, you invoke DSECT2C with the CALL command, with the C command, or as a TSO command. If you use the TSO CALL command, invoke DSECT2C as follows:

CALL 'library.name(DSECT2C)'  'dsect [listing] output options'

library.name is the name of the data set containing DSECT2C.

dsect is the name of the DSECT to be converted.

listing is either the DDname allocated to the assembler listing or the data set name of the assembler listing. If a data set name is specified, it must be prefixed with either tso: or dsn: . The highest level qualifier of the data set must also be included.

output is either the DDname allocated to the output data set or the data set name of the output data set.

options are DSECT2C options.

Following is an example:

CALL 'SASC.LOAD(DSECT2C)'
        'IHADCB <tso:MYDSECT.LIST(IHADCB) >tso:MYDSECT.H(IHADCB)'

Consult your SAS Software Representative for C compiler products for the correct library.name.

Under CMS

Under CMS, invoke DSECT2C as follows:

DSECT2C dsect [listing ]output options

dsect is the name of the DSECT to be converted.

listing is the assembler listing file.

output is the output file.

options are DSECT2C options.

Following is an example:

DSECT2C FSCBD <FSCBD.LISTING >FSCBD.H

Under OS/390 batch

The DSECT2C cataloged procedure can be used to execute DSECT2C under OS/390 batch. This procedure allocates SYSPRINT to a temporary data set, invokes the assembler, and then invokes DSECT2C to produce the C structure. You should provide a DD card for the assembler SYSIN data set and a DD card for DSECT2C's D2COUT data set. Sample JCL for Running the DSECT2C Cataloged Procedure shows typical JCL for using the DSECT2C cataloged procedure.

Sample JCL for Running the DSECT2C Cataloged Procedure
//SAMPD2C JOB job card information //*---------------------------------------------------- //* INVOKE ASSEMBLER AND DSECT2C //* //* REPLACE GENERIC DATA SET NAMES AS APPROPRIATE //*---------------------------------------------------- //STEP1 EXEC DSECT2C,PARM.D2C='dsect-name options ' //ASM.SYSIN DD DSN=assembler.source.file ,DISP=SHR //D2C.D2COUT DD DSN=your.output.file ,DISP=OLD //

In this example,

dsect-name is the name of the DSECT to be converted.

options are DSECT2C options. Separate options with blanks, not commas.

The ASM step of the DSECT2C procedure contains a SYSLIB DD card for the source file libraries SYS1.MACLIB and SYS1.AMODGEN. Note that DSECT2C is not invoked unless the return code from the assembler is 0.

The DSECT2C procedure contains the JCL shown in Expanded JCL for DSECT2C.


Expanded JCL for DSECT2C



//DSECT2C  PROC
//ASM      EXEC PGM=ASMBLR,PARM=TERM
//SYSTERM  DD SYSOUT=*
//SYSPUNCH DD DUMMY
//SYSLIN   DD DUMMY
//SYSUT1   DD DSN=&&SYSUT1,UNIT=SYSDA,SPACE=(TRK,(5,1))
//SYSUT2   DD DSN=&&SYSUT2,UNIT=SYSDA,SPACE=(TRK,(5,1))
//SYSUT3   DD DSN=&&SYSUT3,UNIT=SYSDA,SPACE=(TRK,(5,1))
//SYSLIB   DD DSN=SYS1.MACLIB,DISP=(SHR,KEEP,KEEP)
//         DD DSN=SYS1.AMODGEN,DISP=(SHR,KEEP,KEEP)
//SYSPRINT DD DSN=&&LISTING,DCB=(RECFM=FBA,LRECL=121,BLKSIZE=1089),
//            DISP=(NEW,PASS),UNIT=SYSDA
//D2C      EXEC PGM=DSECT2C,COND=(0,NE,ASM)
//STEPLIB  DD DSN=SASC.LOAD,DISP=SHR        COMPILER LIBRARY
//         DD DSN=SASC.LINKLIB,DISP=SHR       RUNTIME LIBRARY
//SYSIN    DD DSN=*.ASM.SYSPRINT,DISP=(OLD,DELETE,DELETE),
//            VOL=REF=*.ASM.SYSPRINT
//SYSTERM  DD SYSOUT=*
//SYSPRINT DD DDNAME=D2COUT

Chapter Contents
Previous
Next
Top of Page

library.name	is the name of the data set containing DSECT2C.
dsect	is the name of the DSECT to be converted.
listing	is either the DDname allocated to the assembler listing or the data set name of the assembler listing. If a data set name is specified, it must be prefixed with either `tso:` or `dsn:` . The highest level qualifier of the data set must also be included.
output	is either the DDname allocated to the output data set or the data set name of the output data set.
options	are DSECT2C options.

dsect	is the name of the DSECT to be converted.
listing	is the assembler listing file.
output	is the output file.
options	are DSECT2C options.

dsect-name	is the name of the DSECT to be converted.
options	are DSECT2C options. Separate options with blanks, not commas.