CRTCLPGM (Create Control Language Program)

CRTCLPGM Command syntax diagram

 

Purpose

The Create Control Language Program (CRTCLPGM) command creates a CL program from the specified CL source program. The command is valid in batch and interactive jobs, and in both compiled and interpreted CL.

Restriction: The amount of auxiliary storage occupied by a compiled program varies with the number of commands in the program, the kinds of functions performed by the commands (for example: display, create, add, and call), and the kinds of parameter values specified (variables versus constants). Some combinations of these factors can cause the system internal size limits for the program to be exceeded (an unlikely occurrence). When the limits are exceeded, the program must be rewritten, usually as several programs instead of one program.

 

Required Parameters

PGM
Specifies the qualified name of the compiled program.

The name of the program can be qualified by one of the following library values:

*CURLIB: The program is created in the current library for the job. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library where the program is created.

program-name: Specify the name of the program being created.

 

Optional Parameters

SRCFILE
Specifies the qualified name of the source file that contains the CL source program being compiled. The program is known by the name given in the PGM parameter.

The name of the source file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

QCLSRC: The IBM-supplied source file, QCLSRC, that contains the CL source program being compiled is used.

source-file-name: Specify the name of the source file that contains the CL source program being compiled. The source file can be a database file, a device file, or an inline data file.

SRCMBR
Specifies the name of the member of the source file that contains the CL source program being compiled.

*PGM: The CL source program being compiled is in the member of the source file that has the same name as that specified in the PGM parameter for the compiled program.

source-file-member-name: Specify the name of the member that contains the CL source program, if the member name is not the same as the name of the program being created.

OPTION
Specifies the types of output lists created when this command is processed and whether a program is created. Up to five of the following values can be specified in any order on this parameter. If neither or both of the values in each group are specified, the underlined value will be used.

Note: The underlined values for this parameter are similar to, but not actually default values, and therefore, cannot be changed with the CHGCMDDFT (Change Command Default) command.

Source Listing Options

*SRC or *SOURCE: The compiler creates a list of the source input used to compile the program.

*NOSRC or *NOSOURCE: A complete compiler source list is not created; only compiler errors are listed.

Cross-Reference Options

*XREF: A cross-reference listing of the source program is produced.

*NOXREF: No cross-reference list of references to variables and data items in the source is created.

Program Creation Options

*GEN: The compiler creates a program that can run after the program is compiled.

*NOGEN: A program object is not created. The compiler checks only the syntax of the statements.

Second-Level Message Text Options

*NOSECLVL: No second level message text is printed.

*SECLVL: Second-level message text is printed.

Debug Options

*NOSRCDBG: Source-level debug information is not generated. Source-level error information will not be created unless *LSTDBG is specified.

*SRCDBG: The compiler generates source-level error and debug information for use with CoOperative Development Environment/400 (CODE/400). Source-level or listing-level debugging information is also necessary if you want to use the source-level debug function of the system debugger (STRDBG OPMSRC(*YES)) to debug OPM programs. An event file is created even if the compiler completes the process without error.

*NOLSTDBG: A listing view or listing-level debugging information is not generated. Source-level error information will not be created unless *SRCDBG is specified.

*LSTDBG: The compiler generates a listing view, source-level error information, and listing-level debugging information for use with CoOperative Development Environment/400 (CODE/400). Source-level or listing-level debugging information is also necessary if you want to use the source-level debug function of the system debugger (STRDBG OPMSRC(*YES)) to debug OPM programs.

GENOPT
Specifies whether the intermediate representation of a program, a cross-reference list of objects defined in the intermediate representation of a program, an attribute list from the intermediate representation of a program, and the program template are printed, and whether a program patch area is included in the compiled program. This information may be required if a problem occurs in RPG/400*. This parameter also specifies whether program optimization is done.

Note: Up to three of the following values can be specified in any order on this parameter. If neither or both of the values in each group are specified, the underlined value will be used. The underlined values for this parameter are similar to, but not actually default values, and therefore, cannot be changed with the CHGCMDDFT (Change Command Default) command.

Listing Options

*NOLIST: An intermediate representation of the program listing is not created.

*LIST: An intermediate representation of the program is included in the compiler listing.

Cross-Reference Options

*NOXREF: No cross-reference list of variable and data item references in the intermediate representation of the program is created.

*XREF: A cross-reference listing of all objects defined in the intermediate representation of the program is produced.

Patch Options

*NOPATCH: No space is reserved in the compiled program for a program patch area.

*PATCH: Space is reserved in the compiled CL program for a program patch area.

USRPRF
Specifies whether the authority checking done while this program is running includes only the user who is running the program (*USER) or both the user running the program and the program owner (*OWNER). The profiles of the program user or both the program user and the program owner are used to control which objects can be used by the program, including the authority the program has for each object. Only the program owner or a user with QSECOFR authority can change the user profile attribute.

Note: This parameter will be ignored if REPLACE(*YES) is specified.

*USER: The program runs under the user profile of the program's user.

*OWNER: The user profiles of both the program's owner and the program's user are used when the program is processed. The collective sets of object authority in both user profiles are used to find and access objects during program processing. Authority from the owning user profile's group profile is not included in the authority for the running program.

LOG
Specifies the logging options for a created CL program.

*JOB: Logging of commands in a running CL program depends on the status of the job's logging flag (see the LOGCLPGM parameter of the Change Job (CHGJOB) command). To list the logged commands, the logging level of the jobs must be 3 or 4.

A *YES or *NO value takes precedence over any value specified in the CHGJOB command.

*YES: Commands are logged in all cases.

*NO: Commands are not logged.

ALWRTVSRC
Specifies whether the source for the CL program is saved with the program. This source can be retrieved later by using the Retrieve CL Source (RTVCLSRC) command.

*YES: The source for the CL program is saved with the program.

*NO: The source for the CL program is not saved with the program.

 

Notes

  1. If the RTVCLSRC command specifies a program that does not have the source saved with the program, a message is sent, and the RTVCLSRC command is not processed.

  2. Specifying ALWRTVSRC(*NO) does not prevent commands from being logged while a CL program is running. To prevent logging of commands in the program, LOG(*NO) must be specified on the CRTCLPGM command.


REPLACE
Specifies whether an existing program is replaced if a program with the same name already exists in the specified library.

*YES: Replace the existing program by moving it to the QRPLOBJ library.

 

Notes

  1. If a running CL program is recompiled with *YES specified for the REPLACE parameter, message queue errors may occur in the running CL program.

  2. Specifying *YES for this parameter will cause the values of USRPRF (user profile) and AUT (authority) parameters to be ignored. The existing program is used as the source of authority, and the user profile attribute is copied from the existing program to the new program. Use the Change Program (CHGPGM) command to change the user profile and the Grant Object Authority (GRTOBJAUT) or Revoke Object Authority (RVKOBJAUT) commands to change the authority for the program.

*NO: No replacement occurs.

TGTRLS
Specifies the release level of the operating system on which you intend to use the object being created.

When specifying the target-release value, the format VxRxMx is used to specify the release, where Vx is the version, Rx is the release, and Mx is the modification level. For example, V3R6M0 is version 3, release 6, modification level 0.

Valid values depend on the current version, release, and modification level, and they change with each new release. See the Valid Values for TGTRLS Parameter table in the Backup and recovery topic in the Information Center for a complete list of valid values.

*CURRENT: The program is to be used on the release of the operating system currently running on your system. The program can also be used on a system with any subsequent release of the operating system installed.

*PRV: The program is to be used on the previous release with modification level 0 of the operating system. The program can also be used on a system with any subsequent release of the operating system installed.

target-release: Specify the release in the format VxRxMx. The program can be used on a system with the specified release or with any subsequent release of the operating system installed.

AUT
Specifies the authority given to users who do not have specific authority to the command language program, who are not on an authorization list, and whose user group has no specific authority to the command language program. More information on this parameter is in Commonly used parameters.

Note: This parameter will be ignored if REPLACE(*YES) is specified.

*LIBCRTAUT: The public authority for the command language program is taken from the value on the CRTAUT parameter of the target library (the library that is to contain the command language program). The public authority is determined when the command language program is created. If the CRTAUT value for the library changes after the command language program is created, the new value does not affect any existing objects.

*CHANGE: The user can perform all operations on the object except those limited to the owner or controlled by object existence authority and object management authority. The user can change and perform basic functions on the object. Change authority provides object operational authority and all data authority. If the object is an authorization list, the user cannot add, change, or remove users.

*ALL: The user can perform all operations except those limited to the owner or controlled by authorization list management authority. The user can control the object's existence, specify the security for the object, change the object, and perform basic functions on the object. The user also can change ownership of the command language program.

*USE: The user can perform basic operations on the command language program, such as running a program or reading a file. The user cannot change the command language program. *USE authority provides object operational authority, read authority, and execute authority.

*EXCLUDE: The user cannot access the command language program.

authorization-list-name: Specify the name of the authorization list used.

SRTSEQ
Specifies the sort sequence table to be used for string comparisons for this CL program. The sort sequence is used with the language identifier and the coded character set identifier of the job to determine the sort sequence table to use.

Note: SRTSEQ(*HEX) must be specified when a previous release is specified on the TGTRLS parameter.

*HEX: A sort sequence table is not used. The hexadecimal values of the characters are used to determine the sort sequence.

*JOB: The sort sequence used is the SRTSEQ associated with the job when the CL program is created.

*JOBRUN: The sort sequence used is the SRTSEQ associated with the job when the CL program is run.

*LANGIDUNQ: A unique weight sort table is used. The sort sequence table must contain a unique weight for multiple characters and is the unique weight table associated with the language specified on the LANGID parameter.

*LANGIDSHR: A shared weight sort table is used. The sort sequence table can contain the same weight for multiple characters and is the shared weight table associated with the language specified on the LANGID parameter.

The name of the sort sequence table can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

table-name: Specify the name of the sort sequence table to be used with this CL program.

LANGID
Specifies the language identifier to be used when SRTSEQ(*LANGIDUNQ) or SRTSEQ(*LANGIDSHR) is specified.

*JOBRUN: The language ID used is the LANGID associated with the job when the CL program is run.

*JOB: The language ID used is the LANGID associated with the job when the CL program is created.

language-ID: Specify the language identifier to be used by the job.

TEXT
Specifies the text that briefly describes the compiled CL program. More information on this parameter is in Commonly used parameters.

*SRCMBRTXT: The text is taken from the source file member being used to create the CL program. If the source file is an inline file or a device file, the text is blank.

*BLANK: Text is not specified.

'description': Specify no more than 50 characters of text, enclosed in apostrophes.

Examples for CRTCLPGM

Example 1: Compiling a Program to be Run by Any System User 

CRTCLPGM   PAYROLL TEXT('Payroll Program')

This command calls the CL compiler to compile a program named PAYROLL. The source program is in the default source file QCLSRC in the member PAYROLL. A compiler listing is created. The program is processed under the program user's user profile and can be run by any system user.

Example 2: Compiling a Program to be Run by an Authorized User 

CRTCLPGM   PGM(PARTS)  SRCFILE(MYLIB/PARTDATA)
  AUT(*EXCLUDE)
  TEXT('This program displays all parts data')

This command creates a CL program named PARTS and stores it in the current library. The source for the program is in the PARTS member of the source file PARTDATA in the library MYLIB. A compiler listing is created. This program can be processed under the profile of the user that is running the program, who could be the owner or another user to which the owner has granted specific authorization by name in the Grant Object Authority (GRTOBJAUT) command.

Example 3: Compiling a Program to be Run on a Previous Release System 

CRTCLPGM   PGM(MYPGM)  SRCFILE(MYLIB/MYDATA)
  TGTRLS(*PRV)

This command creates a CL program that can be saved for a previous release system, restored on that system, and run on that system.

Error messages for CRTCLPGM

*ESCAPE Messages

CPF0C33
Target release &1 not valid.
CPF0C35
Target release &1 is not a supported release.
CPF0801
Program &1 not created.
CPF0804
Built-in function operands not valid. Reason code &1.
CPF0807
File containing compiler printout not opened.
CPF0808
Error in compiler-created code.
CPF0814
Licensed Program 5769-SS1 Option 9 not installed.
CPF0815
CL program &1 in &2 cannot be created for previous release.
CPF0816
%SWITCH mask &1 not valid.
CPF0849
Space addressing violation.
CPF3202
File &1 in library &2 in use.
CPF3203
Cannot allocate object for file &1 in &2.
CPF3224
Not authorized to perform operation on file &1.
EVF3140
The program's debug information was not created.