Create Program (QPRCRTPG) API

The Create Program (QPRCRTPG) API converts the symbolic representation of a machine interface (MI) program into an OPM program object. This symbolic representation is known as the intermediate representation of a program.

The QPRCRTPG API creates a program object that resides in the *USER domain and runs in the *USER state. If you want the program object to be temporary, you must do one of the following:

• Delete the object when you no longer need it.
• Create the object in the QTEMP library, and let the system delete the object automatically when the job ends.

You can specify program objects created with the QPRCRTPG API in CL commands that process objects of type *PGM. For example, you can:

• Save and restore program objects using the Save Object (SAVOBJ) and Restore Object (RSTOBJ) commands.
• Delete program objects using the Delete Program (DLTPGM) command.
• Run program objects using the Call (CALL) command.
• Rename program objects using the Rename Object (RNMOBJ) command.
• Move program objects to a different library using the Move Object (MOVOBJ) command.

Note: MI instructions that reference system-domain or write-protected objects fail at security levels 40 and 50. At those levels, you must use APIs to work with the objects.

Authorities and Locks

Program Authority

*ALL. Required only if the program already exists and the option value *REPLACE is specified.

Program Library Authority

*CHANGE

Printer File Authority

*USE

Printer File Library Authority

*USE

Source File Authority

*USE

Source File Library Authority

*USE

Required Parameter Group

Intermediate representation of the program

INPUT; CHAR(*)

A string containing the intermediate representation of the program to be processed by the QPRCRTPG API. See Program Syntax.

Length of intermediate representation of program

INPUT; BINARY(4)

The size, in bytes, of the intermediate representation of the program.

Qualified program name

INPUT; CHAR(20)

The name and library of the program to be created or replaced. The first 10 characters contain the program name, and the second 10 characters contain the name of the library where the program is located. The special value *CURLIB may be used for the library name.

Program text

INPUT; CHAR(50)

Text that briefly describes the program.

Qualified source file name

INPUT; CHAR(20)

The name and library containing the source program. The first 10 characters contain the source file name, and the second 10 characters contain the name of the library where the file is located. This places the value in the program object's service description. The special value *NONE may be used for the source file name. If you specify *NONE, no source file information is placed in the program object's service description. A special value, such as *LIBL, is not valid for the source file library.

Source file member information

INPUT; CHAR(10)

The file member containing the source program. This places the value in the program object's service description.

This value must be blanks if you specify *NONE as the source file name.

Source file last changed date and time information

INPUT; CHAR(13)

The date and time the member of the source file was last updated. The format of this field is in the CYYMMDDHHMMSS format, where:

C	Century, where 0 indicates years 19xx and 1 indicates years 20xx.
YY	Year
MM	Month
DD	Day
HH	Hour
MM	Minute
SS	Second

This places the value in the program object's service description.

This value must be blank if you specify *NONE for the source file name parameter.

Qualified printer file name

INPUT; CHAR(20)

The name and library containing the printer file used to generate listings. The first 10 characters contain the printer file name, and the second 10 characters contain the name of the library where the file is located. The only special values supported for the library name are *LIBL and *CURLIB.

This value is ignored if you specify *NOLIST for the generate listing option (see Values for the Option Template Parameter).

Starting page number

INPUT; BINARY(4)

The first page number to be used on listings. This value should be between 1 and 9999; otherwise, the API uses 1.

This value is ignored if you specify *NOLIST for the generate listing option (see Values for the Option Template Parameter).

Public authority

INPUT; CHAR(10)

The authority you give the users who do not have specific private authorities to the object, and where the user's group has no specific authority to the object.

The values allowed are:

*CHANGE

*ALL

*USE

*EXCLUDE

The name of an authorization list

Option template

INPUT; CHAR(*)

This is an array of options. You can specify between 0 and 17 values. Each entry contains a CHAR(11) value as described in Values for the Option Template Parameter.

Number of option template entries

INPUT; BINARY(4)

The number of option template entries.

The value must be between 0 and 17.

Optional Parameter

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.

Values for the Option Template Parameter

When you are using the QPRCRTPG API, you can specify a value in the option template. Only one value per option should be specified. If you specify more than one, the system only uses the first one. If you specify no value for a given option, the system uses the default value (underlined).

Create program object

Creates a program object.

The values allowed are:

*GEN	Generates a program and places the program in the appropriate library.
*NOGEN	No program is generated. The syntax of the intermediate representation of the program is checked, and if the generate listing option is *LIST, a listing is produced.

Replace program

Replaces the existing program if a program by the same name already exists in the specified library.

The values allowed are:

*NOREPLACE	Does not replace an existing program by the same name in the specified library.
*REPLACE	Replaces the existing program by moving it to the QRPLOBJ library.

Generate listing

Generates an output listing.

The values allowed are:

*NOLIST	Does not generate a listing.
*LIST	Generates a listing. You must specify the following parameters: Printer file name and library Starting page number

Create cross-reference listing

Whether the listing is to contain a cross-reference list of variable and data item references.

The values allowed are:

*NOXREF	Does not create cross-reference listing.
*XREF	Creates a cross-reference listing of references to variables, labels, or both.

Create summary listing

Whether the listing is to contain a list of program attributes.

The values allowed are:

*NOATR	Does not create a summary listing section.
*ATR	Creates a summary listing section.

User profile

The values allowed are:

*USER	The user profile of the user running the program is used as a source of authority when this program runs.
*ADOPT	When the program runs, the object authority of both the program's owner and user are used.
*OWNER	The system uses the user profile of the owner of the program as a source of authority when this program runs. Programs called by this program adopt this authority.

Use adopted authority

Whether the system uses the program-adopted authority from the calling programs as a source of authority when this program is running. The user must be authorized to create programs with adopted authority for the *ADPAUT option to take effect.

The values allowed are:

*ADPAUT	The system uses program-adopted authority from the calling program.
*NOADPAUT	The system does not use program-adopted authority from the calling program.

Note: Authorization to create programs which can adopt authority is controlled by the QUSEADPAUT system value. For more information, refer to the description of this system value in the Work management topic collection.

Constrain arrays

The values allowed are:

*SUBSCR	Constrains arrays. This requests additional run-time checks to ensure that references to array elements are not outside the bounds of the declare statement. This option causes the resulting program to run slower.
*NOSUBSCR	Does not constrain arrays. The results of references to array elements outside the bounds of the declare statement are not defined.
*UNCON	Allows fully unconstrained arrays. This ensures that references to array elements outside the bounds of the declare statement act as if the array element actually exists.

Note: This program attribute may be changed at run-time using the Override Program Attributes (OVRPGATR) MI instruction.

Constrain strings

The values allowed are:

*SUBSTR	Constrains strings. This requests additional run-time checks to ensure that references to character strings are not outside the bounds of the declare statement. This option causes the resulting program to run slower.
*NOSUBSTR	Does not constrain strings. The results of substring references outside the bounds of the declare statement are not defined.

Note: You can change this program attribute at run-time using the Override Program Attributes (OVRPGATR) MI instruction.

Initialize static storage

Static storage is allocated the first time a program is called. It remains allocated until explicitly deallocated.

The values allowed are:

*CLRPSSA	Initializes static storage. This code clears the program static storage area (PSSA) on entry using the Call External (CALLX) MI instruction.
*NOCLRPSSA	Does not initialize the PSSA.

Initialize automatic storage

Automatic storage is allocated each time a program runs and automatically deallocated when no longer needed.

The values allowed are:

*CLRPASA	Initializes automatic storage. This code clears the program automatic storage area (PASA) on entry using the Call External (CALLX) MI instruction.
*NOCLRPASA	Does not initialize the PASA.

Ignore decimal data errors

Whether errors found in decimal data result in exceptions.

The values allowed are:

*NOIGNDEC	Does not ignore decimal data errors. When you specify *NOIGNDEC, decimal values used in numeric operations are checked for valid decimal digits and sign codes. If the system finds an error, it signals an exception.
*IGNDEC	Ignores data decimal errors. When you specify *IGNDEC, decimal values used in numeric operations ensure they contain valid decimal digit and sign codes. However, the system treats digits that are not valid as zeros and signs that are not valid as positive signs. There is no exception signaled.

This option applies to only a subset of the numeric operations you specify.

Note: In all cases, the system signals decimal data errors if you use data pointers to address any of the instruction's operands.

The following list contains the MI instructions this option affects:

MI Instruction	Packed Source Operands Supported	Zoned Source Operands Supported	Notes
ADDN		X
CMPNV		X
CVTCN	X	X	You must specify operand 3 (the numeric view to be used for operand 2) as a constant and no data-pointer-defined operands.
CVTDFFP		X
CVTNC	X	X	You must specify operand 3 (the numeric view to be used for operand 1) as a constant and no data-pointer-defined operands.
CPYNV	X	X	You must specify no data-pointer-defined operands.
DIV		X
DIVREM		X
EDIT		X	You must specify no data-pointer-defined operands.
EXTRMAG		X
MULT		X
NEG		X
REM		X
SCALE		X
SUBN		X

When you specify *IGNDEC, the system may still signal the decimal data exception. That is, other MI instructions and instruction combinations not listed above may signal the decimal data exception when the system finds decimal data that is bad.

Ignore binary data size errors

The values allowed are:

*NOIGNBIN	The system handles binary data size errors normally. When a binary size error occurs, an exception is signaled and the receiver contains the left-truncated result.
*IGNBIN	The system ignores binary data size errors. This is used when an overflow or underflow occurs on a computation and when a control MI instruction has a receiver that is a binary field. The receiver contains the left-truncated result.

Support coincident operands

The system overlaps coincident operands between the source and receiver operands in one or more program instructions. Coincident operands are operands that overlap physically, in storage.

The values allowed are:

*NOOVERLAP

Does not support coincident operands. If you specify *NOOVERLAP, you guarantee that coincident operand overlap will not occur while running the instruction. Therefore, the system can use the receiver on an instruction as a work area during operations performed to produce the final result. Using the receiver as a work area does not use as much processor resource as would be required to move the final result from an internal work area to the receiver.

*OVERLAP

Supports coincident operands. If you specify *OVERLAP, the operands on an MI instruction may overlap. Therefore, the system cannot use the receiver on an instruction as a work area during operations that produce the final result. This can require more processor resource for running the instruction but it ensures valid results if an overlap occurs.

The following is a list of instructions this option affects:

• Add logical character (ADDLC)
• Add numeric (ADDN)
• And (AND)
• Compute math function using one input value (CMF1)
• Concatenate (CAT)
• Convert character to numeric (CVTCN)
• Convert decimal form to floating-point (CVTDFFP)
• Convert external form to numeric value (CVTEFN)
• Convert floating-point to decimal form (CVTFPDF)
• Convert numeric to character (CVTNC)
• Copy bytes left adjusted with pad (CPYBLAP)
• Copy bytes right adjusted with pad (CPYBRAP)
• Divide (DIV)
• Divide with remainder (DIVREM)
• Exclusive or (XOR)
• Multiply (MULT)
• Or (OR)
• Remainder (REM)
• Scale (SCALE)
• Subtract logical character (SUBLC)
• Subtract numeric (SUBN)
• Trim length (TRIML)

Allow duplicate declares

The values allowed are:

*NODUP	This does not allow a program object to be declared more than once. This requests that duplicate declare (DCL) statements be diagnosed as errors.
*DUP	This allows a program object to be declared more than once. This requests that program objects declared more than once be pooled and not be diagnosed as errors.

Optimize

The values allowed are:

*OPT	This optimizes the program. In most instances, this produces the smallest and best running program. Occasionally, the source program may signal a MCH2802 escape message during processing. If this occurs, you should not optimize the program.
*NOOPT	This does not optimize the program. This requests the normal level code optimization when you create the program.

Target release

The release of the operating system on which you intend to use the object being created. You can use the object on a system with the specified release or with any subsequent release of the operating system installed.

The values allowed are:

*CURRENT	The object is to be used on the release of the operating system currently running on your system.
*PRV	The object is to be used on the previous release with modification level 0 of the operating system.
target-release	Specify the release in the format VxRxMx.

Error Messages

Program Attributes

The QPRCRTPG API creates programs that have the following attributes:

• An associated space of 480 bytes initialized to hexadecimal 00. You can use the QCLSPGAS API to store information in the program's associated space.
• Observability.
• A blank extended attribute.

Program Syntax

A program object consists of an instruction stream and an object definition table (ODT). The intermediate representation of a program defines both of these components. It consists of one or more statements:

Instruction statements define MI instructions placed in the instruction stream. Declare statements define program objects placed in the ODT. Directive statements:

• Control the formatting of the output listing.
• Define entry-point program objects.
• Define symbolic breakpoints.
• Specify the end of the program.

The following sections explain how to define these statements.

Note: In the diagrams below, names that begin with an uppercase letter identify values specified in another diagram. Names that begin with a lowercase letter identify values defined in the table below the diagram.

Label

The following diagram and table show the possible labels:

Each name specified in the label generates a branch-point program object corresponding to the next MI instruction.

Declare Statement

Declare statements define program data objects. All the declare statements in a program build the object definition table (ODT).

You cannot specifically declare branch and entry-point program objects. However, you can declare branch-point program objects using labels. You can also declare entry-point program objects using the entry directive statement.

The types of declare statements follow:

• Scalar Data Object Declare Statement
• Pointer Data Object Declare Statement
• Space Pointer Machine Object Declare Statement
• Operand List Declare Statement
• Instruction Definition List Declare Statement
• Exception Description Declare Statement
• Space Object Declare Statement
• Constant Object Declare Statement

Scalar-Data-Object Declare Statement

The following diagram and table show the scalar-data-object declare statement:

Only certain combinations of attributes are allowed based on the data object's addressability. The table below shows these combinations.

Object Name

The following diagram and table show the possible object names:

Array Attribute

The following diagram and table show the possible array attributes:

Example

The following declare statements each define an array of 50 elements. The elements of ARRAY1 are numbered 1 to 50. The elements of ARRAY2 are numbered 0 to 49. Each element of the array is a BIN(2) field. The addressability of the arrays is static.

DCL DD ARRAY1(50) BIN(2);
DCL DD ARRAY2(0:49) BIN(2);

Scalar Type

The following diagram and tables show the possible data types of scalar items:

If you specify no value, the system uses BIN(2).

Addressability

The following diagram and tables show the possible addressabilities:

If you specify no value, the system uses STAT.

Scope

Scope refers to the ability to export a variable so that other programs can access it. The following diagram and table show the possible scopes:

If you specify no value, the system uses INT.

Boundary

The following diagram and table show the possible boundaries:

Position

The following diagram and table show the possible positions:

Example

The following declare statements show how POS can be used along with DEF to access the same storage space in different ways:

DCL DD DATETIME CHAR(12);
DCL DD DATE CHAR(6) DEF(DATETIME);
DCL DD TIME CHAR(6) DEF(DATETIME) POS(7);

DATETIME represents a 12 character time and date stamp. The first 6 characters contain the date and the second 6 characters contain the time.

Array Element Offset

The following diagram and table show the possible array element offsets:

Example

The following example shows AEO used in conjunction with DEF and POS:

DCL DD X CHAR(16);
DCL DD LFT(4) BIN(2) DEF(X) AEO(4) POS(1);
DCL DD RGT(4) BIN(2) DEF(X) AEO(4) POS(3);

Both LFT and RGT redefine the storage declared by X. Because the size of each array element is smaller than the array element offset, there are 2-byte gaps between each array element:

Optimization

Optimization determines whether or not an item can be moved to a register and stored there over time. The following diagram shows the possible optimization:

This value indicates that the data object contains an abnormal value. You cannot optimize the value for more than a single reference because the value may be changed in a manner that the QPRCRTPG API cannot detect.

Initial Value

The following diagram and table show each possible initial value:

Example

The following declare statement declares and initializes a 10-element array:

DCL DD IV(10) BIN(2) STAT INIT((1)10,*(2)(2)11,*(4)(3)12,*(7)(4)13);

There are four initial value elements. The following table describes this function:

IV(2)=11
IV(3)=11

IV(4)=12
IV(5)=12
IV(6)=12

IV(7)=13
IV(8)=13
IV(9)=13
IV(10)=13

Pointer-Data-Object Declare Statement

The following diagram and table show the pointer-data-object declare statement:

The system only allows certain combinations of attributes based on the data object's addressability. These combinations are listed as follows:

Pointer Type

The following diagram and table show the possible pointer types:

If you specify an initial value, you must specify INSPTR, SPCPTR, DTAPTR or SYSPTR.

Array Attribute

The following diagram and table show the possible array attributes:

Addressability

The following diagram and tables show the possible addressabilities:

Position

The following diagram and table show the possible positions:

Array Element Offset Value

The following diagram and table show the possible array element offset values:

Optimization

The following diagram shows the possible optimizations:

This value indicates that the data object contains an abnormal value. The system cannot optimize a value for more than a single reference because the value may be changed in a manner the QPRCRTPG API cannot find.

Initial Value

The following diagram shows each possible initial value:

An initial value can only be specified if a pointer-type value other than PTR is specified. The syntax of the initial value is based on the pointer-type value that was used.

Instruction Pointer Initial Value

The following diagram and table show the possible initial value for the instruction pointer:

Example

The following statement declares and initializes an instruction pointer:

LABELI:

  :
  :

  DCL INSPTR INSTRUCTION_PTR INIT(LABELI);

Space Pointer Initial Value

The following diagram and table show the initial value for the space pointer:

Example

The following statement declares and initializes a space pointer:

DCL PTR ANY_POINTER;
DCL SPCPTR SPACE_PTR INIT(ANY_POINTER);

The pointer SPACE_PTR is initialized to point to the space location containing ANY_POINTER. It does not contain the value of ANY_POINTER.

Data Pointer Initial Value

The following diagram and table show the initial value for the data pointer:

Example

The following statement declares and initializes a data pointer:

DCL DTAPTR DVALUE INIT("DBINARY",PGM("DPGM"));

The pointer DTAPTR refers to the externally defined program object DBINARY contained in program DPGM.

System Pointer Initial Value

The following diagram and tables show the initial value for the system pointer:

The following system object types are supported:

Example

The following statement declares and initializes a system pointer:

DCL SYSPTR SYSTEM_PTR INIT("MYPGM",CTX("PGMLIB"),TYPE(PGM));

The pointer SYSTEM_PTR refers to the *PGM object MYPGM in the PGMLIB library.

Space-Pointer-Machine-Object Declare Statement

The following diagram and table show the space-pointer-machine-object declare statement:

The system provides two types of pointers that can access data:

• Space Pointers (SPCPTR)
• Machine Space Pointers (MSPPTR)

  The MSPPTR has the following restrictions:

  • It cannot be passed as a parameter
  • It cannot be part of a structure (SPC)
  • It cannot be based (BAS(on_some_pointer)) pointer
  • It is logically only automatic (AUTO) in storage scope

Because the MSPPTR has the above restrictions, the translator often assigns the MSPPTR to a hardware register for the life of the entire program unit. What this means is that loads may be eliminated from the generated code.

Operand-List Declare Statement

The following diagram and tables show the operand-list declare statement:

Example

The following statements declare both argument and parameter operand lists along with the associated argument and parameter data objects:

DCL DD ARG1 BIN(2);
DCL DD ARG2 CHAR(3);
DCL OL ARGUMENT_LIST (ARG1, ARG2) ARG;

DCL DD PARM1 BIN(2) PARM;
DCL DD PARM2 CHAR(3) PARM;
DCL OL PARAMETER_LIST (PARM1, PARM2) PARM EXT;

A parameter operand list that refers to the data objects has parameter (PARM) addressability.

Instruction-Definition-List Declare Statement

The following diagram and table show the instruction-definition-list declare statement:

Example

The following statements declare and use an instruction definition list:

LABEL1:

  :
  :

  DCL IDL INSTRUCTION_LIST (LABEL1,LABEL2,LABEL3);

  :
  :

LABEL2:
  B INSTRUCTION_LIST(3); /* Branch to LABEL3 */

  :
  :

LABEL3:

Exception-Description Declare Statement

The following diagram and tables show the exception-description declare statement:

Space-Object Declare Statement

The following diagram and tables show the space-object declare statement:

For information on using space objects, refer to Using Space Objects.

Constant-Object Declare Statement

The following diagram and tables show the constant-object declare statement:

If you do not specify a scalar type, the system uses BIN(2).

Instruction Statement

An instruction statement defines an MI instruction. The instruction stream used to create the program is made up of all the instruction statements in the intermediate representation of the program.

For the semantic meanings and the syntax restrictions (number and types of operands, optional forms, and so on) for individual MI instructions, see IBM i Machine Interface.

Following the abbreviated instruction name, you can specify the optional forms of certain MI instructions using a string of characters enclosed in parentheses. The following is an example of some of the various combinations possible for a single MI instruction, ADD NUMERIC:

ADDN      A,B,C;               Add numeric (A=B+C)
ADDN(S)   A,B;                 Add numeric short (A=A+B)
ADDN(SR)  A,B;                 Add numeric short and round (A=A+B)
ADDN(SB)  A,B/POS(X),NEG(Y);   Add numeric short and branch  (A=A+B,
                               branch to X if A>0, branch to Y if A<0)
ADDN(RI)  A,B,C/POS(I),NEG(J); Add numeric round and indicator (A=B+C;
                               I='on' if A>0; j='on' if A<0 )

Also note that the order of characters in the optional form string is not significant. Thus, all of the following instructions are both valid and equivalent:

ADDN(SRB)A,B/POS(X);     Add numeric short, round and branch
ADDN(SBR)A,B/POS(X);     Add numeric short, round and branch
ADDN(RSB)A,B/POS(X);     Add numeric short, round and branch

Operand

The following diagram and table show the possible operands:

Variable Operand

The following diagram and table show the possible variable operands:

Relative Branch Target

The following diagram and table show the possible relative branch targets:

Note: You cannot use blanks between either the '

=+

' symbol set and integer1 or the '

=-

' symbol set and integer1. However, a blank must precede the symbol sets.

Example

The following instructions illustrate the use of relative branch targets:

  CPYNV X,0;
  CMPBLA(B) A,'1'/EQ( =+2);
  CPYNV X,1;
: CPYNV Y,X;        /* Destination of relative branch */

Note: A null label is placed in the destination instruction of the relative branch.

Target

The following diagram and table show the possible targets:

The following table shows the branch and indicator keywords:

By adding N to the beginning of the appropriate keyword you can form a not condition. For example, the code for "not equal" is NEQ.

All conditions coded on a particular instruction must be mutually exclusive. All conditions within a group are equivalent, and therefore, only one may be specified. For example, POS (positive) and HI (high) cannot be coded on the same instruction.

The not form of a condition is satisfied by any condition from another group. For example, NEQ (not equal) is satisfied by HI (high), LO (low), or UNOR (unordered). Therefore, you cannot specify NEQ with any of the other three. However, you can use NEQ and EQ (or any other keyword in group 3) together because they are mutually exclusive.

Index

The following diagram and table show the possible indexes:

An index is a numeric value that qualifies an array or substring reference. The context in which the index is used determines the range. For more information, refer to the preceding tables.

Directive Statements

The directive statements are as follows:

• Title Directive Statement
• Space Directive Statement
• Eject Directive Statement
• Break Directive Statement
• Entry Directive Statement
• Reset Directive Statement
• Program End Directive Statement

Title Directive Statement

The title directive statement causes a heading to appear on the listings. Only one title directive statement may be specified in a program. The following diagram and table show the title directive statement:

Space Directive Statement

The space directive statement causes a blank line to appear in the listing. The following diagram and table show the space directive statement:

Eject Directive Statement

The eject directive statement causes the next line to appear on a new page. The following diagram shows the eject directive statement:

Break Directive Statement

The break directive statement allows symbolic breakpoints to be defined. The following diagram and table show the break directive statement:

Entry Directive Statement

The following diagram and tables show the entry directive statement:

The default scope is internal (INT).

The entry statement defines entry point program objects. The next instruction number is associated with this entry point. The entry statement is to be the definition point for this object, so the ODT number assigned to this object is the next available ODT number.

Reset Directive Statement

The following diagram shows the reset directive statement:

The specified name is a previously declared space object. The reset statement causes subsequent data object declarations containing the DIR attribute to use the specified space object. The system maintains next byte counts for each space object; these counts are not affected by the reset statement. For more information, see Using Space Objects.

Program End Directive Statement

The following diagram shows the program end directive statement:

This must be the last statement in the program. To ensure comments and strings end before processing the PEND statement, use the following statement:

/*'/*'/*"/*"*/; PEND;;;

Coding Techniques

This section contains additional information for coding the intermediate representation of a program.

Using Declare Statements

Use the following guidelines when using declare statements:

• A declare statement for data objects defined on another data object must occur after the declare statement for the data object on which it is defined.

  Example: The following sets of declare statements are valid:

  DCL DD A CHAR(5);
  DCL DD B CHAR(1) DEF(A);
  
  
  DCL DD A CHAR(5);
  DCL DD X BIN(2);
  DCL PTR P1 AUTO;
  DCL DD B CHAR(1) DEF(A);
  

  Example: The following declare statements are not valid because B is defined on A but is declared before A:

  DCL DD B CHAR(1) DEF(A);
  DCL DD A CHAR(5);
  

  This restriction also applies when there is a chain of dependencies.

  Example: In the figure below, B is defined on A and C is defined on B:

  DCL DD A CHAR(5);
  DCL DD B CHAR(3) DEF(A);
  DCL DD C CHAR(1) DEF(B);
  

  If any object in a chain of definitions, as shown in the previous examples, has an initial value specified, then the following restrictions apply:

  • No object in that chain can have the BAS (based) addressability attribute.
  • The highest level data object in the chain must be either static or automatic.
  • When you initialize the same area twice, the system uses the last value.

  Example: The following declare statements are valid because:

  • The BAS addressability attribute is not used.
  • Data object A (implicitly) has the static addressability attribute.

    DCL DD A CHAR(5);
    DCL DD B CHAR(3) DEF(A) INIT(C'YES');
    DCL DD C CHAR(1) DEF(B);
    

• All declare statements for the objects that make up the elements of an operand list must precede the declare statement for the operand list.
• When a declare statement for an exception description refers to a system pointer, the declare statement for the system pointer must precede the DCL for the exception description.

Using Space Objects

Space objects, when used in conjunction with program objects declared with the DIR attribute, provide a convenient way of declaring structures.

Note: Space objects, as used here, do not refer to IBM i space objects.

When you declare a space object, a scalar data object with a scalar type of CHAR(32767) is created. This object contains the structure to be defined. Associated with this object is a "next byte" count. This value is initially 1 and represents the position where the next structure element will be placed.

Example: Simple Space Objects

After you declare a space object, you can declare one or more scalar or pointer data objects with an addressability attribute of DIR. As a result, the system automatically declares each object with the DEF and POS attributes. The name associated with the DEF attribute is the most recently declared space object. The value associated with the POS attribute is the space object's next byte count. After you declare the object, the system sets the next byte count associated with the space object to the next available position within the structure.

The group of declare statements on the left is equivalent to the group on the right:

DCL SPC X BAS(PTR);        DCL DD X CHAR(32767) BAS(PTR);
DCL DD A CHAR(2) DIR;      DCL DD A CHAR(2) DEF(X) POS(1);
DCL DD B ZND(5,2) DIR;     DCL DD B ZND(5,2) DEF(X) POS(3);
DCL DD C FLT(4) DIR;       DCL DD C FLT(4) DEF(X) POS(8);

Example: Explicit Position Values

Data objects declared with DIR may also have an explicit POS value. The object is defined on the appropriate space object and uses the specified POS value. However, the next byte count is changed only if the POS value causes the count to increase.

The group of declare statements on the left is equivalent to the group on the right:

DCL SPC X BAS(PTR);             DCL DD X CHAR(32767) BAS(PTR);
DCL DD A CHAR(4) DIR;           DCL DD A CHAR(4) DEF(X) POS(1);
DCL DD B CHAR(4) POS(20) DIR;   DCL DD B CHAR(4) DEF(X) POS(20);
DCL DD C CHAR(4) DIR;           DCL DD C CHAR(4) DEF(X) POS(24);
DCL DD D CHAR(4) POS(10) DIR;   DCL DD D CHAR(4) DEF(X) POS(10);
DCL DD E CHAR(4) DIR;           DCL DD E CHAR(4) DEF(X) POS(28);

Example: Explicit Boundary Alignment

When you declare objects with an explicit boundary other than 1, the object is positioned on the next available byte with that boundary. The position of any data object with the direct attribute is the next available byte in the space if no boundary or position is specified. The position of any pointer object with the direct attribute is the next available byte in the space if no position is specified. Space objects are assumed to begin on a 16-byte boundary. You must ensure this condition exists at run-time.

The group of declare statements on the left is equivalent to the group on the right:

DCL SPC X BAS(PTR);           DCL DD X CHAR(32767) BAS(PTR);
DCL DD A CHAR(1) DIR;         DCL DD A CHAR(1) DEF(X) POS(1);
DCL DD B FLT(4) DIR; BDRY(4); DCL DD B FLT(4) DEF(X) POS(5);
DCL PTR C DIR; POS(17);       DCL PTR C DEF(X) POS(17);

Example: Reset Directive Statement

You can use the reset directive statement to change the name of the space object to be used by subsequent declare statements.

The group of declare statements on the left is equivalent to the group on the right:

DCL SPCPTR PTR1;           DCL SPCPTR PTR1;
DCL SPCPTR PTR2;           DCL SPCPTR PTR2;

DCL SPC X BAS(PTR1);       DCL DD X CHAR(32767) BAS(PTR1);
DCL DD A CHAR(2) DIR;      DCL DD A CHAR(2) DEF(X) POS(1);
DCL DD B ZND(5,2) DIR;     DCL DD B ZND(5,2) DEF(X) POS(3);

DCL SPC Y BAS(PTR2);       DCL DD Y CHAR(32767) BAS(PTR2);
DCL DD C CHAR(5) DIR;      DCL DD C CHAR(5) DEF(Y) POS(1);
DCL DD D CHAR(7) DIR;      DCL DD D CHAR(7) DEF(Y) POS(6);

RESET X;
DCL DD E CHAR(3) DIR;      DCL DD E CHAR(3) DEF(X) POS(8);

Constants

This section describes the syntax of constant values.

Integer

Integers define signed and unsigned binary scalar data values. The two forms of integers are decimal and hexadecimal. The decimal form is a sequence of digits optionally preceded by a sign. The hexadecimal form is a string of hexadecimal digits delimited with apostrophes and preceded by an H. Neither form may exceed the 4-byte limit on binary numbers. When the value of the integer is between -4095 and +8191, the QPRCRTPG API converts the integer to an immediate operand where it can.

Example

+123
-1
54788

H'0F0D'
H'0123'
H'5E2D1AB4'

String

Strings define scalar character string data values. The three types of string constants are character form, hexadecimal form, and Hollerith form.

The character form is a delimited string optionally preceded by a C. Apostrophes or double quotation marks may be used for this form. The hexadecimal form is a delimited string of hexadecimal digits preceded by an X. The Hollerith form is a string of bytes preceded by the count of the number of bytes in the string. The syntax is:

< count | string >

The count in the preceding syntax is the number of characters in the string. The QPRCRTPG API ensures that the string contains the right number of characters by checking for the

>

character. No blanks are allowed between

<

and

>

unless they are part of the string. The QPRCRTPG API simply flags the constant as in error if the right corner bracket does not appear in the correct position.

Example

The following groups of strings are equivalent:

'ABCDE'
C'ABCDE'
X'C1C2C3C4C5'
<5|ABCDE>

'TE''ST'
"TE'ST"
X'E3C57DE2E3'
<5|TE'ST>

'/*'
X'615C'
<2|/*>

Packed

Packed constants define packed decimal scalar data values. Packed constants are a string of decimal digits delimited with apostrophes. They can have an embedded decimal point and can be preceded by a sign. P must precede the delimited string. Packed constants have a maximum of 31 significant digits.

Note: You must specify at least one numeric digit.

Example

P'+123.456'
P'1'
P'-1'
P'-123.345345345345'
P'+.00000000000001'

Zoned

Zoned constants define zoned decimal scalar data values. The external representation of zoned constants is the same as that for packed constants except that the preceding character is a Z.

Note: You must specify at least one numeric digit.

Example

Z'+123.456'
Z'1'
Z'-1'
Z'-123.345345345345'
Z'+.00000000000001'

Floating-Point Constants

Floating-point constants define floating-point scalar data values. You must specify whether the constant is a 4-byte (short floating-point) or an 8-byte (long floating-point) value.

There are two ways to represent floating-point values. First, you can specify floating-point constants as a delimited string of decimal digits possibly with an embedded decimal point and optionally preceded by a sign. An F for short floating-point values or an E for long floating-point values must precede the delimited string. An E in the string determines the start of the base 10 exponent. You specify the exponent as signed.

Second, you can specify floating-point constants as a string of hexadecimal digits. The delimited string must be preceded by an XF for short floating-point values or an XE for long floating-point values.

Note: You must specify at least one numeric digit.

Example

Short Floating-Point    Long Floating-Point
Values                  Values


F'0'                    E'0'
F'+12'                  E'+12'
F'-12.21'               E'-12.21'
F'12.34E2'              E'12.34E2'
F'+3.2345678E-02'       E'+3.2345678E-02'

XF'449A4000'            XE'46CE6F37FFBE8722'
XF'40490FD0'            XE'400921F9F01B866E'

Several special values are allowed:

Short Floating-Point   Long Floating-Point
Values                 Values


F'MNAN'                E'MNAN'     Masked Not A Number
F'UNAN'                E'UNAN'     Unmasked Not A Number
F'+INF'                E'+INF'     Plus Infinity
F'-INF'                E'-INF'     Minus Infinity

Note: You must use floating-point constants to initialize floating-point data objects.

Name

Names specified in the intermediate representation of a program are a sequence of characters of up to 48 characters in length. You cannot use the following characters as the first character of the name:

blank /,;():<+'%-0123456789

You cannot use the following characters in subsequent characters of the name:

blank /,;():<+'%

Example

.NAME
NAME
THIS_IS_A_NAME
THIS_IS_A_NAME_2
&NAME
!NAME
?NAME
.0001

Note: Symbols that begin with a period (.) are not inserted into the program's symbol table and may not be referred to by the IBM i debug function.

Comments

Comments, in the intermediate representation of a program, may appear anywhere in the text. Comments are treated as blanks so they are significant in finding tokens. Comments are a string of characters starting with

/*

and ending with

*/

. If a comment occurs immediately following a semicolon, it prints as a separate line (or a multiple line as required) on the listing. If a comment is embedded in a statement, then it appears as a part of that statement, such as a remark.

Example

The following statements are equivalent:

CPYBLA A,B;
CPYBLA A, /* C-> */ B ;
CPYBLA A,B;  /* B is based on C */

Blanks

You can use strings of blanks of any length in the intermediate representation of a program. Blanks act as delimiters in finding tokens and in some places are necessary as in separating the opcode and operand in an instruction statement.

Example

The following statements are equivalent:

ADDN A,B,C;
ADDN        A    ,     B             , C            ;

[ Back to top | Program and CL Command APIs | APIs by category ]