DEFINITION SPECIFICATION


The definition specification is used to define data to the program. This includes fields, arrays, tables, data structures, data structure subfields, procedure parameter lists, and prototypes. The base properties (attributes) of each data item are specified on the definition specification. In addition to the base properties, the definition specification supports keyword properties. These keyword properties extend the definition of the item.

The definition specification can be specified within the mainline procedure and subprocedures of a program. The four layouts for the definition specification are illustrated in Figures 2.3 through 2.6. Figure 2.3 is the most common definition specification layout in use. Figure 2.5 is used for special reserved locations within the program status data structure (PSDS), and within a file's I/O feedback data structure. Figure 2.6 is often used when converting previous versions of RPG to the RPG IV language. Table 2.7 lists the definition specifications.

Table 2.7: Definition Specification Summary

Column

Title

Values

Description

7 – 21

Name

Name

The RPG name assigned to the item being defined. The name can be up to 15 positions in length. The name does not have to be left justified within these positions. It can be located in any positions (i.e., it can "float") within the name location.

22

Externally described

Blank

The item is not externally described.

E

The item is externally described. A data structure can be externally described when the EXTNAME keyword is specified. A data structure subfield can be externally described when the EXTFLD keyword is specified.

23

Data area

Blank

The data structure is not a data area.

U

The data structure is also a data area. The data area name is identified by the DTAARA keyword.

24 – 25

Data set type

Blank

The item is a data structure subfield.

DS

The item is a data structure.

S

The item is a stand-alone field.

C

The Item is a constant.

PI

The item is a procedure interface definition.

PR

The item is a procedure prototype.

26 – 32

Starting location

Blank

Length notation is used.

From/To Notation

1 to 65535

Starting location (within the data structure) of the data structure subfield being declared.

33 – 39

Ending Location or Length

Blank

The item's length is based on the following:

  • For a data structure, the length is determined by the sum of the length of its subfields.

  • For a data structure subfield, the length is based on either the length of the external field definition (for externally described data structures) or the field specified for the LIKE keyword (for program-described data structures). If the subfield is not externally defined or based on another field through the LIKE keyword, then a length entry is required.

  • For constants, this entry must be blank.

From/To Notation

1 to 65535

If a starting location is specified, this value represents the ending location of the data structure subfield. If no starting location is specified, then positions 33 to 39 are considered to be the field's length.

Length notation

1 to 65535

The length of the item being defined.

-65,534 to +65,534

The relative length of the field, whose attributes are based on another field, through the LIKE keyword.

40

Data type

Blank

The data-type is implied by other item properties.

A

(CHARACTER) character field. Default for fields with no decimal positions.

B

(NUMERIC) binary field.

C

The UCS-2 (Unicode) character set can encode the characters for many written languages. The field is a character field. Each character of the field occupies two bytes in the field itself.

D

(DATE) date field.

F

(NUMERIC) floating-point numeric.

G

(GRAPHIC) double-byte character set field.

I

(NUMERIC) integer field.

N

(CHARACTER) named indicator field.

O

(OBJECT) instantiation of a class object.

P

(NUMERIC) packed decimal field.

S

(NUMERIC) zoned decimal. Default for fields with decimal positions of 0 to 30.

T

(TIME) time field.

U

(NUMERIC) unsigned integer field.

Z

(TIMESTAMP) timestamp field.

*

(POINTER) pointer data-type.

41 – 42

Decimal positions

Blank

The field is non-numeric.

0 to 30

The field is numeric.

43

Not used.

44 to 80

Functions

Blank

No additional properties are specified.

Keyword

Additional properties for the item are specified. See Table 2.11 (Definition Specification Keyword Summary) for more information.

start figure

 .....DName+++++++++++EUDs.......Length+TDc.Functions++++++++++++++++++++++++++++ 

end figure

Figure 2.3: Definition specification.

start figure

 .....DName++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 

end figure

Figure 2.4: Extended name specification.

start figure

 .....DName+++++++++++....Position++++++....Functions++++++++++++++++++++++++++++ 

end figure

Figure 2.5: Special reserved positions ("star position") specification.

start figure

 .....DName+++++++++++EUDsFrom+++To+++++TDc.Functions++++++++++++++++++++++++++++ 

end figure

Figure 2.6: Field definition specification.

Extended Name Definition

The definition specification provides a unique syntax to support long names. The default name location, positions 7 through 21, provides support for 15-position names. Under most situations, names are usually less than 15 positions.

In order to support item names longer than 15 positions, the definition specification supports the ellipse (...) that consists of three consecutive periods or dots that can be used to indicate that the name is a long name. The ellipse indicates that the name and definition are continued onto the next source line. Table 2.8 lists the layout of the extended name definition specification.

Table 2.8: Definition Specification Extended Name Summary

Column

Title

Values

Description

7 – 80

Name

Extended name...

The RPG name assigned to the item being defined. If more space is needed, a second line can be inserted into the source code. The name on this line is continued onto the next line using the ellipse (three dots...).The name can be up to 4,096 positions in length.

Names must begin in positions 7 to 21 of the definition specification.

Extended item names can be used in expressions throughout the RPG IV source member. The example shown in Figure 2.7 illustrates three extended name declarations.

start figure

 .....DName++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .....DName+++++++++++EUDS.......Length+TDc.Functions++++++++++++++++++++++++++++ 0010 D Very_Long_Field_Name_with_continuation... 0020 D                 S             35A 0030 D This_is_another_very... 0040 D long_field_name_continued_over... 0050 D four_source_lines... 0060 D                 S              7P 2 0070 D A_medium_length_field... 0080 D finishing_here  S             35A 

end figure

Figure 2.7: Extended name declarations.

Lines 10 and 20 declare a 35-position character field.

Lines 30 through 60 define a packed field with a length of 7 and 2 decimal positions.

Lines 70 and 80 define another 35-position character field.

Special PSDS Data Structure Subfields Positions

These special values are used in place of From and To positions. They represent built-in positions that contain special values. They are part of the PSDS. The PSDS is used to store both runtime and error-specific information. Many of these fields are set when the program starts; others are set when an error occurs. The definition specification shown in Figure 2.5 is the basis for this type of definition specification. Note that, although the function area is documented as part of this specification, no keywords are available to extend the properties of these fields. See Table 2.9.

Table 2.9: Definition Specification Special PSDS Data Structure Subfields Summary

Column

Title

Values

Description

7 – 21

Name

Name

The RPG name assigned to the special position value. The special position value is identified by the entry in positions 26 to 39.

26 – 39

Special position

*FILE

Name of the file being processed.

*OPCODE

The RPG operation being performed when an exception/error occurred.

*PARMS

Number of parameters passed to the program.

*ROUTINE

Name of the RPG routine (through the RPG cycle) that was being performed when an exception/error occurred.

*RECORD

Name of the record format being processed when an exception/error occurred.

*PROC

Name of the program or procedure being run.

*STATUS

Program status (error code).

44 – 80

Functions

Keywords

Not used.

Special INFDS Data Structure Subfields

Special values represent built-in positions that contain common values. They are part of the file information input/output feedback data structure (INFDS). The INFDS is used to store information about a file being processed. Each file declared in the program can have its own INFDS. The definition specification shown in Figure 2.5 is the basis for this type of definition specification. Note that, although the function area is documented as part of this specification, no keywords are available to extend the properties of these fields. See Table 2.10.

Table 2.10: Definition Specification Special INFDS Data Structure Subfields Summary

Column

Title

Values

Description

26 – 39

Special position

*FILE

File being processed; the external name for the opened file.

*INP

A two-digit numeric field containing the DBCS indicator. A value of 0 indicates that a non-DBCS keyboard is being used. A value of 10 indicates that a Katakana or DBCS keyboard is being used.

This value applies to WORKSTN device files only.

*OUT

A two-digit numeric field containing the output DBCS indicator. A value of 0 indicates that a non-DBCS output device is being used. A value of 10 indicates that a Katakana or DBCS output is being used.

This value applies to WORKSTN device files only.

*OPCODE

A six-position field containing the RPG operation being performed when an exception/error occurs. The sixth position of this field contains one of the following status flags:

F

The operation was performed on a file name.

R

The operation was performed on a record format.

I

The operation was an implicit file name.

For example, the CHAIN operation appears as CHAINR (Chain to a Record Format).

Note that operation names that appear in this location are RPG III operation names and not RPG IV operation names. This is for compatibility with RPG III compilers. See The Modern RPG Language, 4th Edition by Robert Cozzi, Jr., Midrange Computing, 1996, for a description of RPG III operations.

*MODE

A two-digit numeric field that indicates the type of session. A value of 0 indicates a non-DBCS session. A value of 10 indicates that this is a DBCS session.

This value applies to WORKSTN device files only.

*RECORD

For externally described files, this 8-byte character field contains the name of the record format being processed when an exception/error occurred. For program-described files, the record-identifying indicator of the record just processed is placed, left-adjusted, into the field.

*ROUTINE

An eight-position character field containing the name of the RPG cycle routine running when an exception/error occurred. This field will contain one of the following routines:

*INIT=program initialization

*DETL=detail-time output

*GETIN=get-in

*TOTC=total-time calculations

*TOTL=total-time output

*DETC=detail calculations

*OFL=overflow output

*TERM=program termination.

*SIZE

If the exception error occurs during another program—as is normally the case when a SPECIAL file is being processed—this field will contain the first eight characters of that program name.

*STATUS

A four-digit numeric field containing the number of characters that can be sent to the display device in its current mode.

File status (error code).

44 – 80

Not used.

Definition Specification Keywords

Table 2.11 summarizes the definition specification keywords.

Table 2.11: Definition Specification Keyword Summary.

Keyword

Parameters

Description

ALIGN

Forces data structure subfield alignment on either a 2-, 4-, 8-, or 16-byte boundary. Use this keyword on the data structure definition (not subfield definition).

Only the following subfields are aligned:

  • Pointer fields

  • Length notation fields without overlay

ALT

Array name

The name of an alternate table or array name. This keyword is valid for definitions of arrays or tables.

ALTSEQ

*NONE

Turns off alternate collating sequence for the specified field.

ASCEND

The array or table data is in ascending sequence.

BASED

Pointer variable

Identifies a pointer variable that holds the address (memory location) of variable being defined. The variable being defined can access the data stored at the memory address contained in the pointer variable. No storage is allocated for a based variable.

CCSID

0 to 65535

*DFT

Identifies the CCSID for double-byte character set data (G data-type) and UCS-2 data (C data-type) fields.

CLASS

*JAVA : class-name

Used with the O (object) data-type to declare an instance of a Java language class.

CONST

Literal value

A quoted character string, an expression, or a numeric value can be specified. The length of a constant value can be up to 1024 positions.

For procedure parameters, the value being passed is constant; that is, it is considered read-only and is not changed by the called procedure. CONST parameters can be any value, including literal values or expressions.

CTDATA

Identifies the table or array as a compile-time data table or array. The data for the table or array is stored near the bottom of the source module and is identified by the **CTDATA array/table identifier.

DATFMT

Format [separator]

Specifies the format to use for the date field being defined.

If this keyword is not specified, the date format is based on the DATFMT keyword specified on the header specification.

The separator can be any valid separator character.

DESCEND

The table or array data is in descending sequence.

DIM

Elements

Identifies the number of elements in the table or array. Up to 32767 elements are allowed per table or array.

Occurrences

When DIM is used with a data structure, the data structure's occurrences are specified as array elements. The data structures occurrences may be referred to using traditional array syntax. For example, myDS(7) refers to the 7 occurrence of the data structure named MYDS.

If a subfield of a data structure is also a data structure, and that subfield data structure contains the dim keyword, the qualified name syntax must be used to access the occurrences, for example:

  • myDs(7).subfield(3)

This accesses the third occurrence of the subfield in the seventh occurrence of the higher level data structure. This is referred to as complex data structures.

DTAARA

[ Data area name ]

*VAR : data-area-name

Associates a variable (data structure, data area data structure, or field) with the data area name. If the data area name is not specified, the name of the variable is issued as the data area name.

The data area name must be unquoted. If a field name is needed, it must be specified as the second parameter of the DTAARA keyword.

When the data area name is to be specified within a field, it must be specified as the second parameter. In addition, the first parameter must contain the value *VAR. The data structure name can be qualified to a library name or *LIBL, or it can be unqualified. The data structure and library name must be specified in all uppercase characters.

EXPORT

'Export name'

The variable (field or data structure) is available to other program modules linked (i.e., bound) into this module. Those other modules can use the IMPORT keyword to access the data for this variable.

The export name value is the name used to export the variable. This is the name that is referred to when importing the variable.

This provides an alternative to parameters when calling procedures. See IMPORT.

EXTFLD

External field name

The external field name is renamed to the name specified in the name entry of this line. The EXTFLD keyword is functionally equivalent to the DDS RENAME keyword. If the PREFIX keyword is used, the prefix value is not applied to a field with the EXTFLD keyword.

EXTFMT

External format code

Identifies the external data-type (format) of data loaded into pre-runtime arrays and tables.

Valid format codes include the following:

Format Description

B

RPG binary.

C

UCS-2 format data.

I

Signed integer.

L

Zoned numeric with left-side sign.

R

Zoned numeric with right-side sign.

P

Packed decimal.

S

Zoned numeric.

U

Unsigned integer.

F

Floating point

EXTNAME

File name { : format { : field selection }}

For externally described data structures, the name of the file and, optionally, the format name used to generate the data structure format.

The third parameter is optional and indicates which fields from the record format are included. If no field selection is specified, only the input fields are included. The valid choices for the field selection parameter include the following:

*ALL - All fields are included.

*INPUT - Only the input fields are included.

*OUTPUT - Only the output fields are included.

*KEY - Only the key fields from the file are included.

Note that if the file containing the record format includes the PREFIX keyword, then the subfields will also include that prefix.

EXTPGM

'External program name'

The name of the program being prototyped.

The external program name is the name of the program that is being prototyped. If no name is specified, the name in positions 7 to 21 is used as the name of the program.

EXTPROC

'External procedure name'

The name of the procedure being prototyped. A quoted character literal, a named constant, or a procedure pointer can be specified as the external program name.

If neither EXTPROC nor EXTPGM is specified, the name of the prototype (positions 7 to 21) is used as the procedure name.

See PROCPTR keyword.

*JAVA : class-name :

method

Used to declare a prototype to evoke a method in a Java class object.

*CL : procedure-name

Used to declare a prototype that receives a return value that uses the CL language parameter standards. Also used when declaring an RPG procedure that is to be called by CL.

*Cwiden : procedure-name

Used to prototype a procedure written in the C language. Causes parameters passed by value to be widened to the standard C language conventions.

*Cnowiden : procedure-name

Used to prototype a procedure written in the C language that includes the following C directive:

  • #pragma argument(procedure-name,nowiden)

FROMFILE

File name

The name of the database file whose data will be used to load the pre-runtime array or table.

IMPORT

'External name'

The memory for the variable (field or data structure) is allocated in another program module. The data can be accessed from this program module.

The definition of the variable should match that of the variable defined with the EXPORT keyword in the other program module.

INZ

Initial value

*EXTDFT

*USER

*SYS

*JOB

*LIKEDS

The initial value for the variable. The value must be a quoted character string, a numeric literal, a named constant, or an expression that can be analyzed at compile time.

The *EXTDFT option can be used for fields specified for an externally described data structure. Specify INZ(*EXTDFT), on the data structure header, to initialize all subfields to the value specified for the DFT keyword in the DDS for the file. Specify INZ(*EXTDFT) on the individual subfield to initialize the subfield itself.

INZ(*SYS) and INZ(*JOB) initialize date, time, or time-stamp variables to the current system or job value, respectively.

*USER initializes a character field to the user profile ID for the job running the program.

*LIKEDS initializes the fields of a data structure that was previously defined using the LIKEDS keyword. The initial values used are the same as those in the data structure specified on the LIKEDS keyword.

LIKE

Referenced variable

Use this keyword to assign the attribute of the based-on variable to the new variable. Only the size, decimal positions (if any), and data-type are inherited. The initial value is not.

If the based-on variable is the name of a procedure prototype, the new field inherits the same properties as the prototype's return value.

If the based-on variable is an array, only the properties of the based-on array's elements are inherited. To also inherit the number of elements from the original array, specify the DIM keyword with the %ELEM built-in function, as follows:

LIKEDS

Data structure name

Declares a new data structure with the same format as its based-on data structure.

All the fields from the original data structure are included in the new data structure. In addition, data structures that include the LIKEDS keyword, also automatically include the QUALIFIED keyword, and thus must only be refered to using the qualified data structure syntax of ds.subfield.

When the LIKEDS keyword is used, the initial values for the subfields of the new data structure do not inherit the original data structure's initialization. Therefore in order to initialize the new data structure to match the based-on data structure, the INZ(*LIKEDS) keyword option must also be used.

LIKEREC

Record : field selection

Declares a data structure whose subfields have the same names and attributes of those specified in the record format name specified on the first parameter.

The second parameter is optional and indicates which fields from the record format are included. If no second parameter is specified, then all fields are included. The valid choices for the second parameter include the following:

*ALL - All fields are included.

*INPUT - Only the input fields are included.

*OUTPUT - Only the output fields are included.

*KEY - Only the key fields from the file are included.

Note that if the file containing the record format includes the PREFIX keyword, then the subfields will also include that prefix.

NOOPT

Prohibits optimization of the variable. Functionally similar to the VOLITILE keyword in the C language, it ensures that the content of the variable is the most current assigned value.

When calling an older version of RPG using a program prototype, specify the NOOPT keyword for each parameter. Older versions of RPG are implicitly defined with NOOPT. This ensures that parameters are passed correctly.

In addition, any variables used in the *PSSR or other error routines should also include NOOPT in their definition.

OCCURS

Occurrences

The number of occurrences for the multiple occurrence data structure. For named data structures, the maximum occurrences is 32767. For unnamed data structures, the maximum is 9999999.

OPDESC

Operational descriptors are passed with the parameters. Use this keyword on the procedure prototype and the procedure interface statements.

OPTIONS

[ opt1 : opt2 : opt3 : opt4 :

opt5 ]

Parameter passing options. On a prototype or parameter list, use the OPTIONS keyword on any of the parameters that require special consideration.

*NOPASS

The parameter is optional. It doesn't have to be specified when the procedure is called by the CALLP operation or as a function. All subsequent parameters for this prototype must also contain OPTIONS(*NOPASS).

*OMIT

The *OMIT option is allowed for the parameter. Use *OMIT in place of a parameter value when the procedure is called.

*RIGHTADJ

For CONST or VALUE parameters the value specified for the parameter is passed right-justified.

*STRING

The value is converted into a null-terminated string and then a pointer reference to that string is passed to the called procedure. This is valid for parameter of type pointer.

*VARSIZE

The character, array, or graphic parameter value can be shorter than the length defined in the prototype for the parameter. If *VARSIZE is not specified, the value passed must be at least the length of the parameter length.

The CEEDOD API can be used to retrieve the length of the parameters passed, provided the OPDESC keyword is also specified for the prototype. Optionally, by specifying that the parameter is VARYING, the %LEN built-in function can be used to retrieve the length of the character value passed as the parameter. See CONST.

OVERLAY

Subfield [ : nStart | *NEXT ]

The subfield being defined is located at nStart of the overlaid subfield or data structure name.

If *NEXT is specified, the field appears in the data structure in the next available position within the overlaid variable.

PACKEVEN

Causes a packed decimal field to be packed with an even number of digits. The decimal precision will be an even number of digits, such as, 2, 4, 6, 8, and so on.

If this keyword is not specified, the field is packed with an odd number of digits, such as: 3, 5, 7, 9, 11, and so on.

Use this keyword only when using from and to notation.

PERRCD

Entries per record

The number of elements per record for a compile-time or pre-runtime array. The default value for this keyword is 1.

PREFIX

Prefix [: replace count ]

For externally described files, the prefix is used to automatically rename all fields in the file. The prefix is appended to the front of the field name for each field in the file's record format. If the prefix value is enclosed in quotes, the value must be in all uppercase letters. The PREFIX value cannot contain a period.

The replace-count controls whether or not the first replace-count characters of each field name are trimmed from the field name before the automatic rename occurs. For example, if all the fields in the file begin with cst, as in cstnam, cstnbr, and cstadr, the prefix keyword's replace-count can be used to remove the leading three characters from each field.

In this case, a prefix keyword specified as

prefix('cm_' : 3) will rename the above fields, as follows:

cm_nam, cm_nbr, cm_adr

PROCPTR

This keyword is used to indicate that a field of type pointer (*) is being declared as a procedure pointer.

QUALIFIED

This keyword causes the data structure to be required to be referred to using the qualified data structure syntax. Traditionally, data structure subfields can be specified individually. When the QUALIFIED keyword is used, subfields must be referred to using the qualified syntax as follows:

  • myDS.subfield

Subfields of qualified data structures may not be referred to by their names alone. This allows two different data structures to contain a subfield with the same name.

Note that the QUALIFIED keyword is implied when when LIKEDS and LIKEREC keywords are used to declare the data structure.

STATIC

The data item is stored in static storage. Items stored in static storage are retained until the program is terminated. All global data items are static. Data items within a subprocedure are, by default, stored in automatic storage. Automatic storage is initialized each time a subprocedure is called and released when the subprocedure ends.

Because subprocedures can be called recursively, consideration should be given as to whether a data item should be left in automatic storage, as each invocation of a procedure allocates its own copy of all automatic data items.

TIMFMT

Format [ : separator ]

Specifies the format for time fields. If this keyword is not specified, the *ISO format (hh.mm.ss 24 hour clock) is used.

The separator can be any separator and defaults to the slash (/).

TOFILE

File name

Identifies the output file for a pre-runtime array or table. The data from the array is written to this file when the program ends. The file must be defined on the file description specifications as a combined file, and must have a file designation of T (table).

VALUE

For procedure prototype parameters. Causes the parameter to be passed "by value" instead of the system-wide default of "by reference." The system makes a copy of the parameter value and passes a reference to that copy to the called procedure.

VARYING

The character field (data-type A) is a variable length field. The length of the field is the maximum length that can be accessed for the field. Use the %LEN built-in function to set and retrieve the length of variable length fields. The actual length of a VARYING field is stored as a two-byte binary (10i0) value. That value is hidden from the RPG program and is stored in the first type bytes of the storage allocated for the field. The physical length of the field is two bytes longer than that declared length.




The Modern RPG IV Language
The Modern RPG IV Language
ISBN: 1583470646
EAN: 2147483647
Year: 2003
Pages: 156
Authors: Robert Cozzi

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net