DSECT Utility options

The options that you can use to control the generation of the C or C++ structure are as follows. You can specify them in uppercase or lowercase, separating them by spaces or commas.

Table 1. DSECT Utility options, abbreviations, and IBM-supplied defaults
DSECT Utility Option	Abbreviated Name	IBM-supplied Default
SECT[(name,…)]	None	SECT(ALL)
BITF0XL \| NOBITF0XL	BITF \| NOBITF	NOBITF0XL
COMMENT[(delim,…)] \| NOCOMMENT	COM \| NOCOM	COMMENT
DECIMAL \| NODECIMAL	None	NODECIMAL
DEFSUB \| NODEFSUB	DEF \| NODEF	DEFSUB
EQUATE[(suboptions,…)] \| NOEQUATE	EQU \| NOEQU	NOEQUATE
HDRSKIP[(length)] \| NOHDRSKIP	HDR(length) \| NOHDR	NOHDRSKIP
INDENT[(count)] \| NOINDENT	IN(count) \| NOIN	INDENT(2)
LEGACY\| NOLEGACY	LEG \| NOLEG	NOLEGACY
LOCALE(name) \| NOLOCALE	LOC \| NOLOC	NOLOCALE
OPTFILE(filename) \| NOOPTFILE	OPTF \| NOOPTF	NOOPTFILE
PPCOND[(switch)] \| NOPPCOND	PP(switch) \| NOPP	NOPPCOND
SEQUENCE \| NOSEQUENCE	SEQ \| NOSEQ	NOSEQUENCE
UNIQUE\|NOUNIQUE	None	NOUNIQUE
UNNAME \| NOUNNAMED	UNN \| NOUNN	NOUNNAMED
OUTPUT[(filename)]	OUT[(filename)]	OUTPUT (DD:EDCDSECT)
RECFM[(recfm)]	None	C/C++ Library defaults
LRECL[(lrecl)]	None	C/C++ Library defaults
BLKSIZE[(blksize)]	None	C/C++ Library defaults
LP64	None	NOLP64

SECT

DEFAULT: SECT(ALL)

The SECT option specifies the section names for which structures are produced. The section names can be either CSECT or DSECT names. They must exist in the SYSADATA file that is produced by the assembler. If you do not specify the SECT option or if you specify SECT(ALL), structures are produced for all CSECTs and DSECTs defined in the SYSADATA file, except for private code and unnamed DSECTs.

If the High Level Assembler is run with the BATCH option, only the section names defined within the first program can be specified on the SECT option. If you specify SECT(ALL) (or select it by default), only the sections from the first program are selected.

BITF0XL | NOBITF0XL

DEFAULT: NOBITF0XL

Specify the BITF0XL option when the bit fields are mapped into a flag byte as in the following example:

FLAGFLD   DS   F
          ORG  FLAGFLD+0
B1FLG1    DC   0XL(B'10000000')'00'    Definition for bit 0 of 1st byte
B1FLG2    DC   0XL(B'01000000')'00'    Definition for bit 1 of 1st byte
B1FLG3    DC   0XL(B'00100000')'00'    Definition for bit 2 of 1st byte
B1FLG4    DC   0XL(B'00010000')'00'    Definition for bit 3 of 1st byte
B1FLG5    DC   0XL(B'00001000')'00'    Definition for bit 4 of 1st byte
B1FLG6    DC   0XL(B'00000100')'00'    Definition for bit 5 of 1st byte
B1FLG7    DC   0XL(B'00000010')'00'    Definition for bit 6 of 1st byte
B1FLG8    DC   0XL(B'00000001')'00'    Definition for bit 7 of 1st byte
          ORG  FLAGFLD+1
B2FLG1    DC   0XL(B'10000000')'00'    Definition for bit 0 of 2nd byte
B2FLG2    DC   0XL(B'01000000')'00'    Definition for bit 1 of 2nd byte
B2FLG3    DC   0XL(B'00100000')'00'    Definition for bit 2 of 2nd byte
B2FLG4    DC   0XL(B'00010000')'00'    Definition for bit 3 of 2nd byte

When the bit fields are mapped as shown in this example, you can use the following code to test the bit fields:

TM   FLAGFLD,L'B1FLG1          Test bit 0 of byte 1
Bx   label                     Branch if set/not set

When you specify the BITF0XL option, the length attribute of the following fields provides the mapping for the bits within the flag bytes.

The length attribute of the following fields is used to map the bit fields if a field conforms to the following rules:

The field does not have a duplication factor of zero.
The field has a length between 1 and 4 bytes and does not have a bit length.
The field does not have more than one nominal value.

and the following fields conform to the following rules:

Has a Type attribute of B, C, or X.
Has the same offset as the field (or consecutive fields have overlapping offsets).
Has a duplication factor of zero.
Does not have more than one nominal value.
Has a length attribute between 1 and 255 and does not have a bit length.
The length attribute maps one bit or consecutive bits; for example, B'10000000' or B'11000000', but not B'10100000'.

The fields must be on consecutive lines and must overlap a named field. If these fields are used to define the bits for a field, EQU statements that follow the field are not used to define the bit fields.

COMMENT | NOCOMMENT

DEFAULT: COMMENT

The COMMENT option specifies whether the comments on the line where the field is defined will be placed in the structure produced.

If you specify the COMMENT option without a delimiter, the entire comment is placed in the structure.

If you specify a delimiter, any comments that follow the delimiter are skipped and are not placed in the structure. You can remove changes that are flagged with a particular delimiter. The delimiter cannot contain imbedded spaces or commas. The case of the delimiter and the comment text is not significant. You can specify up to 10 delimiters, and they can contain up to 10 characters each.

DECIMAL | NODECIMAL

DEFAULT: NODECIMAL

The DECIMAL option will instruct the DSECT utility to convert all SYSATADA DC/DS records of type P to the function type macro: _dec__var(w,0). w is the number of digits and it is computed by taking the byte size of the P-type data, multiplying it by two, and subtracting one from the result [in other words, (byte_size * 2)-1]. The byte size of the P type data is found in the SYSADATA DC/DS record. If a SYSADATA DC/DS record of type P is interpreted to be part of a union then the DSECT utility will map it to the function type macro: _dec__uvar(w,0). w still represents the number of digits. The _dec__uvar macro will expand to a decimal datatype for C and a unsigned character array for C++. This is necessary because decimal support in C++ is implemented by a decimal class. C++ does not allow a class with constructors, or deconstructors, to be part of a union, hence in the case of C++ such decimal data must be mapped to a character array of the same byte size.

The precision will always be left as zero since there is no way to figure out its value from the DC/DS SYSADATA record. The zero will be output, rather than just the digit size (that is, _dec__var(w,0) rather than just _dec__var(w,)) ), to allow you to easily edit the DSECT utility output and adjust for the needed precision. Do not remove the zero as it will cause compilation errors because the function type macros can no longer be expanded.

If the DECIMAL option is enabled and P type records are found, then the utility will also include the following code at the beginning of the output file:

#ifndef __decimal_found
     #define __decimal_found
     #ifdef __cplusplus
         #define _dec__var(w,p)  decimal<n>
             #define _dec_uvar(w,p) _decchar##w
         #include <idecimal.hpp>
             typedef char _decchar1[1];
             typedef char _decchar2[2];
             typedef char _decchar3[2];
             typedef char _decchar4[3];
             typedef char _decchar5[3];
             typedef char _decchar6[4];
             typedef char _decchar7[4];
             typedef char _decchar8[5];
             typedef char _decchar9[5];
             typedef char _decchar10[6];
             typedef char _decchar11[6];
             typedef char _decchar12[7];
             typedef char _decchar13[7];
             typedef char _decchar14[8];
             typedef char _decchar15[8];
             typedef char _decchar16[9];
             typedef char _decchar17[9];
             typedef char _decchar18[10];
             typedef char _decchar19[10];
             typedef char _decchar20[[11];
             typedef char _decchar21[11];
             typedef char _decchar22[12];
             typedef char _decchar23[12];
             typedef char _decchar24[13];
             typedef char _decchar25[13];
             typedef char _decchar26[14];
             typedef char _decchar27[14];
             typedef char _decchar28[15];
             typedef char _decchar29[15];
             typedef char _decchar30[16];
             typedef char _decchar31[16];
     #else
         #define _dec__var(w,p)  decimal(n,p)
             #define _dec_uvar(w,p) decimal(w,p)
         #include <decimal.h>
     #endif
 #endif

This code will force the inclusion of the necessary header files, depending on whether the C or C++ compiler is used. It will also force the _dec__var and _dec_uvar types, which are outputted by the DSECT utility, to be mapped to the appropriate C or C++ decimal type. The definition of the macro __decimal_found is used to guard against the redefinition of macros if several DSECT utility output files are compiled together.

If the default NODECIMAL option is used then the DSECT utility will convert all P type DC/DS SYSATADA records to character arrays of the same byte size as the P type data, as is the existing behavior; for example, 171 (a value of PL3) will map to an unsigned char[3].

DEFSUB | NODEFSUB

DEFAULT: DEFSUB

The DEFSUB option specifies whether #define directives will be built for fields that are part of a union or substructure.

Example: If the DEFSUB option is in effect, fields within a substructure or union have the field names prefixed by an underscore. A #define directive is written at the end of the structure to allow the field name to be specified directly as in the following example.

struct dsect_name {
  int           field1;
  struct {
    int           _subfld1;
    short int     _subfld2;
    unsigned char _subfld3[4];
    } field2;
  }
#define subfld1  field2._subfld1
#define subfld2  field2._subfld2
#define subfld3  field2._subfld3

If the DEFSUB option is in effect, the fields that are prefixed by an underscore may match the name of another field within the structure. No warning is issued.

EQUATE | NOEQUATE

DEFAULT: NOEQUATE

The EQUATE option specifies whether the EQU statements following a field are to be used to define bit fields, to generate #define directives, or are to be ignored.

The suboptions specify how the EQU statement is used. You can specify one or more of the suboptions, separating them by spaces or commas. If you specify more than one suboption, the EQU statements that follow a field are checked to see if they are valid for the first suboption. If so, they are formatted according to that option. Otherwise, the subsequent suboptions are checked to see if they are applicable.

If you specify the EQUATE option without suboptions, EQUATE(BIT) is used. If you specify NOEQUATE (or select it by default), the EQU statements that follow a field are ignored.

You can specify the following suboptions for the EQUATE option:

BIT

Indicates that the value for an EQU statement is used to define the bits for a field where the field conforms to the following rules:

The field does not have a duplication factor of zero.
The field has a length between 1 and 4 bytes and has a bit length that is a multiple of 8.
The field does not have more than one nominal value.

and the EQU statements that follow the field conform to the following rules:

The value for the EQU statements that follow the field mask consecutive bits (for example, X'80' followed by X'40').
The value for an EQU statement masks one bit or consecutive bits for example, B'10000000' or B'11000000', but not B'10100000'.
Where the length of the field is greater than 1 byte, the bits for the remaining bytes can be defined by providing the EQU statements for the second byte after the EQU statement for the first byte.
The value for the EQU statement is not a relocatable value.

Example: When you specify EQUATE(BIT), the EQU statements are converted as in the following example:

FLAGFLD  DS   H
FLAG21   EQU  X'80'
FLAG22   EQU  X'40'
FLAG23   EQU  X'20'
FLAG24   EQU  X'10'
FLAG25   EQU  X'08'
FLAG26   EQU  X'04'
FLAG27   EQU  X'02'
FLAG28   EQU  X'01'
FLAG2A   EQU  X'80'
FLAG2B   EQU  X'40'
struct dsect_name {
  unsigned int flag21   : 1,
               flag22   : 1,
               flag23   : 1,
               flag24   : 1,
               flag25   : 1,
               flag26   : 1,
               flag27   : 1,
               flag28   : 1,
               flag2a   : 1,
               flag2b   : 1,
                        : 6;
  }

BITL

Indicates that the length attribute for an EQU statement is used to define the bits for a field where the field conforms to the following rules:

The field does not have a duplication factor of zero.
The field has a length between 1 and 4 bytes and has a bit length that is a multiple of 8.
The field does not have more than one nominal value.

and the EQU statements that follow the field conform to the following rules:

The value that is specified for the EQU statement has the same or overlapping offset as the field.
The length attribute for the EQU statement is between 1 and 255.
The length attribute for the EQU statement masks one bit or consecutive bits; for example, B'10000000' or B'11000000', but not B'10100000'.
The value for the EQU statement is a relocatable value.

Example: When you specify EQUATE(BITL), the EQU statements are converted as in the following example:

BYTEFLD   DS   F
B1FLG1    EQU  BYTEFLD+0,B'10000000'
B1FLG2    EQU  BYTEFLD+0,B'01000000'
B1FLG3    EQU  BYTEFLD+0,B'00100000'
B1FLG4    EQU  BYTEFLD+0,B'00010000'
B1FLG5    EQU  BYTEFLD+0,B'00001000'
B1FLG6    EQU  BYTEFLD+0,B'00000100'
B1FLG7    EQU  BYTEFLD+0,B'00000010'
B1FLG8    EQU  BYTEFLD+0,B'00000001'
B2FLG1    EQU  BYTEFLD+1,B'10000000'
B2FLG2    EQU  BYTEFLD+1,B'01000000'
B2FLG3    EQU  BYTEFLD+1,B'00100000'
B2FLG4    EQU  BYTEFLD+1,B'00010000'
struct dsect_name {
  unsigned int b1flg1  : 1,
               b1flg2  : 1,
               b1flg3  : 1,
               b1flg4  : 1,
               b1flg5  : 1,
               b1flg6  : 1,
               b1flg7  : 1,
               b1flg8  : 1,
               b2flg1  : 1,
               b2flg2  : 1,
               b2flg3  : 1,
               b2flg4  : 1,
                       : 20;
  }

DEF

Indicates that the EQU statements following a field are used to build #define directives to define the possible values for a field. The #define directives are placed after the end of the structure. The EQU statements should not specify a relocatable value.

Example: When you specify EQUATE(DEF), the EQU statements are converted as in the following example:

FLAGBYTE DS   X
FLAG1    EQU  X'80'
FLAG2    EQU  X'20'
FLAG3    EQU  X'10'
FLAG4    EQU  X'08'
FLAG5    EQU  X'06'
FLAG6    EQU  X'01'
struct dsect_name {
  unsigned char flagbyte;
  }
/* Values for flagbyte field */
#define flag1 0x80
#define flag2 0x20
#define flag3 0x10
#define flag4 0x08
#define flag5 0x06
#define flag6 0x01

DEFS

EQU(DEFS) is equivalent to EQU(DEF) with the exception of generating string literals as opposed to hex values for EQU asm instruction with C type operand in the range of 1 - 4 bytes. EQU(DEFS) can be specified together with other suboptions like BIT and BIFS, but not with DEF.

Example: When you specify EQUATE(DEFS), the EQU statements are converted as in the following example:

MYDSECT  DSECT         
KEYS      DS CL4       
KEY1      EQU C'KEY1'  
KEY2      EQU C'KEY2'  
KEY3      EQU C'KEY3'  
             END          
struct mydsect {                    
  unsigned char  keys;           
  };                                
/* Values for field "keys" */       
#define key1 "KEY1"                 
#define key2 "KEY2"                 
#define key3 "KEY3"

HDRSKIP | NOHDRSKIP

DEFAULT: NOHDRSKIP

The HDRSKIP option specifies that the fields within the specified number of bytes from the start of the section are to be skipped. Use this option where a section has a header that is not required in the structure produced.

The value that is specified on the HDRSKIP option indicates the number of bytes at the start of the section that are to be skipped. HDRSKIP(0) is equivalent to NOHDRSKIP.

Example: In the following example, if you specify HDRSKIP(8), the first two fields are skipped and only the remaining two fields are built into the structure.

SECTNAME DSECT
PREFIX1  DS   CL4
PREFIX2  DS   CL4
FIELD1   DS   CL4
FIELD2   DS   CL4
struct sectname {
  unsigned char field1[4];
  unsigned char field2[4];
  }

If the value specified for the HDRSKIP option is greater than the length of the section, the structure is not be produced for that section.

INDENT | NOINDENT

DEFAULT: INDENT(2)

The INDENT option specifies the number of character positions that the fields, unions, and substructures are indented. Turn off indentation by specifying INDENT(0) or NOINDENT. The maximum value that you can specify for the INDENT option is 32767.

LEGACY | NOLEGACY

DEFAULT: NOLEGACY

When the NOLEGACY option is in effect, a zero extend array is inserted into the structure to represent the fields with a duplication factor of zero. You are recommended to use the NOLEGACY option to make the C structure that is generated by DSECT utility match the layout of DSECT interpreted by HLASM.

When the LEGACY option is in effect, zero extend arrays are not inserted into the structure.

Example 1: Use the DSECT utility to process the following ASM code:

TEST       DSECT
FIELD1     DS    AL1
FIELD2     DS    AL2
FIELD3     DS    AL3
DSECTEND   DS    0D
LEN        EQU   *-TEST
END

When the NOLEGACY option is in effect, the following C structure is generated:

struct test {
  unsigned char  field1;
  unsigned short field2;
  unsigned int   field3 : 24;
  unsigned char  _filler1[2];
  __extension__ double         dsectend[0];
  };

The size of the test structure is 8 bytes. The offset of dsectend is also 8 bytes and there is no space allocated for it. The zero extend array, which is the C/C++ language extension, is used to represent the ASM field dsectend with the duplication factor of zero. The __extension__ keyword is required so the resulting structure can be used in any language level.

When the LEGACY option is in effect, the following C structure is generated:

struct test {
  unsigned char  field1;
  unsigned short field2;
  unsigned int   field3 : 24;
  unsigned char  _filler1[2];
  double         dsectend;
  };

No zero extend array is generated in the structure and the ASM field dsectend is represented by a regular structure member. The structure test in the output is 8 bytes bigger than the one generated with NOLEGACY option in effect.

Example 2: Use the DSECT utility to process the following ASM code:

ABC     DSECT
F32      DS   2X
F32A     DS   0XL(B'00000010')'00'
F32B     DS   0XL(B'00000001')'00'
         END

When the NOLEGACY option is in effect, the following C structure is generated:

struct abc {
unsigned char f32[2];
__extension__ union {
unsigned char _f32a[2];
unsigned char _f32b;
} _abc_union1[0];
};

#define f32a _abc_union1[0]._f32a
#define f32b _abc_union1[0]._f32b

The zero extend array of a union is inserted to the structure, so that the size of the structure, abc, is 2 bytes. The #define directives at the end of the structure are present, so _f32a and _f32b can be accessed by the same names 'f32a' and 'f32b' respectively as before when LEGACY option is in effect.

When the LEGACY option is in effect, the following C structure is generated:

struct abc {
  unsigned char  f32[2];
  struct {
   unsigned char  _f32b;
   unsigned char  _filler1;
   } f32a;
  };
#define f32b     f32a._f32b

No zero extend array is generated in the structure.

LOCALE | NOLOCALE

The LOCALE(name) specifies the name of a locale to be passed to the setlocale() function. Specifying LOCALE without the name parameter is equivalent to passing the NULL string to the setlocale() function.

The structure produced contains the left and right brace, and left and right square bracket, backslash, and number sign which have different code point values for the different code pages. When the LOCALE option is specified, and these characters are written to the output file, the code point from the LC_SYNTAX category for the specified locale is used.

The default is NOLOCALE.

You can abbreviate the option to LOC(name) or NOLOC.

LOWERCASE | NOLOWERCASE

DEFAULT: LOWERCASE>

The LOWERCASE> option specifies whether the field names within the C structure are to be converted to lowercase or left as entered. If you specify LOWERCASE>, all the field names are converted to lowercase. If you specify NOLOWERCASE, the field names are built into the structure in the case in which they were entered in the assembler section.

LP64 | NOLP64

DEFAULT: NOLP64

The equivalent of NOLP64 for the compiler is the option ILP32, which means 32-bit integer, long, and pointer type. This is the default in the compiler as well. LP64 means 64-bit long and pointer type. LP64 and ILP32 specify the data model for the programming language.

The LP64 option instructs the DSECT utility to generate structures for use by the programs compiled with the LP64 option. When this option is enabled, address fields are mapped to C pointer types (64 bits), and 64-bit integer fields are mapped to long data types. C/C++ also supports a __ptr32 qualifier for declaring pointers that are 32-bit in size, which means that if a field is explicitly specified with a 31-bit address, it is mapped to a __ptr32 qualified pointer.

OPTFILE | NOOPTFILE

The OPTFILE(filename) option specifies the filename that contains the records that specify the options to be used for processing the sections. The records must be as follows:

The lines must begin with the SECT option, and only one section name must be specified. The options following determine how the structure is produced for the specified section. The section name must only be specified once.
The lines may contain the BITF0XL, COMMENT, DEFSUB, EQUATE, HDRSKIP, INDENT, LOWERCASE, PPCOND, and UNNAMED options, separated by spaces or commas. These override the options that are specified on the command line for the section.

The OPTFILE option is ignored if the SECT option is also specified on the command line.

The default is NOOPTFILE.

You can abbreviate the option to OPTF(filename) or NOOPTF.

PPCOND | NOPPCOND

DEFAULT: NOPPCOND

The PPCOND option specifies whether preprocessor directives will be built around the structure definition to prevent duplicate definitions.

If you specify PPCOND, the following are built around the structure definition.

#ifndef switch
#define switch
⋮
  structure definition for section
⋮
#endif

where switch is the switch specified on the PPCOND option or the section name prefixed and suffixed by two underscores; for example, _ _name_ _.

If you specify a switch, the #ifndef and #endif directives are placed around all structures that are produced. If you do not specify a switch, the #ifndef and #endif directives are placed around each structure produced.

SEQUENCE | NOSEQUENCE

DEFAULT: NOSEQUENCE

The SEQUENCE option specifies whether sequence numbers will be placed in columns 73 to 80 of the output record. If you specify the SEQUENCE option, the structure is built into columns 1 to 72 of the output record, and sequence numbers are placed in columns 73 to 80. If you specify NOSEQUENCE (or select it by default), sequence numbers are not generated, and the structure is built within all available columns in the output record.

If the record length for the output file is less than 80 characters, the SEQUENCE option is ignored.

UNIQUE | NOUNIQUE

DEFAULT: NOUNIQUE

The UNIQUE option tells the DSECT utility to consider the given unique string as not occurring in any field names in the input SYSADATA. This is necessary because it is a guarantee from the user that if the DSECT utility were to use the unique string to map national characters, no conflict would occur with any other field name. Given this guarantee the DSECT utility maps national characters as follows:

# = unique string + 'n' + unique string
@ = unique string + 'a' + unique string
$ = unique string + 'd' + unique string

Example: If the default "_" unique string was used then the national characters would be mapped as:

# = _n_
@ = _a_
$ = _d_

If the default NOUNIQUE option is enabled, the DSECT utility converts all national characters to a single underscore, even if the resulting label names conflict (as is the existing behavior).

Note: If the DSECT utility detects a field name that has a length that exceeds the maximum allowed, a message is displayed and the name is truncated in the output. This can happen due to the substitution characters in the UNIQUE option. That is, the field name as specified by you is within the maximum limit, but due to the presence of national characters and the mapping done by UNIQUE, the resulting field name can exceed the limit. The DSECT utility then ends the output field name with "..." to make it easy to find. You should check and fix the field name either by changing the UNIQUE option, or by shortening the original field name, or both.

UNNAMED | NOUNNAMED

DEFAULT: NOUNNAMED

The UNNAME option specifies that names are not generated for the unions and substructures within the main structure.

OUTPUT

DEFAULT: OUTPUT(DD:EDCDSECT)

The structures that are produced are, by default, written to the EDCDSECT DD statement. You can use the OUTPUT option to specify an alternative DD statement or data set name to write the structure. You can specify any valid file name up to 60 characters in length. The file name specified will be passed to fopen() as entered.

RECFM

DEFAULT: C/C++ Library default

The RECFM option specifies the record format for the file to be produced. You can specify up to 10 characters. If it is not specified, the C or C++ library defaults are used.

LRECL

DEFAULT: C/C++ Library default

The LRECL option specifies the logical record length for the file to be produced. The logical record length that is specified must not be greater than 32767. If it is not specified, the C or C++ library defaults will be used.

BLKSIZE

DEFAULT: C/C++ Library default

The BLKSIZE option specifies the block size for the file to be produced. The block size that is specified must not be greater than 32767. If it is not specified, the C or C++ library defaults will be used.