1.8 Create Program (QPRCRTPG) API ________________________________________________________________________ | Required Parameter Group: | | ____ __________________________________________ ________ ___________ | | | 1 | Intermediate representation of the | Input | Char(*) | | | | | program | | | | | |____|__________________________________________|________|___________| | | | 2 | Length of intermediate representation of | Input | Binary(4) | | | | | program | | | | | |____|__________________________________________|________|___________| | | | 3 | Qualified program name | Input | Char(20) | | | |____|__________________________________________|________|___________| | | | 4 | Program text | Input | Char(50) | | | |____|__________________________________________|________|___________| | | | 5 | Qualified source file name | Input | Char(20) | | | |____|__________________________________________|________|___________| | | | 6 | Source file member information | Input | Char(10) | | | |____|__________________________________________|________|___________| | | | 7 | Source file last changed date and time | Input | Char(13) | | | | | information | | | | | |____|__________________________________________|________|___________| | | | 8 | Qualified printer file name | Input | Char(20) | | | |____|__________________________________________|________|___________| | | | 9 | Starting page number | Input | Binary(4) | | | |____|__________________________________________|________|___________| | | | 10 | Public authority | Input | Char(10) | | | |____|__________________________________________|________|___________| | | | 11 | Option template | Input | Char(*) | | | |____|__________________________________________|________|___________| | | | 12 | Number of option template entries | Input | Binary(4) | | | |____|__________________________________________|________|___________| | | | Optional Parameter: | | | |____ __________________________________________ ________ ___________| | | | 13 | Error code | I/O | Char(*) | | | |____|__________________________________________|________|___________| | |________________________________________________________________________| 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. 1.8.2 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" in topic 1.10. 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" in topic 1.8.4). 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" in topic 1.8.4). 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 16 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 16. 1.8.3 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" in the book System API Reference. If this parameter is omitted, diagnostic and escape messages are issued to the application. 1.8.4 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 (MARKED BY '>'). 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 book. 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: _____________ ___________ ___________ __________________________________ | | Packed | Zoned | | | | Source | Source | | | MI | Operands | Operands | | | Instruction | Supported | 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.